]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Run wrapcomments.py, release step 0c
authorMatthias Maier <tamiko@kyomu.43-1.org>
Mon, 15 Dec 2014 22:26:45 +0000 (23:26 +0100)
committerMatthias Maier <tamiko@kyomu.43-1.org>
Mon, 15 Dec 2014 22:26:45 +0000 (23:26 +0100)
311 files changed:
include/deal.II/algorithms/any_data.h
include/deal.II/algorithms/newton.h
include/deal.II/algorithms/operator.h
include/deal.II/algorithms/theta_timestepping.h
include/deal.II/algorithms/timestep_control.h
include/deal.II/base/aligned_vector.h
include/deal.II/base/auto_derivative_function.h
include/deal.II/base/conditional_ostream.h
include/deal.II/base/convergence_table.h
include/deal.II/base/data_out_base.h
include/deal.II/base/derivative_form.h
include/deal.II/base/event.h
include/deal.II/base/exceptions.h
include/deal.II/base/flow_function.h
include/deal.II/base/function.h
include/deal.II/base/function_derivative.h
include/deal.II/base/function_lib.h
include/deal.II/base/function_parser.h
include/deal.II/base/function_time.h
include/deal.II/base/geometry_info.h
include/deal.II/base/graph_coloring.h
include/deal.II/base/index_set.h
include/deal.II/base/iterator_range.h
include/deal.II/base/job_identifier.h
include/deal.II/base/logstream.h
include/deal.II/base/memory_consumption.h
include/deal.II/base/mg_level_object.h
include/deal.II/base/mpi.h
include/deal.II/base/multithread_info.h
include/deal.II/base/named_data.h
include/deal.II/base/numbers.h
include/deal.II/base/parallel.h
include/deal.II/base/parameter_handler.h
include/deal.II/base/parsed_function.h
include/deal.II/base/partitioner.h
include/deal.II/base/path_search.h
include/deal.II/base/point.h
include/deal.II/base/polynomial.h
include/deal.II/base/polynomial_space.h
include/deal.II/base/polynomials_abf.h
include/deal.II/base/polynomials_adini.h
include/deal.II/base/polynomials_bdm.h
include/deal.II/base/polynomials_nedelec.h
include/deal.II/base/polynomials_p.h
include/deal.II/base/polynomials_piecewise.h
include/deal.II/base/polynomials_raviart_thomas.h
include/deal.II/base/qprojector.h
include/deal.II/base/quadrature.h
include/deal.II/base/quadrature_lib.h
include/deal.II/base/quadrature_selector.h
include/deal.II/base/smartpointer.h
include/deal.II/base/subscriptor.h
include/deal.II/base/symmetric_tensor.h
include/deal.II/base/synchronous_iterator.h
include/deal.II/base/table.h
include/deal.II/base/table_handler.h
include/deal.II/base/table_indices.h
include/deal.II/base/template_constraints.h
include/deal.II/base/tensor.h
include/deal.II/base/tensor_base.h
include/deal.II/base/tensor_function.h
include/deal.II/base/tensor_product_polynomials.h
include/deal.II/base/tensor_product_polynomials_const.h
include/deal.II/base/thread_local_storage.h
include/deal.II/base/thread_management.h
include/deal.II/base/time_stepping.h
include/deal.II/base/timer.h
include/deal.II/base/types.h
include/deal.II/base/utilities.h
include/deal.II/base/vector_slice.h
include/deal.II/base/vectorization.h
include/deal.II/base/work_stream.h
include/deal.II/distributed/grid_refinement.h
include/deal.II/distributed/solution_transfer.h
include/deal.II/distributed/tria.h
include/deal.II/dofs/block_info.h
include/deal.II/dofs/dof_accessor.h
include/deal.II/dofs/dof_accessor.templates.h
include/deal.II/dofs/dof_faces.h
include/deal.II/dofs/dof_handler.h
include/deal.II/dofs/dof_handler_policy.h
include/deal.II/dofs/dof_iterator_selector.h
include/deal.II/dofs/dof_levels.h
include/deal.II/dofs/dof_objects.h
include/deal.II/dofs/dof_renumbering.h
include/deal.II/dofs/dof_tools.h
include/deal.II/dofs/function_map.h
include/deal.II/dofs/number_cache.h
include/deal.II/fe/block_mask.h
include/deal.II/fe/component_mask.h
include/deal.II/fe/fe.h
include/deal.II/fe/fe_abf.h
include/deal.II/fe/fe_base.h
include/deal.II/fe/fe_bdm.h
include/deal.II/fe/fe_dg_vector.h
include/deal.II/fe/fe_dgp.h
include/deal.II/fe/fe_dgp_monomial.h
include/deal.II/fe/fe_dgp_nonparametric.h
include/deal.II/fe/fe_dgq.h
include/deal.II/fe/fe_face.h
include/deal.II/fe/fe_nedelec.h
include/deal.II/fe/fe_nothing.h
include/deal.II/fe/fe_poly.h
include/deal.II/fe/fe_poly_face.h
include/deal.II/fe/fe_poly_tensor.h
include/deal.II/fe/fe_q.h
include/deal.II/fe/fe_q_base.h
include/deal.II/fe/fe_q_dg0.h
include/deal.II/fe/fe_q_hierarchical.h
include/deal.II/fe/fe_q_iso_q1.h
include/deal.II/fe/fe_raviart_thomas.h
include/deal.II/fe/fe_system.h
include/deal.II/fe/fe_tools.h
include/deal.II/fe/fe_trace.h
include/deal.II/fe/fe_update_flags.h
include/deal.II/fe/fe_values.h
include/deal.II/fe/fe_values_extractors.h
include/deal.II/fe/mapping.h
include/deal.II/fe/mapping_c1.h
include/deal.II/fe/mapping_cartesian.h
include/deal.II/fe/mapping_q.h
include/deal.II/fe/mapping_q1.h
include/deal.II/fe/mapping_q1_eulerian.h
include/deal.II/fe/mapping_q_eulerian.h
include/deal.II/grid/cell_id.h
include/deal.II/grid/filtered_iterator.h
include/deal.II/grid/grid_generator.h
include/deal.II/grid/grid_in.h
include/deal.II/grid/grid_out.h
include/deal.II/grid/grid_refinement.h
include/deal.II/grid/grid_reordering.h
include/deal.II/grid/grid_reordering_internal.h
include/deal.II/grid/grid_tools.h
include/deal.II/grid/intergrid_map.h
include/deal.II/grid/manifold.h
include/deal.II/grid/manifold_lib.h
include/deal.II/grid/persistent_tria.h
include/deal.II/grid/tria.h
include/deal.II/grid/tria_accessor.h
include/deal.II/grid/tria_accessor.templates.h
include/deal.II/grid/tria_boundary.h
include/deal.II/grid/tria_boundary_lib.h
include/deal.II/grid/tria_faces.h
include/deal.II/grid/tria_iterator.h
include/deal.II/grid/tria_iterator_base.h
include/deal.II/grid/tria_iterator_selector.h
include/deal.II/grid/tria_levels.h
include/deal.II/grid/tria_object.h
include/deal.II/grid/tria_objects.h
include/deal.II/hp/dof_faces.h
include/deal.II/hp/dof_handler.h
include/deal.II/hp/dof_level.h
include/deal.II/hp/fe_collection.h
include/deal.II/hp/fe_values.h
include/deal.II/hp/mapping_collection.h
include/deal.II/hp/q_collection.h
include/deal.II/integrators/advection.h
include/deal.II/integrators/divergence.h
include/deal.II/integrators/elasticity.h
include/deal.II/integrators/l2.h
include/deal.II/integrators/laplace.h
include/deal.II/integrators/local_integrators.h
include/deal.II/integrators/maxwell.h
include/deal.II/lac/arpack_solver.h
include/deal.II/lac/block_indices.h
include/deal.II/lac/block_list.h
include/deal.II/lac/block_matrix.h
include/deal.II/lac/block_matrix_array.h
include/deal.II/lac/block_matrix_base.h
include/deal.II/lac/block_sparse_matrix.h
include/deal.II/lac/block_sparse_matrix_ez.h
include/deal.II/lac/block_sparsity_pattern.h
include/deal.II/lac/block_vector.h
include/deal.II/lac/block_vector_base.h
include/deal.II/lac/chunk_sparse_matrix.h
include/deal.II/lac/chunk_sparse_matrix.templates.h
include/deal.II/lac/chunk_sparsity_pattern.h
include/deal.II/lac/compressed_set_sparsity_pattern.h
include/deal.II/lac/compressed_simple_sparsity_pattern.h
include/deal.II/lac/compressed_sparsity_pattern.h
include/deal.II/lac/constraint_matrix.h
include/deal.II/lac/constraint_matrix.templates.h
include/deal.II/lac/eigen.h
include/deal.II/lac/exceptions.h
include/deal.II/lac/filtered_matrix.h
include/deal.II/lac/full_matrix.h
include/deal.II/lac/generic_linear_algebra.h
include/deal.II/lac/householder.h
include/deal.II/lac/identity_matrix.h
include/deal.II/lac/iterative_inverse.h
include/deal.II/lac/lapack_full_matrix.h
include/deal.II/lac/lapack_support.h
include/deal.II/lac/matrix_block.h
include/deal.II/lac/matrix_iterator.h
include/deal.II/lac/matrix_lib.h
include/deal.II/lac/matrix_out.h
include/deal.II/lac/parallel_block_vector.h
include/deal.II/lac/parallel_vector.h
include/deal.II/lac/petsc_block_sparse_matrix.h
include/deal.II/lac/petsc_block_vector.h
include/deal.II/lac/petsc_full_matrix.h
include/deal.II/lac/petsc_matrix_base.h
include/deal.II/lac/petsc_matrix_free.h
include/deal.II/lac/petsc_parallel_block_sparse_matrix.h
include/deal.II/lac/petsc_parallel_block_vector.h
include/deal.II/lac/petsc_parallel_sparse_matrix.h
include/deal.II/lac/petsc_parallel_vector.h
include/deal.II/lac/petsc_precondition.h
include/deal.II/lac/petsc_solver.h
include/deal.II/lac/petsc_sparse_matrix.h
include/deal.II/lac/petsc_vector.h
include/deal.II/lac/petsc_vector_base.h
include/deal.II/lac/pointer_matrix.h
include/deal.II/lac/precondition.h
include/deal.II/lac/precondition_block.h
include/deal.II/lac/precondition_block_base.h
include/deal.II/lac/precondition_selector.h
include/deal.II/lac/relaxation_block.h
include/deal.II/lac/schur_matrix.h
include/deal.II/lac/shifted_matrix.h
include/deal.II/lac/slepc_solver.h
include/deal.II/lac/slepc_spectral_transformation.h
include/deal.II/lac/solver.h
include/deal.II/lac/solver_bicgstab.h
include/deal.II/lac/solver_cg.h
include/deal.II/lac/solver_control.h
include/deal.II/lac/solver_gmres.h
include/deal.II/lac/solver_minres.h
include/deal.II/lac/solver_qmrs.h
include/deal.II/lac/solver_relaxation.h
include/deal.II/lac/solver_richardson.h
include/deal.II/lac/solver_selector.h
include/deal.II/lac/sparse_decomposition.h
include/deal.II/lac/sparse_direct.h
include/deal.II/lac/sparse_ilu.h
include/deal.II/lac/sparse_matrix.h
include/deal.II/lac/sparse_matrix.templates.h
include/deal.II/lac/sparse_matrix_ez.h
include/deal.II/lac/sparse_mic.h
include/deal.II/lac/sparse_vanka.h
include/deal.II/lac/sparsity_pattern.h
include/deal.II/lac/sparsity_tools.h
include/deal.II/lac/swappable_vector.h
include/deal.II/lac/transpose_matrix.h
include/deal.II/lac/tridiagonal_matrix.h
include/deal.II/lac/trilinos_block_sparse_matrix.h
include/deal.II/lac/trilinos_block_vector.h
include/deal.II/lac/trilinos_parallel_block_vector.h
include/deal.II/lac/trilinos_precondition.h
include/deal.II/lac/trilinos_solver.h
include/deal.II/lac/trilinos_sparse_matrix.h
include/deal.II/lac/trilinos_sparsity_pattern.h
include/deal.II/lac/trilinos_vector.h
include/deal.II/lac/trilinos_vector_base.h
include/deal.II/lac/vector.h
include/deal.II/lac/vector_memory.h
include/deal.II/lac/vector_view.h
include/deal.II/matrix_free/dof_info.h
include/deal.II/matrix_free/fe_evaluation.h
include/deal.II/matrix_free/helper_functions.h
include/deal.II/matrix_free/mapping_data_on_the_fly.h
include/deal.II/matrix_free/mapping_info.h
include/deal.II/matrix_free/matrix_free.h
include/deal.II/matrix_free/operators.h
include/deal.II/matrix_free/shape_info.h
include/deal.II/meshworker/assembler.h
include/deal.II/meshworker/dof_info.h
include/deal.II/meshworker/functional.h
include/deal.II/meshworker/integration_info.h
include/deal.II/meshworker/local_integrator.h
include/deal.II/meshworker/local_results.h
include/deal.II/meshworker/loop.h
include/deal.II/meshworker/output.h
include/deal.II/meshworker/simple.h
include/deal.II/meshworker/vector_selector.h
include/deal.II/multigrid/mg_base.h
include/deal.II/multigrid/mg_block_smoother.h
include/deal.II/multigrid/mg_coarse.h
include/deal.II/multigrid/mg_constrained_dofs.h
include/deal.II/multigrid/mg_dof_handler.h
include/deal.II/multigrid/mg_dof_iterator_selector.h
include/deal.II/multigrid/mg_matrix.h
include/deal.II/multigrid/mg_smoother.h
include/deal.II/multigrid/mg_tools.h
include/deal.II/multigrid/mg_transfer.h
include/deal.II/multigrid/mg_transfer.templates.h
include/deal.II/multigrid/mg_transfer_block.h
include/deal.II/multigrid/mg_transfer_component.h
include/deal.II/multigrid/multigrid.h
include/deal.II/multigrid/sparse_matrix_collection.h
include/deal.II/numerics/data_component_interpretation.h
include/deal.II/numerics/data_out.h
include/deal.II/numerics/data_out_dof_data.h
include/deal.II/numerics/data_out_faces.h
include/deal.II/numerics/data_out_rotation.h
include/deal.II/numerics/data_out_stack.h
include/deal.II/numerics/data_postprocessor.h
include/deal.II/numerics/derivative_approximation.h
include/deal.II/numerics/dof_output_operator.h
include/deal.II/numerics/dof_print_solver_step.h
include/deal.II/numerics/error_estimator.h
include/deal.II/numerics/fe_field_function.h
include/deal.II/numerics/histogram.h
include/deal.II/numerics/matrix_tools.h
include/deal.II/numerics/point_value_history.h
include/deal.II/numerics/solution_transfer.h
include/deal.II/numerics/time_dependent.h
include/deal.II/numerics/vector_tools.h
include/deal.II/numerics/vector_tools.templates.h
include/deal.II/opencascade/boundary_lib.h
include/deal.II/opencascade/utilities.h

index d3f60edd5a387011c29006f50cd370b2ac57c5c7..95bbb3df32bc3bf339c41ed7ff1d99804736cc68 100644 (file)
@@ -31,8 +31,8 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Store any amount of any type of data accessible by an identifier string.
  *
- * @todo Deprecate access by index after NamedData has been deprecated
- * for long enough, then change to a map.
+ * @todo Deprecate access by index after NamedData has been deprecated for
+ * long enough, then change to a map.
  */
 class AnyData :
   public Subscriptor
@@ -56,11 +56,10 @@ public:
   /**
    * @brief Access to stored data object by name.
    *
-   * Find the object with given name, try to convert it to
-   * <tt>type</tt> and return it. This function throws an exception
-   * if either the name does not exist or if the conversion
-   * fails. If such an exception is not desired, use try_read()
-   * instead.
+   * Find the object with given name, try to convert it to <tt>type</tt> and
+   * return it. This function throws an exception if either the name does not
+   * exist or if the conversion fails. If such an exception is not desired,
+   * use try_read() instead.
    */
   template <typename type>
   type entry (const std::string &name);
@@ -68,11 +67,10 @@ public:
   /**
    * @brief Read-only access to stored data object by name.
    *
-   * Find the object with given name, try to convert it to
-   * <tt>type</tt> and return it. This function throws an exception
-   * if either the name does not exist or if the conversion
-   * fails. If such an exception is not desired, use try_read()
-   * instead.
+   * Find the object with given name, try to convert it to <tt>type</tt> and
+   * return it. This function throws an exception if either the name does not
+   * exist or if the conversion fails. If such an exception is not desired,
+   * use try_read() instead.
    */
   template <typename type>
   const type entry (const std::string &name) const;
@@ -80,14 +78,13 @@ public:
   /**
    * @brief Dedicated read only access by name.
    *
-   * For a constant object, this function equals entry(). For a
-   * non-const object, it forces read only access to the data. In
-   * particular, it throws an exception if the object is not found
-   * or cannot be converted to type.  If such an exception is not
-   * desired, use try_read() instead.
+   * For a constant object, this function equals entry(). For a non-const
+   * object, it forces read only access to the data. In particular, it throws
+   * an exception if the object is not found or cannot be converted to type.
+   * If such an exception is not desired, use try_read() instead.
    *
-   * @warning Do not use this function for stored objects which are
-   * pointers. Use read_ptr() instead!
+   * @warning Do not use this function for stored objects which are pointers.
+   * Use read_ptr() instead!
    */
   template <typename type>
   const type read (const std::string &name) const;
@@ -95,19 +92,18 @@ public:
   /**
    * @brief Dedicated read only access by name for pointer data.
    *
-   * If the stored data object is a pointer to a constant object, the logic
-   * of access becomes fairly complicated. Namely, the standard read
-   * function may fail, depending on whether it was a const pointer
-   * or a regular pointer. This function fixes the logic and
-   * ascertains that the object does not become mutable by accident.
+   * If the stored data object is a pointer to a constant object, the logic of
+   * access becomes fairly complicated. Namely, the standard read function may
+   * fail, depending on whether it was a const pointer or a regular pointer.
+   * This function fixes the logic and ascertains that the object does not
+   * become mutable by accident.
    */
   template <typename type>
   const type *read_ptr (const std::string &name) const;
 
   /**
-   * Perform the same action as read_ptr(), but do not throw an
-   * exception if the pointer does not exist. Return a null pointer
-   * instead.
+   * Perform the same action as read_ptr(), but do not throw an exception if
+   * the pointer does not exist. Return a null pointer instead.
    */
   template <typename type>
   const type *try_read_ptr (const std::string &name) const;
@@ -115,10 +111,9 @@ public:
   /**
    * @brief Dedicated read only access by name without exceptions.
    *
-   * This function tries to find the name in the list and return a
-   * pointer to the associated object. If either the name is not
-   * found or the object cannot be converted to the return type, a
-   * null pointer is returned.
+   * This function tries to find the name in the list and return a pointer to
+   * the associated object. If either the name is not found or the object
+   * cannot be converted to the return type, a null pointer is returned.
    */
   template <typename type>
   const type *try_read (const std::string &name) const;
@@ -155,17 +150,16 @@ public:
   /**
    * @brief Find index of a named object
    *
-   * Try to find the objecty and return its index in the list. Throw
-   * an exception if the object has not been found.
+   * Try to find the objecty and return its index in the list. Throw an
+   * exception if the object has not been found.
    */
   unsigned int find(const std::string &name) const;
 
   /**
    * @brief Try to find index of a named object
    *
-   * Try to find the objecty and return its index in the
-   * list. returns numbers::invalid_unsigned_int if the name was not
-   * found.
+   * Try to find the objecty and return its index in the list. returns
+   * numbers::invalid_unsigned_int if the name was not found.
    */
   unsigned int try_find(const std::string &name) const;
 
@@ -193,9 +187,8 @@ public:
                  << " must coincide");
 
   /**
-   * Exception indicating that a function expected a vector to have a
-   * certain name, but NamedData had a different name in that
-   * position.
+   * Exception indicating that a function expected a vector to have a certain
+   * name, but NamedData had a different name in that position.
    */
   DeclException2(ExcNameMismatch, int, std::string,
                  << "Name at position " << arg1 << " is not equal to " << arg2);
index c06d026bbf8966f107c2e9de46800654b1c758a3..d8ec3683ef23d68753210e375c29b8868dc4fa5e 100644 (file)
@@ -29,36 +29,34 @@ class ParameterHandler;
 namespace Algorithms
 {
   /**
-   * Operator class performing Newton's iteration with standard step
-   * size control and adaptive matrix generation.
+   * Operator class performing Newton's iteration with standard step size
+   * control and adaptive matrix generation.
    *
-   * This class performs a Newton iteration up to convergence
-   * determined by #control. If after an update the norm of the residual
-   * has become larger, then step size control is activated and the
-   * update is subsequently divided by two until the residual actually
-   * becomes smaller (or the minimal scaling factor determined by
-   * #n_stepsize_iterations is reached).
+   * This class performs a Newton iteration up to convergence determined by
+   * #control. If after an update the norm of the residual has become larger,
+   * then step size control is activated and the update is subsequently
+   * divided by two until the residual actually becomes smaller (or the
+   * minimal scaling factor determined by #n_stepsize_iterations is reached).
    *
-   * Since assembling matrices, depending on the implementation, tends
-   * to be costly, this method applies an adaptive reassembling
-   * strategy. Only if the reduction factor for the residual is more
-   * than #threshold, the event Algorithms::bad_derivative is submitted to
-   * #inverse_derivative. It is up to this object to implement
-   * reassembling accordingly.
+   * Since assembling matrices, depending on the implementation, tends to be
+   * costly, this method applies an adaptive reassembling strategy. Only if
+   * the reduction factor for the residual is more than #threshold, the event
+   * Algorithms::bad_derivative is submitted to #inverse_derivative. It is up
+   * to this object to implement reassembling accordingly.
    *
    * <h3>Contents of the AnyData 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.
+   * 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.
+   * 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>.
@@ -70,10 +68,8 @@ namespace Algorithms
   {
   public:
     /**
-     * Constructor, receiving the
-     * applications computing the
-     * residual and solving the
-     * linear problem, respectively.
+     * Constructor, receiving the applications computing the residual and
+     * solving the linear problem, respectively.
      */
     Newton (Operator<VECTOR> &residual, Operator<VECTOR> &inverse_derivative);
 
@@ -93,20 +89,14 @@ namespace Algorithms
     void initialize (ParameterHandler &param) DEAL_II_DEPRECATED;
 
     /**
-     * Initialize the pointer
-     * data_out for debugging.
+     * Initialize the pointer data_out for debugging.
      */
     void initialize (OutputOperator<VECTOR> &output);
 
     /**
-     * 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
+     * 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() (AnyData &out, const AnyData &in);
@@ -119,17 +109,13 @@ namespace Algorithms
     virtual void notify(const Event &);
 
     /**
-     * Set the maximal residual
-     * reduction allowed without
-     * triggering assembling in the
-     * next step. Return the
-     * previous value.
+     * Set the maximal residual reduction allowed without triggering
+     * assembling in the next step. Return the previous value.
      */
     double threshold(double new_value);
 
     /**
-     * Control object for the
-     * Newton iteration.
+     * Control object for the Newton iteration.
      */
     ReductionControl control;
   private:
@@ -139,73 +125,55 @@ namespace Algorithms
     SmartPointer<Operator<VECTOR>, Newton<VECTOR> > residual;
 
     /**
-     * The operator applying the
-     * inverse derivative to the residual.
+     * The operator applying the inverse derivative to the residual.
      */
     SmartPointer<Operator<VECTOR>, Newton<VECTOR> > inverse_derivative;
 
     /**
-     * The operator handling the output
-     * in case the debug_vectors is true.
+     * The operator handling the output in case the debug_vectors is true.
      * Call the initialize function first.
      */
     SmartPointer<OutputOperator<VECTOR>, Newton<VECTOR> > data_out;
 
     /**
-     * This flag is set by the
-     * function assemble(),
-     * indicating that the matrix
-     * must be assembled anew upon
-     * start.
+     * This flag is set by the function assemble(), indicating that the matrix
+     * must be assembled anew upon start.
      */
     bool assemble_now;
 
     /**
-     * A flag used to decide how
-     * many stepsize iteration
-     * should be made. Default is
-     * the original value of 21.
+     * A flag used to decide how many stepsize iteration should be made.
+     * Default is the original value of 21.
      *
-     * Enter zero here to turn of
-     * stepsize control.
+     * Enter zero here to turn of stepsize control.
      *
-     * @note Controlled by
-     * <tt>Stepsize iterations</tt> in
-     * parameter file
+     * @note Controlled by <tt>Stepsize iterations</tt> in parameter file
      */
     unsigned int n_stepsize_iterations;
 
     /**
      * Threshold for re-assembling matrix.
      *
-     * If the quotient of two
-     * consecutive residuals is
-     * smaller than this threshold,
-     * the system matrix is not
-     * assembled in this step.
+     * If the quotient of two consecutive residuals is smaller than this
+     * threshold, the system matrix is not assembled in this step.
      *
-     * @note This parameter should be
-     * adjusted to the residual gain
-     * of the inner solver.
+     * @note This parameter should be adjusted to the residual gain of the
+     * inner solver.
      *
-     * The default values is zero,
-     * resulting in reassembling in
-     * every Newton step.
+     * The default values is zero, resulting in reassembling in every Newton
+     * step.
      */
     double assemble_threshold;
 
   public:
     /**
-     * Print residual, update and
-     * updated solution after each
-     * step into file
+     * Print residual, update and updated solution after each step into file
      * <tt>Newton_NNN</tt>?
      */
     bool debug_vectors;
     /**
-     * Write debug output to
-     * @p deallog; the higher the
-     * number, the more output.
+     * Write debug output to @p deallog; the higher the number, the more
+     * output.
      */
     unsigned int debug;
   };
index 09315f2968fc97825c73c19e706e969d6be6c60b..8aa19246911c50146d85e504676502ccf165074b 100644 (file)
@@ -29,10 +29,10 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Namespace containing numerical algorithms in a unified form.
  *
- * All algorithmic classes in this namespace are derived from either
- * Operator or OutputOperator, depending on whether they return a
- * value or not. See the documentation of those classes for more
- * detailed information on how to use them.
+ * All algorithmic classes in this namespace are derived from either Operator
+ * or OutputOperator, depending on whether they return a value or not. See the
+ * documentation of those classes for more detailed information on how to use
+ * them.
  *
  * @author Guido Kanschat
  * @date 2012, 2013
@@ -42,30 +42,28 @@ namespace Algorithms
   /**
    * @todo Update this documentation and the one of Operator
    *
-   * The abstract base class of all algorithms in this library. An
-   * operator is an object with an operator(), which transforms a set
-   * of named vectors into another set of named vectors.
+   * The abstract base class of all algorithms in this library. An operator is
+   * an object with an operator(), which transforms a set of named vectors
+   * into another set of named vectors.
    *
-   * Furthermore, an operator can be notified of parameter changes by
-   * the calling routine. The outer iteration can notify() the Operator
-   * of an Event, which could be for instance a change of mesh, a
-   * different time step size or too slow convergence of Newton's
-   * method, which would then trigger reassembling of a matrix or
-   * similar things.
+   * Furthermore, an operator can be notified of parameter changes by the
+   * calling routine. The outer iteration can notify() the Operator of an
+   * Event, which could be for instance a change of mesh, a different time
+   * step size or too slow convergence of Newton's 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 AnyData 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.
+   * 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
+   * AnyData 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
    * @date 2014
@@ -79,14 +77,12 @@ namespace Algorithms
     ~OperatorBase();
 
     /**
-     * The actual operation, which
-     * is implemented in a derived class.
+     * The actual operation, which is implemented in a derived class.
      */
     virtual void operator() (AnyData &out, const AnyData &in) = 0;
 
     /**
-     * Register an event triggered
-     * by an outer iteration.
+     * Register an event triggered by an outer iteration.
      */
     virtual void notify(const Event &);
     /**
@@ -95,11 +91,8 @@ namespace Algorithms
     void clear_events();
   protected:
     /**
-     * Accumulate events here. If any of
-     * those is set, the function
-     * solve() of a terminal
-     * application must take care
-     * of reassembling the matrix.
+     * Accumulate events here. If any of those is set, the function solve() of
+     * a terminal application must take care of reassembling the matrix.
      */
     Event notifications;
 
@@ -108,30 +101,28 @@ namespace Algorithms
   /**
    * @deprecated This class has been replaced by OperatorBase.
    *
-   * The abstract base class of all algorithms in this library. An
-   * operator is an object with an operator(), which transforms a set
-   * of named vectors into another set of named vectors.
+   * The abstract base class of all algorithms in this library. An operator is
+   * an object with an operator(), which transforms a set of named vectors
+   * into another set of named vectors.
    *
-   * Furthermore, an operator can be notified of parameter changes by
-   * the calling routine. The outer iteration can notify() the Operator
-   * of an Event, which could be for instance a change of mesh, a
-   * different time step size or too slow convergence of Newton's
-   * method, which would then trigger reassembling of a matrix or
-   * similar things.
+   * Furthermore, an operator can be notified of parameter changes by the
+   * calling routine. The outer iteration can notify() the Operator of an
+   * Event, which could be for instance a change of mesh, a different time
+   * step size or too slow convergence of Newton's 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.
+   * 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
    */
@@ -143,16 +134,15 @@ namespace Algorithms
 
     /**
      * Implementation of the function in the base class in order to do
-     * compatibility conversions between the old and the new
-     * interface.
+     * compatibility conversions between the old and the new interface.
      */
     virtual void operator() (AnyData &out, const AnyData &in);
 
     /**
-     * @deprecated It is in particular this function which should not be used anymore.
+     * @deprecated It is in particular this function which should not be used
+     * anymore.
      *
-     * The actual operation, which
-     * is implemented in a derived class.
+     * The actual operation, which is implemented in a derived class.
      */
     virtual void operator() (NamedData<VECTOR *> &out, const NamedData<VECTOR *> &in);
 
@@ -163,15 +153,15 @@ namespace Algorithms
 
   private:
     /**
-     * While we are providing compatibility functions to the old
-     * interface, this variable will ensure there is no endless loop.
+     * While we are providing compatibility functions to the old interface,
+     * this variable will ensure there is no endless loop.
      */
     bool compatibility_flag;
   };
 
   /**
-   * An unary operator base class, intended to output the vectors in
-   * NamedData in each step of an iteration.
+   * An unary operator base class, intended to output the vectors in NamedData
+   * in each step of an iteration.
    *
    * @author Guido Kanschat, 2010
    */
@@ -187,11 +177,8 @@ namespace Algorithms
     virtual ~OutputOperator();
 
     /**
-     * Set the stream @p os to
-     * which data is written. If
-     * no stream is selected with
-     * this function, data goes
-     * to @p deallog.
+     * Set the stream @p os to which data is written. If no stream is selected
+     * with this function, data goes to @p deallog.
      */
     void initialize_stream(std::ostream &stream);
     /**
index 77e8f0b796b3ce22053a9c31a83ff26789ca58d6..e24c3a01944c95062453b820ee4cf84be3068457 100644 (file)
@@ -28,14 +28,13 @@ class ParameterHandler;
 namespace Algorithms
 {
   /**
-   * A little structure, gathering the size of a timestep and the
-   * current time. Time stepping schemes can use this to provide time
-   * step information to the classes actually performing a single step.
+   * A little structure, gathering the size of a timestep and the current
+   * time. Time stepping schemes can use this to provide time step information
+   * to the classes actually performing a single step.
    *
    * The definition of what is considered "current time" depends on the
-   * scheme. For an explicit scheme, this is the time at the beginning
-   * of the step. For an implicit scheme, it is usually the time at the
-   * end.
+   * scheme. For an explicit scheme, this is the time at the beginning of the
+   * step. For an implicit scheme, it is usually the time at the end.
    */
   struct TimestepData
   {
@@ -49,20 +48,20 @@ namespace Algorithms
    * Application class performing the theta timestepping scheme.
    *
    * The theta scheme is an abstraction of implicit and explicit Euler
-   * schemes, the Crank-Nicholson scheme and linear combinations of
-   * those. The choice of the actual scheme is controlled by the
-   * parameter #theta as follows.
+   * schemes, the Crank-Nicholson scheme and linear combinations of those. The
+   * choice of the actual scheme is controlled by the parameter #theta as
+   * follows.
    * <ul>
    * <li> #theta=0: explicit Euler scheme
    * <li> #theta=1: implicit Euler scheme
    * <li> #theta=½: Crank-Nicholson scheme
    * </ul>
    *
-   * For fixed #theta, the Crank-Nicholson scheme is the only second
-   * order scheme. Nevertheless, further stability may be achieved by
-   * choosing #theta larger than ½, thereby introducing a first order
-   * error term. In order to avoid a loss of convergence order, the
-   * adaptive theta scheme can be used, where <i>#theta=½+c dt</i>.
+   * For fixed #theta, the Crank-Nicholson scheme is the only second order
+   * scheme. Nevertheless, further stability may be achieved by choosing
+   * #theta larger than ½, thereby introducing a first order error term. In
+   * order to avoid a loss of convergence order, the adaptive theta scheme can
+   * be used, where <i>#theta=½+c dt</i>.
    *
    * Assume that we want to solve the equation <i>u' + F(u) = 0</i> with a
    * step size <i>k</i>.  A step of the theta scheme can be written as
@@ -72,132 +71,118 @@ namespace Algorithms
    * @f]
    *
    * Here, <i>M</i> is the mass matrix. We see, that the right hand side
-   * amounts to an explicit Euler step with modified step size in weak
-   * form (up to inversion of M). The left hand side corresponds to an
-   * implicit Euler step with modified step size (right hand side
-   * given). Thus, the implementation of the theta scheme will use two
-   * Operator objects, one for the explicit, one for the implicit
-   * part. Each of these will use its own TimestepData to account for
-   * the modified step sizes (and different times if the problem is not
-   * autonomous). Note that once the explicit part has been computed,
-   * the left hand side actually constitutes a linear or nonlinear
-   * system which has to be solved.
+   * amounts to an explicit Euler step with modified step size in weak form
+   * (up to inversion of M). The left hand side corresponds to an implicit
+   * Euler step with modified step size (right hand side given). Thus, the
+   * implementation of the theta scheme will use two Operator objects, one for
+   * the explicit, one for the implicit part. Each of these will use its own
+   * TimestepData to account for the modified step sizes (and different times
+   * if the problem is not autonomous). Note that once the explicit part has
+   * been computed, the left hand side actually constitutes a linear or
+   * nonlinear system which has to be solved.
    *
    * <h3>Usage AnyData</h3>
    *
-   * ThetaTimestepping uses AnyData for communicating vectors and time
-   * step information. With
-   * outer or inner Operator objects. It does not use itself the input
-   * vectors provided, but forwards them to the explicit and implicit
-   * operators.
+   * ThetaTimestepping uses AnyData for communicating vectors and time step
+   * information. With outer or inner Operator objects. It does not use itself
+   * the input vectors provided, but forwards them to the explicit and
+   * implicit operators.
    *
    * <h4>Vector data</h4>
    *
-   * The explicit Operator #op_explicit receives in its input in first
-   * place the vector "Previous iterate", which is the solution
-   * value after the previous timestep. It is followed by all vectors
-   * provided to ThetaTimestepping::operator() as input
-   * argument. #op_explicit is supposed to write its result into the
-   * first position of its output argument, labeled "Result".
+   * The explicit Operator #op_explicit receives in its input in first place
+   * the vector "Previous iterate", which is the solution value after the
+   * previous timestep. It is followed by all vectors provided to
+   * ThetaTimestepping::operator() as input argument. #op_explicit is supposed
+   * to write its result into the first position of its output argument,
+   * labeled "Result".
    *
-   * The implicit Operator #op_implicit receives the result of
-   * #op_explicit in its first input vector labeled "Previous
-   * time". It is followed by all vectors provided to
-   * ThetaTimestepping::operator() as input argument. The output of
-   * #op_implicit is directly written into the output argument given to
-   * ThetaTimestepping.
+   * The implicit Operator #op_implicit receives the result of #op_explicit in
+   * its first input vector labeled "Previous time". It is followed by all
+   * vectors provided to ThetaTimestepping::operator() as input argument. The
+   * output of #op_implicit is directly written into the output argument given
+   * to ThetaTimestepping.
    *
    * <h4>Scalar data</h4>
    *
    * Since the introduction of AnyData, ThetaTimestepping is able to
-   * communicate the current time step information through AnyData as
-   * well. Therefore, the AnyData objects handed as input to
-   * #op_explicit and #op_implicit contain two entries of type
-   * `const double*` named "Time" and "Timestep". Note
-   * that "Time" refers to the time at the beginning of the current
-   * step for #op_explicit and at the end for #op_implicit,
+   * communicate the current time step information through AnyData as well.
+   * Therefore, the AnyData objects handed as input to #op_explicit and
+   * #op_implicit contain two entries of type `const double*` named "Time" and
+   * "Timestep". Note that "Time" refers to the time at the beginning of the
+   * current step for #op_explicit and at the end for #op_implicit,
    * respectively.
    *
    * <h3>Usage of ThetaTimestepping</h3>
    *
-   * The use ThetaTimestepping is more complicated than for instance
-   * Newton, since the inner operators will usually need to access the
-   * TimeStepData. Thus, we have a circular dependency of information,
-   * and we include the following example for its use. It can be found
-   * in <tt>examples/doxygen/theta_timestepping.cc</tt>
+   * The use ThetaTimestepping is more complicated than for instance Newton,
+   * since the inner operators will usually need to access the TimeStepData.
+   * Thus, we have a circular dependency of information, and we include the
+   * following example for its use. It can be found in
+   * <tt>examples/doxygen/theta_timestepping.cc</tt>
    *
    * @dontinclude theta_timestepping.cc
    *
-   * First, we define the two operators used by ThetaTimestepping and
-   * call them <code>Implicit</code> and <code>Explicit</code>. They
-   * both share the public interface of Operator, and additionally
-   * provide storage for the matrices to be used and a pointer to
-   * TimestepData. Note that we do not use a SmartPointer here, since
-   * the TimestepData will be destroyed before the operator.
+   * First, we define the two operators used by ThetaTimestepping and call
+   * them <code>Implicit</code> and <code>Explicit</code>. They both share the
+   * public interface of Operator, and additionally provide storage for the
+   * matrices to be used and a pointer to TimestepData. Note that we do not
+   * use a SmartPointer here, since the TimestepData will be destroyed before
+   * the operator.
    *
-   * @skip class Explicit
-   * @until End of declarations
+   * @skip class Explicit @until End of declarations
    *
-   * These operators will be implemented after the main program. But let
-   * us look first at how they get used. First, let us define a matrix to be
-   * used for our system and also an OutputOperator in order to write
-   * the data of each timestep to a file.
+   * These operators will be implemented after the main program. But let us
+   * look first at how they get used. First, let us define a matrix to be used
+   * for our system and also an OutputOperator in order to write the data of
+   * each timestep to a file.
    *
-   * @skipline main
-   * @until out.initialize
+   * @skipline main @until out.initialize
    *
-   * Now we create objects for the implicit and explicit parts of the
-   * steps as well as the ThetaTimestepping itself. We initialize the
-   * timestepping with the output operator in order to be able to see
-   * the output in every step.
+   * Now we create objects for the implicit and explicit parts of the steps as
+   * well as the ThetaTimestepping itself. We initialize the timestepping with
+   * the output operator in order to be able to see the output in every step.
    *
    * @until set_output
    *
-   * The next step is providing the vectors to be used. <tt>value</tt>
-   * is filled with the initial value and is also the vector where the
-   * solution at each timestep will be. Because the interface of
-   * Operator has to be able to handle several vectors, we need to store
-   * it in an AnyData object. Since our problem has no additional
-   * parameters, the input AnyData object remains empty.
+   * The next step is providing the vectors to be used. <tt>value</tt> is
+   * filled with the initial value and is also the vector where the solution
+   * at each timestep will be. Because the interface of Operator has to be
+   * able to handle several vectors, we need to store it in an AnyData object.
+   * Since our problem has no additional parameters, the input AnyData object
+   * remains empty.
    *
    * @until add
    *
-   * Finally, we are ready to tell the solver, that we are starting at
-   * the initial timestep and run it.
+   * Finally, we are ready to tell the solver, that we are starting at the
+   * initial timestep and run it.
    *
    * @until }
    *
-   * First the constructor, which simply copies the system matrix into
-   * the member pointer for later use.
+   * First the constructor, which simply copies the system matrix into the
+   * member pointer for later use.
    *
-   * @skip Explicit::
-   * @until }
+   * @skip Explicit:: @until }
    *
    * Now we need to study the application of the implicit and explicit
-   * operator. We assume that the pointer <code>matrix</code> points to
-   * the matrix created in the main program (the constructor did this
-   * for us). Here, we first get the time step size from the AnyData
-   * object that was provided as input. Then, if we are in the first
-   * step or if the timestep has changed, we fill the local matrix
-   * $m$, such that with the given matrix $M$, it becomes
-   * \f[
-   * m = I - \Delta t M.
-   * \f]
-   * After we have worked off the notifications, we clear them, such
-   * that the matrix is only generated when necessary.
-   *
-   * @skipline void
-   * @until clear
+   * operator. We assume that the pointer <code>matrix</code> points to the
+   * matrix created in the main program (the constructor did this for us).
+   * Here, we first get the time step size from the AnyData object that was
+   * provided as input. Then, if we are in the first step or if the timestep
+   * has changed, we fill the local matrix $m$, such that with the given
+   * matrix $M$, it becomes \f[ m = I - \Delta t M. \f] After we have worked
+   * off the notifications, we clear them, such that the matrix is only
+   * generated when necessary.
+   *
+   * @skipline void @until clear
    *
    * Now we multiply the input vector with the new matrix and store on output.
    *
-   * @until }
-   * The code for the implicit operator is almost the same, except
-   * that we change the sign in front of the timestep and use the
-   * inverse of t he matrix.
+   * @until } The code for the implicit operator is almost the same, except
+   * that we change the sign in front of the timestep and use the inverse of t
+   * he matrix.
    *
-   * @until vmult
-   * @until }
+   * @until vmult @until }
    * @author Guido Kanschat
    * @date 2010
    */
@@ -206,11 +191,9 @@ namespace Algorithms
   {
   public:
     /**
-     * Constructor, receiving the
-     * two operators stored in
-     * #op_explicit and #op_implicit. For
-     * their meening, see the
-     * description of those variables.
+     * Constructor, receiving the two operators stored in #op_explicit and
+     * #op_implicit. For their meening, see the description of those
+     * variables.
      */
     ThetaTimestepping (Operator<VECTOR> &op_explicit,
                        Operator<VECTOR> &op_implicit);
@@ -218,13 +201,13 @@ namespace Algorithms
     /**
      * The timestepping scheme.
      *
-     * @param in is ignored by
-     * ThetaTimestepping, but is merged into the AnyData objects used
-     * as input for the operators #op_explicit and #op_implicit.
+     * @param in is ignored by ThetaTimestepping, but is merged into the
+     * AnyData objects used as input for the operators #op_explicit and
+     * #op_implicit.
      *
-     * @param out in its first argument must contain a pointer to a
-     * `VECTOR`, which contains the initial value when the operator is
-     * called. It contains the final value when the operator returns.
+     * @param out in its first argument must contain a pointer to a `VECTOR`,
+     * which contains the initial value when the operator is called. It
+     * contains the final value when the operator returns.
      */
     virtual void operator() (AnyData &out, const AnyData &in);
 
@@ -234,14 +217,13 @@ namespace Algorithms
     virtual void operator() (NamedData<VECTOR *> &out, const NamedData<VECTOR *> &in);
 
     /**
-     * Register an event triggered
-     * by an outer iteration.
+     * Register an event triggered by an outer iteration.
      */
     virtual void notify(const Event &);
 
     /**
-     * Define an operator which will output the result in each
-     * step. Note that no output will be generated without this.
+     * Define an operator which will output the result in each step. Note that
+     * no output will be generated without this.
      */
     void set_output(OutputOperator<VECTOR> &output);
 
@@ -260,8 +242,7 @@ namespace Algorithms
      */
     void initialize (ParameterHandler &param) DEAL_II_DEPRECATED;
     /**
-     * The current time in the
-     * timestepping scheme.
+     * The current time in the timestepping scheme.
      */
     double current_time() const;
     /**
@@ -281,16 +262,16 @@ namespace Algorithms
     /**
      * The data handed to the #op_explicit time stepping operator.
      *
-     * The time in here is the time at the beginning of the current
-     * step, the time step is (1-#theta) times the actual time step.
+     * The time in here is the time at the beginning of the current step, the
+     * time step is (1-#theta) times the actual time step.
      */
     const TimestepData &explicit_data() const;
 
     /**
      * The data handed to the #op_implicit time stepping operator.
      *
-     * The time in here is the time at the beginning of the current
-     * step, the time step is #theta times the actual time step.
+     * The time in here is the time at the beginning of the current step, the
+     * time step is #theta times the actual time step.
      */
     const TimestepData &implicit_data() const;
 
@@ -301,14 +282,14 @@ namespace Algorithms
 
   private:
     /**
-     * The object controlling the time step size and computing the new
-     * time in each step.
+     * The object controlling the time step size and computing the new time in
+     * each step.
      */
     TimestepControl control;
 
     /**
-     * The control parameter theta in the range <tt>[0,1]</tt>. It
-     * defaults to 0.5.
+     * The control parameter theta in the range <tt>[0,1]</tt>. It defaults to
+     * 0.5.
      */
     double vtheta;
     /**
@@ -328,29 +309,26 @@ namespace Algorithms
 
 
     /**
-     * The operator computing the explicit part of the scheme. This
-     * will receive in its input data the value at the current time
-     * with name "Current time solution". It should obtain the current
-     * time and time step size from explicit_data().
+     * The operator computing the explicit part of the scheme. This will
+     * receive in its input data the value at the current time with name
+     * "Current time solution". It should obtain the current time and time
+     * step size from explicit_data().
      *
-     * Its return value is $ Mu+cF(u) $, where $u$ is the
-     * current state vector, $M$ the mass matrix, $F$ the
-     * operator in space and $c$ is the adjusted
-     * time step size $(1-\theta) \Delta t$.
+     * Its return value is $ Mu+cF(u) $, where $u$ is the current state
+     * vector, $M$ the mass matrix, $F$ the operator in space and $c$ is the
+     * adjusted time step size $(1-\theta) \Delta t$.
      */
     SmartPointer<Operator<VECTOR>, ThetaTimestepping<VECTOR> > op_explicit;
 
     /**
-     * The operator solving the implicit part of the scheme. It will
-     * receive in its input data the vector "Previous
-     * time". Information on the timestep should be obtained from
-     * implicit_data().
+     * The operator solving the implicit part of the scheme. It will receive
+     * in its input data the vector "Previous time". Information on the
+     * timestep should be obtained from implicit_data().
      *
-     * Its return value is the solution <i>u</i> of <i>Mu-cF(u)=f</i>,
-     * where <i>f</i> is the dual space vector found in the "Previous
-     * time" entry of the input data, <i>M</i> the mass matrix,
-     * <i>F</i> the operator in space and <i>c</i> is the adjusted
-     * time step size $ \theta \Delta t$
+     * Its return value is the solution <i>u</i> of <i>Mu-cF(u)=f</i>, where
+     * <i>f</i> is the dual space vector found in the "Previous time" entry of
+     * the input data, <i>M</i> the mass matrix, <i>F</i> the operator in
+     * space and <i>c</i> is the adjusted time step size $ \theta \Delta t$
      */
     SmartPointer<Operator<VECTOR>, ThetaTimestepping<VECTOR> > op_implicit;
 
index 0944d96b867359dfa36e272db0975a542026cd29..3e669efa43884ab4cecc94df5824fe21b8ac4422 100644 (file)
@@ -29,65 +29,50 @@ class ParameterHandler;
 namespace Algorithms
 {
   /**
-   * Control class for timestepping schemes. Its main task is
-   * determining the size of the next time step and the according point
-   * in the time interval. Additionally, it controls writing the
-   * solution to a file.
+   * Control class for timestepping schemes. Its main task is determining the
+   * size of the next time step and the according point in the time interval.
+   * Additionally, it controls writing the solution to a file.
    *
    * The size of the next time step is determined as follows:
    * <ol>
    * <li> According to the strategy, the step size is tentatively added to the
    * current time.
-   * <li> If the resulting time exceeds the final time of the interval,
-   * the step size is reduced in order to meet this time.
-   * <li> If the resulting time is below the final time by just a
-   * fraction of the step size, the step size is increased in order to
-   * meet this time.
+   * <li> If the resulting time exceeds the final time of the interval, the
+   * step size is reduced in order to meet this time.
+   * <li> If the resulting time is below the final time by just a fraction of
+   * the step size, the step size is increased in order to meet this time.
    * <li> The resulting step size is used from the current time.
    * </ol>
    *
-   * The variable @p print_step can be used to control the amount of
-   * output generated by the timestepping scheme.
+   * The variable @p print_step can be used to control the amount of output
+   * generated by the timestepping scheme.
    */
   class TimestepControl : public Subscriptor
   {
   public:
     /**
-     * The time stepping
-     * strategies. These are
-     * controlled by the value of
+     * The time stepping strategies. These are controlled by the value of
      * tolerance() and start_step().
      */
     enum Strategy
     {
       /**
-       * Choose a uniform time
-       * step size. The step size
-       * is determined by
-       * start_step(),
-       * tolerance() is ignored.
+       * Choose a uniform time step size. The step size is determined by
+       * start_step(), tolerance() is ignored.
        */
       uniform,
       /**
-       * Start with the time step
-       * size given by
-       * start_step() and double it
-       * in every
-       * step. tolerance() is
-       * ignored.
+       * Start with the time step size given by start_step() and double it in
+       * every step. tolerance() is ignored.
        *
-       * This strategy is
-       * intended for
-       * pseudo-timestepping
-       * schemes computing a
+       * This strategy is intended for pseudo-timestepping schemes computing a
        * stationary limit.
        */
       doubling
     };
 
     /**
-     * Constructor setting default
-     * values
+     * Constructor setting default values
      */
     TimestepControl (double start = 0.,
                      double final = 1.,
@@ -110,8 +95,8 @@ namespace Algorithms
      */
     double start () const;
     /**
-     * The right end of the time interval. The control mechanism
-     * ensures that the final time step ends at this point.
+     * The right end of the time interval. The control mechanism ensures that
+     * the final time step ends at this point.
      */
     double final () const;
     /**
@@ -129,9 +114,8 @@ namespace Algorithms
     double now () const;
 
     /**
-     * Compute the size of the next step and return true if it differs
-     * from the current step size. Advance the current time by the new
-     * step size.
+     * Compute the size of the next step and return true if it differs from
+     * the current step size. Advance the current time by the new step size.
      */
     bool advance ();
 
@@ -164,8 +148,8 @@ namespace Algorithms
     void max_step (double);
 
     /**
-     * Set now() equal to start(). Initialize step() and print() to
-     * their initial values.
+     * Set now() equal to start(). Initialize step() and print() to their
+     * initial values.
      */
     void restart ();
     /**
@@ -187,9 +171,8 @@ namespace Algorithms
     double max_step_val;
     double min_step_val;
     /**
-     * The size of the current time
-     * step. This may differ from
-     * @p step_val, if we aimed at @p final_val.
+     * The size of the current time step. This may differ from @p step_val, if
+     * we aimed at @p final_val.
      */
     double current_step_val;
     double step_val;
index 40cb2411c2a9553ab72c9018e435b86430007cdf..534510b3b7f9309cbc460b36aa6fd60ade5948f0 100644 (file)
@@ -41,13 +41,13 @@ DEAL_II_NAMESPACE_OPEN
  * VectorizedArray and derived data types. It allocates memory aligned to
  * addresses of a vectorized data type (in order to avoid segmentation faults
  * when a variable of type VectorizedArray which the compiler assumes to be
- * aligned to certain memory addresses does not actually follow these
- * rules). This could also be achieved by proving std::vector with a
- * user-defined allocator. On the other hand, writing an own small vector
- * class lets us implement parallel copy and move operations with TBB, insert
- * deal.II-style assertions, and cut some unnecessary functionality. Note that
- * this vector is a bit more memory-consuming than std::vector because of
- * alignment, so it is recommended to only use this vector on long vectors.
+ * aligned to certain memory addresses does not actually follow these rules).
+ * This could also be achieved by proving std::vector with a user-defined
+ * allocator. On the other hand, writing an own small vector class lets us
+ * implement parallel copy and move operations with TBB, insert deal.II-style
+ * assertions, and cut some unnecessary functionality. Note that this vector
+ * is a bit more memory-consuming than std::vector because of alignment, so it
+ * is recommended to only use this vector on long vectors.
  *
  * @p author Katharina Kormann, Martin Kronbichler, 2011
  */
@@ -228,15 +228,15 @@ public:
   size_type memory_consumption () const;
 
   /**
-   * Write the data of this object to
-   * a stream for the purpose of serialization.
+   * Write the data of this object to a stream for the purpose of
+   * serialization.
    */
   template <class Archive>
   void save (Archive &ar, const unsigned int version) const;
 
   /**
-   * Read the data of this object
-   * from a stream for the purpose of serialization.
+   * Read the data of this object from a stream for the purpose of
+   * serialization.
    */
   template <class Archive>
   void load (Archive &ar, const unsigned int version);
@@ -265,15 +265,15 @@ private:
 // ------------------------------- inline functions --------------------------
 
 /**
- * This namespace defines the copy and set functions used in
- * AlignedVector. These functions operate in parallel when there are enough
- * elements in the vector.
+ * This namespace defines the copy and set functions used in AlignedVector.
+ * These functions operate in parallel when there are enough elements in the
+ * vector.
  */
 namespace internal
 {
   /**
-   * Move and class that actually issues the copy commands in
-   * AlignedVector. This class is based on the specialized for loop base class
+   * Move and class that actually issues the copy commands in AlignedVector.
+   * This class is based on the specialized for loop base class
    * ParallelForLoop in parallel.h whose purpose is the following: When
    * calling a parallel for loop on AlignedVector with apply_to_subranges, it
    * generates different code for every different argument we might choose (as
index 676bcfd8341671cc50f6e0ea8ac4922727f69f64..a9d6691866a136499ffa460a9a3b706c69407323 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class automatically computes the gradient of a function by
- * employing numerical difference quotients. This only, if the user
- * function does not provide the gradient function himself.
+ * This class automatically computes the gradient of a function by employing
+ * numerical difference quotients. This only, if the user function does not
+ * provide the gradient function himself.
  *
- * The following example of an user defined function overloads and
- * implements only the value() function but not the gradient()
- * function. If the gradient() function is invoked then the gradient
- * function implemented by the AutoDerivativeFunction is called,
- * where the latter function imployes numerical difference quotients.
+ * The following example of an user defined function overloads and implements
+ * only the value() function but not the gradient() function. If the
+ * gradient() function is invoked then the gradient function implemented by
+ * the AutoDerivativeFunction is called, where the latter function imployes
+ * numerical difference quotients.
  *
  * @code
  * class UserFunction: public AutoDerivativeFunction
@@ -45,31 +45,29 @@ DEAL_II_NAMESPACE_OPEN
  * Tensor<1,dim> grad=user_function.gradient(some_point);
  * @endcode
  *
- * If the user overloads and implements also the gradient function,
- * then, of course, the users gradient function is called.
+ * If the user overloads and implements also the gradient function, then, of
+ * course, the users gradient function is called.
  *
- * Note, that the usage of the value() and gradient() functions
- * explained above, also applies to the value_list() and
- * gradient_list() functions as well as to the vector valued
- * versions of these functions, see e.g. vector_value(),
- * vector_gradient(), vector_value_list() and
+ * Note, that the usage of the value() and gradient() functions explained
+ * above, also applies to the value_list() and gradient_list() functions as
+ * well as to the vector valued versions of these functions, see e.g.
+ * vector_value(), vector_gradient(), vector_value_list() and
  * vector_gradient_list().
  *
  * The gradient() and gradient_list() functions make use of the
  * Function::value() function. The vector_gradient() and
- * vector_gradient_list() make use of the Function::vector_value()
- * function. Make sure that the user defined function implements the
- * value() function and the vector_value() function, respectively.
+ * vector_gradient_list() make use of the Function::vector_value() function.
+ * Make sure that the user defined function implements the value() function
+ * and the vector_value() function, respectively.
  *
  * Furthermore note, that an object of this class does <b>not</b> represent
- * the derivative of a function, like FunctionDerivative, that
- * gives a directional derivate by calling the value() function. In
- * fact, this class (the AutoDerivativeFunction class) can
- * substitute the Function class as base class for user defined
- * classes. This class implements the gradient() functions for
- * automatic computation of numerical difference quotients and serves
- * as intermediate class between the base Function class and the
- * user defined function class.
+ * the derivative of a function, like FunctionDerivative, that gives a
+ * directional derivate by calling the value() function. In fact, this class
+ * (the AutoDerivativeFunction class) can substitute the Function class as
+ * base class for user defined classes. This class implements the gradient()
+ * functions for automatic computation of numerical difference quotients and
+ * serves as intermediate class between the base Function class and the user
+ * defined function class.
  *
  * @ingroup functions
  * @author Ralf Hartmann, 2001
@@ -85,8 +83,7 @@ public:
   enum DifferenceFormula
   {
     /**
-     * The symmetric Euler
-     * formula of second order:
+     * The symmetric Euler formula of second order:
      * @f[
      * u'(t) \approx
      * \frac{u(t+h) -
@@ -95,8 +92,7 @@ public:
      */
     Euler,
     /**
-     * The upwind Euler
-     * formula of first order:
+     * The upwind Euler formula of first order:
      * @f[
      * u'(t) \approx
      * \frac{u(t) -
@@ -116,101 +112,70 @@ public:
   };
 
   /**
-   * Constructor. Takes the
-   * difference step size
-   * <tt>h</tt>. It's within the user's
-   * responsibility to choose an
-   * appropriate value here. <tt>h</tt>
-   * should be chosen taking into
-   * account the absolute value as
-   * well as the amount of local
-   * variation of the function.
-   * Setting <tt>h=1e-6</tt> might be a
-   * good choice for functions with
-   * an absolute value of about 1,
-   * that furthermore does not vary
-   * to much.
+   * Constructor. Takes the difference step size <tt>h</tt>. It's within the
+   * user's responsibility to choose an appropriate value here. <tt>h</tt>
+   * should be chosen taking into account the absolute value as well as the
+   * amount of local variation of the function. Setting <tt>h=1e-6</tt> might
+   * be a good choice for functions with an absolute value of about 1, that
+   * furthermore does not vary to much.
    *
-   * <tt>h</tt> can be changed later
-   * using the set_h() function.
+   * <tt>h</tt> can be changed later using the set_h() function.
    *
-   * Sets DifferenceFormula
-   * <tt>formula</tt> to the default
-   * <tt>Euler</tt> formula of the
-   * set_formula()
-   * function. Change this preset
-   * formula by calling the
-   * set_formula() function.
+   * Sets DifferenceFormula <tt>formula</tt> to the default <tt>Euler</tt>
+   * formula of the set_formula() function. Change this preset formula by
+   * calling the set_formula() function.
    */
   AutoDerivativeFunction (const double h,
                           const unsigned int n_components = 1,
                           const double       initial_time = 0.0);
 
   /**
-   * Virtual destructor; absolutely
-   * necessary in this case.
+   * Virtual destructor; absolutely necessary in this case.
    */
   virtual ~AutoDerivativeFunction ();
 
   /**
-   * Choose the difference formula.
-   * See the enum #DifferenceFormula
-   * for available choices.
+   * Choose the difference formula. See the enum #DifferenceFormula for
+   * available choices.
    */
   void set_formula (const DifferenceFormula formula = Euler);
 
   /**
-   * Takes the difference step size
-   * <tt>h</tt>. It's within the user's
-   * responsibility to choose an
-   * appropriate value here. <tt>h</tt>
-   * should be chosen taking into
-   * account the absolute value of
-   * as well as the amount of local
-   * variation of the function.
-   * Setting <tt>h=1e-6</tt> might be a
-   * good choice for functions with
-   * an absolute value of about 1,
-   * that furthermore does not vary
-   * to much.
+   * Takes the difference step size <tt>h</tt>. It's within the user's
+   * responsibility to choose an appropriate value here. <tt>h</tt> should be
+   * chosen taking into account the absolute value of as well as the amount of
+   * local variation of the function. Setting <tt>h=1e-6</tt> might be a good
+   * choice for functions with an absolute value of about 1, that furthermore
+   * does not vary to much.
    */
   void set_h (const double h);
 
   /**
-   * Return the gradient of the
-   * specified component of the
-   * function at the given point.
+   * Return the gradient of the specified component of the function at the
+   * given point.
    *
-   * Computes numerical difference
-   * quotients using the preset
+   * Computes numerical difference quotients using the preset
    * #DifferenceFormula.
    */
   virtual Tensor<1,dim> gradient (const Point<dim>   &p,
                                   const unsigned int  component = 0) const;
 
   /**
-   * Return the gradient of all
-   * components of the
-   * function at the given point.
+   * Return the gradient of all components of the function at the given point.
    *
-   * Computes numerical difference
-   * quotients using the preset
+   * Computes numerical difference quotients using the preset
    * #DifferenceFormula.
    */
   virtual void vector_gradient (const Point<dim>            &p,
                                 std::vector<Tensor<1,dim> > &gradients) const;
 
   /**
-   * Set <tt>gradients</tt> to the
-   * gradients of the specified
-   * component of the function at
-   * the <tt>points</tt>.  It is assumed
-   * that <tt>gradients</tt> already has the
-   * right size, i.e.  the same
-   * size as the <tt>points</tt> array.
+   * Set <tt>gradients</tt> to the gradients of the specified component of the
+   * function at the <tt>points</tt>.  It is assumed that <tt>gradients</tt>
+   * already has the right size, i.e.  the same size as the <tt>points</tt>
+   * array.
    *
-   * Computes numerical difference
-   * quotients using the preset
+   * Computes numerical difference quotients using the preset
    * #DifferenceFormula.
    */
   virtual void gradient_list (const std::vector<Point<dim> > &points,
@@ -218,30 +183,22 @@ public:
                               const unsigned int              component = 0) const;
 
   /**
-   * Set <tt>gradients</tt> to the gradients of
-   * the function at the <tt>points</tt>,
-   * for all components.
-   * It is assumed that <tt>gradients</tt>
-   * already has the right size, i.e.
-   * the same size as the <tt>points</tt> array.
+   * Set <tt>gradients</tt> to the gradients of the function at the
+   * <tt>points</tt>, for all components. It is assumed that
+   * <tt>gradients</tt> already has the right size, i.e. the same size as the
+   * <tt>points</tt> array.
    *
-   * The outer loop over
-   * <tt>gradients</tt> is over the points
-   * in the list, the inner loop
-   * over the different components
-   * of the function.
+   * The outer loop over <tt>gradients</tt> is over the points in the list,
+   * the inner loop over the different components of the function.
    *
-   * Computes numerical difference
-   * quotients using the preset
+   * Computes numerical difference quotients using the preset
    * #DifferenceFormula.
    */
   virtual void vector_gradient_list (const std::vector<Point<dim> > &points,
                                      std::vector<std::vector<Tensor<1,dim> > > &gradients) const;
 
   /**
-   * Returns a
-   * #DifferenceFormula of the
-   * order <tt>ord</tt> at minimum.
+   * Returns a #DifferenceFormula of the order <tt>ord</tt> at minimum.
    */
   static
   DifferenceFormula
@@ -255,21 +212,17 @@ public:
 private:
 
   /**
-   * Step size of the difference
-   * formula. Set by the set_h()
-   * function.
+   * Step size of the difference formula. Set by the set_h() function.
    */
   double h;
 
   /**
-   * Includes the unit vectors
-   * scaled by <tt>h</tt>.
+   * Includes the unit vectors scaled by <tt>h</tt>.
    */
   std::vector<Tensor<1,dim> > ht;
 
   /**
-   * Difference formula. Set by the
-   * set_formula() function.
+   * Difference formula. Set by the set_formula() function.
    */
   DifferenceFormula formula;
 };
index 63242c22dcbc04c240a44b7e88976527dd6cc70f..38b12055567d2a19fd1710a7c030533d7b79f399 100644 (file)
@@ -25,12 +25,10 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * A class that allows printing to an output stream, e.g. @p std::cout,
- * depending on the ConditionalOStream object being active (default)
- * or not. The condition of this object can be changed by
- * set_condition() and in the constructor. This class is used in the
- * step-17, step-18, step-32,
- * step-33, and step-35
- * tutorial programs.
+ * depending on the ConditionalOStream object being active (default) or not.
+ * The condition of this object can be changed by set_condition() and in the
+ * constructor. This class is used in the step-17, step-18, step-32, step-33,
+ * and step-35 tutorial programs.
  *
  * This class is mostly useful in parallel computations. Ordinarily, you would
  * use @p std::cout to print messages like what the program is presently
@@ -38,8 +36,8 @@ DEAL_II_NAMESPACE_OPEN
  * parallel programs, this means that each of the MPI processes write to the
  * screen, which yields many repetitions of the same text. To avoid it, one
  * would have to have a designated process, say the one with MPI process
- * number zero, do the output, and guard each write statement with an
- * if-condition. This becomes cumbersome and clutters up the code. Rather than
+ * number zero, do the output, and guard each write statement with an if-
+ * condition. This becomes cumbersome and clutters up the code. Rather than
  * doing so, the present class can be used: objects of its type act just like
  * a standard output stream, but they only print something based on a
  * condition that can be set to, for example, <tt>mpi_process==0</tt>, so that
@@ -63,16 +61,16 @@ DEAL_II_NAMESPACE_OPEN
  * pout << "done" << std::endl;
  * @endcode
  *
- * Here, `Reading parameter file on process xy' is printed by each
- * process separately. In contrast to that, `Solving ...' and `done'
- * is printed to standard output only once, namely by process 0.
+ * Here, `Reading parameter file on process xy' is printed by each process
+ * separately. In contrast to that, `Solving ...' and `done' is printed to
+ * standard output only once, namely by process 0.
  *
  * This class is not derived from ostream. Therefore
  * @code
  * system_matrix.print_formatted(pout);
  * @endcode
- * is <em>not</em> possible. Instead use the is_active() function for a
- * work-around:
+ * is <em>not</em> possible. Instead use the is_active() function for a work-
+ * around:
  *
  * @code
  * if (pout.is_active())
@@ -86,24 +84,17 @@ class ConditionalOStream
 {
 public:
   /**
-   * Constructor. Set the stream to which
-   * we want to write, and the condition
-   * based on which writes are actually
-   * forwarded. Per default the condition
+   * Constructor. Set the stream to which we want to write, and the condition
+   * based on which writes are actually forwarded. Per default the condition
    * of an object is active.
    */
   ConditionalOStream (std::ostream &stream,
                       const bool    active = true);
 
   /**
-   * Depending on the
-   * <tt>active</tt> flag set the
-   * condition of this stream to
-   * active (true) or non-active
-   * (false). An object of this
-   * class prints to <tt>cout</tt>
-   * if and only if its condition
-   * is active.
+   * Depending on the <tt>active</tt> flag set the condition of this stream to
+   * active (true) or non-active (false). An object of this class prints to
+   * <tt>cout</tt> if and only if its condition is active.
    */
   void set_condition (const bool active);
 
@@ -113,50 +104,39 @@ public:
   bool is_active() const;
 
   /**
-   * Return a reference to the stream
-   * currently in use.
+   * Return a reference to the stream currently in use.
    */
   std::ostream &get_stream () const;
 
   /**
-   * Output a constant something through
-   * this stream. This function must be @p
-   * const so that member objects of this
-   * type can also be used from @p const
-   * member functions of the surrounding
-   * class.
+   * Output a constant something through this stream. This function must be @p
+   * const so that member objects of this type can also be used from @p const
+   * member functions of the surrounding class.
    */
   template <typename T>
   const ConditionalOStream &
   operator << (const T &t) const;
 
   /**
-   * Treat ostream manipulators. This
-   * function must be @p const so that
-   * member objects of this type can also
-   * be used from @p const member functions
-   * of the surrounding class.
+   * Treat ostream manipulators. This function must be @p const so that member
+   * objects of this type can also be used from @p const member functions of
+   * the surrounding class.
    *
-   * Note that compilers want to see this
-   * treated differently from the general
-   * template above since functions like @p
-   * std::endl are actually overloaded and
-   * can't be bound directly to a template
-   * type.
+   * Note that compilers want to see this treated differently from the general
+   * template above since functions like @p std::endl are actually overloaded
+   * and can't be bound directly to a template type.
    */
   const ConditionalOStream &
   operator<< (std::ostream& (*p) (std::ostream &)) const;
 
 private:
   /**
-   * Reference to the stream we
-   * want to write to.
+   * Reference to the stream we want to write to.
    */
   std::ostream  &output_stream;
 
   /**
-   * Stores the actual condition
-   * the object is in.
+   * Stores the actual condition the object is in.
    */
   bool active_flag;
 };
index d4be5718b119b67d5aaac28bc234efee1edcc90f..dd9a13e1946290fe64a4253d61cc675ad82e3b24 100644 (file)
@@ -24,15 +24,15 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * The ConvergenceTable class is an application to the TableHandler
- * class and stores some convergence data, such as residuals of the
- * cg-method, or some evaluated <i>L<sup>2</sup></i>-errors of
- * discrete solutions, etc, and evaluates convergence rates or orders.
+ * The ConvergenceTable class is an application to the TableHandler class and
+ * stores some convergence data, such as residuals of the cg-method, or some
+ * evaluated <i>L<sup>2</sup></i>-errors of discrete solutions, etc, and
+ * evaluates convergence rates or orders.
  *
- * The already implemented #RateMode's are #reduction_rate,
- * where the convergence rate is the quotient of two following rows, and
- * #reduction_rate_log2, that evaluates the order of convergence.
- * These standard evaluations are useful for global refinement, for local refinement
+ * The already implemented #RateMode's are #reduction_rate, where the
+ * convergence rate is the quotient of two following rows, and
+ * #reduction_rate_log2, that evaluates the order of convergence. These
+ * standard evaluations are useful for global refinement, for local refinement
  * this may not be an appropriate method, as the convergence rates should be
  * set in relation to the number of cells or the number of DoFs. The
  * implementations of these non-standard methods is left to a user.
@@ -43,14 +43,14 @@ DEAL_II_NAMESPACE_OPEN
  * functions evaluate_convergence_rates() and evaluate_all_convergence_rates()
  * may be called.
  *
- * There are two possibilities of how to evaluate the convergence rates of multiple
- * columns in the same RateMode.
+ * There are two possibilities of how to evaluate the convergence rates of
+ * multiple columns in the same RateMode.
  * <ol>
  * <li> call evaluate_convergence_rates() for all wanted columns
- * <li> call omit_column_from_convergence_rate_evaluation() for all
- *      columns for which this evaluation is not desired and then
- *      evaluate_all_convergence_rates() to evaluate the convergence rates of all columns
- *      that have not been flagged for omission.
+ * <li> call omit_column_from_convergence_rate_evaluation() for all columns
+ * for which this evaluation is not desired and then
+ * evaluate_all_convergence_rates() to evaluate the convergence rates of all
+ * columns that have not been flagged for omission.
  * </ol>
  *
  * A detailed discussion of this class can also be found in the step-7 and
@@ -102,28 +102,26 @@ public:
    * $1/h$, remember to set the dimension to 1 also when working in 3D to get
    * correct rates.
    *
-   * The new rate column and the data column will be merged to a
-   * supercolumn. The tex caption of the supercolumn will be (by default) the
-   * same as the one of the data column. This may be changed by using the
+   * The new rate column and the data column will be merged to a supercolumn.
+   * The tex caption of the supercolumn will be (by default) the same as the
+   * one of the data column. This may be changed by using the
    * <tt>set_tex_supercaption (...)</tt> function of the base class
    * TableHandler.
    *
    * This method behaves in the following way:
    *
-   * If RateMode is reduction_rate, then the computed output is
-   * $ \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $
-   * where $k$ is the reference column (no dimension dependence!).
+   * If RateMode is reduction_rate, then the computed output is $
+   * \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $ where $k$ is the reference column (no
+   * dimension dependence!).
    *
-   * If RateMode is reduction_rate_log2, then the computed output is
-   * $
-   * dim \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|}
-   * $.
+   * If RateMode is reduction_rate_log2, then the computed output is $ dim
+   * \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} $.
    *
    * This is useful, for example, if we use as reference key the number of
    * degrees of freedom or better, the number of cells.  Assuming that the
    * error is proportional to $ C (1/\sqrt{k})^r $ in 2D, then this method
-   * will produce the rate $r$ as a result. For general dimension, as described
-   * by the last parameter of this function, the formula needs to be
+   * will produce the rate $r$ as a result. For general dimension, as
+   * described by the last parameter of this function, the formula needs to be
    * $ C (1/\sqrt[dim]{k})^r $.
    *
    * @note Since this function adds columns to the table after several rows
@@ -144,9 +142,9 @@ public:
    * types of the table entries of the data column is a number, i.e. double,
    * float, (unsigned) int, and so on.
    *
-   * The new rate column and the data column will be merged to a
-   * supercolumn. The tex caption of the supercolumn will be (by default) the
-   * same as the one of the data column. This may be changed by using the
+   * The new rate column and the data column will be merged to a supercolumn.
+   * The tex caption of the supercolumn will be (by default) the same as the
+   * one of the data column. This may be changed by using the
    * set_tex_supercaption() function of the base class TableHandler.
    *
    * @note Since this function adds columns to the table after several rows
@@ -177,10 +175,10 @@ public:
    * convergence rate for almost all columns of a table without calling
    * evaluate_convergence_rates() for each column separately.
    *
-   * Example:
-   * Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be wanted to
-   * be omitted in the evaluation of the convergence rates. Hence they should
-   * omitted by calling the omit_column_from_convergence_rate_evaluation().
+   * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
+   * wanted to be omitted in the evaluation of the convergence rates. Hence
+   * they should omitted by calling the
+   * omit_column_from_convergence_rate_evaluation().
    */
   void
   evaluate_all_convergence_rates(const std::string &reference_column_key,
@@ -194,16 +192,18 @@ public:
    * convergence rate for almost all columns of a table without calling
    * evaluate_convergence_rates() for each column separately.
    *
-   * Example:
-   * Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be wanted to
-   * be omitted in the evaluation of the convergence rates. Hence they should
-   * omitted by calling the omit_column_from_convergence_rate_evaluation().
+   * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
+   * wanted to be omitted in the evaluation of the convergence rates. Hence
+   * they should omitted by calling the
+   * omit_column_from_convergence_rate_evaluation().
    */
   void
   evaluate_all_convergence_rates(const RateMode rate_mode);
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
index aec159d46e3579da9f04ddaadcfe101c417e3388..bffe08dac256f62174e31f437db5e8f7d3f68f2a 100644 (file)
@@ -45,110 +45,104 @@ class ParameterHandler;
 class XDMFEntry;
 
 /**
- * This is a base class for output of data on meshes of very general
- * form. Output data is expected as a set of <tt>patches</tt> and
- * written to the output stream in the format expected by the
- * visualization tool. For a list of output formats, check the
- * enumeration #OutputFormat. For each format listed there, this class
- * contains a function <tt>write_format</tt>, writing the
- * output. Refer to the documentation of those functions for details
- * on a certain format.
+ * This is a base class for output of data on meshes of very general form.
+ * Output data is expected as a set of <tt>patches</tt> and written to the
+ * output stream in the format expected by the visualization tool. For a list
+ * of output formats, check the enumeration #OutputFormat. For each format
+ * listed there, this class contains a function <tt>write_format</tt>, writing
+ * the output. Refer to the documentation of those functions for details on a
+ * certain format.
  *
  * <h3>Structure of the output data</h3>
  *
- * Data is not written with the deal.II mesh structure. Instead, it
- * relies on a set of <tt>patches</tt> created by a derived class (for
- * example the DataOut, DataOutStack, DataOutFaces, DataOutRotation,
- * or MatrixOut classes).  Each Patch describes a single logical cell
- * of a mesh, possibly subdivided a number of times to represent
- * higher order polynomials defined on this cell. To this end, a patch
- * consists of a <tt>dim</tt>-dimensional regular grid with the same
- * number of grid points in each direction. In the simplest case it
- * may consist of the corner points of a single mesh cell.  For each
- * point of this local grid, the Patch contains an arbitrary number of
- * data values, though the number of data sets must be the same for
- * each point on each patch.
+ * Data is not written with the deal.II mesh structure. Instead, it relies on
+ * a set of <tt>patches</tt> created by a derived class (for example the
+ * DataOut, DataOutStack, DataOutFaces, DataOutRotation, or MatrixOut
+ * classes).  Each Patch describes a single logical cell of a mesh, possibly
+ * subdivided a number of times to represent higher order polynomials defined
+ * on this cell. To this end, a patch consists of a <tt>dim</tt>-dimensional
+ * regular grid with the same number of grid points in each direction. In the
+ * simplest case it may consist of the corner points of a single mesh cell.
+ * For each point of this local grid, the Patch contains an arbitrary number
+ * of data values, though the number of data sets must be the same for each
+ * point on each patch.
  *
- * By offering this interface to the different output formats, it is simple
- * to extend this class to new formats without depending on such things
- * as actual triangulations and handling of data vectors. These things shall
- * be provided by derived class which have a user callable interface then.
+ * By offering this interface to the different output formats, it is simple to
+ * extend this class to new formats without depending on such things as actual
+ * triangulations and handling of data vectors. These things shall be provided
+ * by derived class which have a user callable interface then.
  *
- * Inside each patch, the data is organized in the usual
- * lexicographical order, <i>x</i> running fastest, then <i>y</i> and
- * <i>z</i>. Nodes are stored in this order and cells as well. Each
- * cell in 3D is stored such that the front face is in the
- * <i>xz</i>-plane. In order to enhance intellegibility of this
- * concept, the following two sections are kept from a previous
- * version of this documentation.
+ * Inside each patch, the data is organized in the usual lexicographical
+ * order, <i>x</i> running fastest, then <i>y</i> and <i>z</i>. Nodes are
+ * stored in this order and cells as well. Each cell in 3D is stored such that
+ * the front face is in the <i>xz</i>-plane. In order to enhance
+ * intellegibility of this concept, the following two sections are kept from a
+ * previous version of this documentation.
  *
  *
  * <h4>Patches</h4>
  *
  * Grids can be thought of as a collection of cells; if you want to write out
- * data on such a grid, you can do so by writing them one cell at a time.
- * The functions in this class therefore take a list of objects describing the
+ * data on such a grid, you can do so by writing them one cell at a time. The
+ * functions in this class therefore take a list of objects describing the
  * data on one cell each. This data for each cell usually consists of a list
  * of vertices for this cell, and a list of data values (for example solution
  * data, error information, etc) at each of these vertices.
  *
  * In some cases, this interface to a cell is too restricted, however. For
- * example, you may have higher order elements and printing the values at
- * the vertices only is not enough. For this reason, we not only provide
- * writing the data on the vertices only, but the data is organizes as a
- * tensor product grid on each cell. The parameter <tt>n_subdivision</tt>, which is
+ * example, you may have higher order elements and printing the values at the
+ * vertices only is not enough. For this reason, we not only provide writing
+ * the data on the vertices only, but the data is organizes as a tensor
+ * product grid on each cell. The parameter <tt>n_subdivision</tt>, which is
  * given for each patch separately, denotes how often the cell is to be
- * divided for output; for example, <tt>n_subdivisions==1</tt> yields no subdivision
- * of the cell, <tt>n_subdivisions==2</tt> will produce a grid of 3 times 3 points
- * in two spatial dimensions and 3 times 3 times 3 points in three dimensions,
- * <tt>n_subdivisions==3</tt> will yield 4 times 4 (times 4) points, etc. The actual
- * location of these points on the patch will be computed by a multilinear
- * transformation from the vertices given for this patch.
-
- * For cells at the boundary, a mapping might be used to calculate the position
- * of the inner points. In that case the coordinates are stored inside the
- * Patch, as they cannot be easily recovered otherwise.
+ * divided for output; for example, <tt>n_subdivisions==1</tt> yields no
+ * subdivision of the cell, <tt>n_subdivisions==2</tt> will produce a grid of
+ * 3 times 3 points in two spatial dimensions and 3 times 3 times 3 points in
+ * three dimensions, <tt>n_subdivisions==3</tt> will yield 4 times 4 (times 4)
+ * points, etc. The actual location of these points on the patch will be
+ * computed by a multilinear transformation from the vertices given for this
+ * patch.  For cells at the boundary, a mapping might be used to calculate the
+ * position of the inner points. In that case the coordinates are stored
+ * inside the Patch, as they cannot be easily recovered otherwise.
  *
- * Given these comments, the actual data to be printed on this patch of
- * points consists of several data sets each of which has a value at each
- * of the patch points. For example with <tt>n_subdivisions==2</tt> in two space
- * dimensions, each data set has to provide nine values, and since the
- * patch is to be printed as a tensor product (or its transformation to the
- * real space cell), its values are to be ordered like
- * <i>(x0,y0) (x0,y1) (x0,y2) (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2)</i>,
- * i.e. the z-coordinate runs fastest, then the y-coordinate, then x (if there
- * are that many space directions).
+ * Given these comments, the actual data to be printed on this patch of points
+ * consists of several data sets each of which has a value at each of the
+ * patch points. For example with <tt>n_subdivisions==2</tt> in two space
+ * dimensions, each data set has to provide nine values, and since the patch
+ * is to be printed as a tensor product (or its transformation to the real
+ * space cell), its values are to be ordered like <i>(x0,y0) (x0,y1) (x0,y2)
+ * (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2)</i>, i.e. the z-coordinate
+ * runs fastest, then the y-coordinate, then x (if there are that many space
+ * directions).
  *
  *
  * <h4>Generalized patches</h4>
  *
- * In general, the patches as explained above might be too
- * restricted. For example, one might want to draw only the outer
- * faces of a domain in a three-dimensional computation, if one is not
- * interested in what happens inside. Then, the objects that should be
- * drawn are two-dimensional in a three-dimensional world. The
- * Patch class and associated output functions handle these
- * cases. The Patch class therefore takes two template parameters,
- * the first, named <tt>dim</tt> denoting the dimension of the object (in
- * the above example, this would be two), while the second, named
- * <tt>spacedim</tt>, denotes the dimension of the embedding space (this
- * would be three). The corner points of a patch have the dimension of
- * the space, while their number is determined by the dimension of the
- * patch. By default, the second template parameter has the same value
- * as the first, which would correspond to outputting a cell, rather
- * than a face or something else.
+ * In general, the patches as explained above might be too restricted. For
+ * example, one might want to draw only the outer faces of a domain in a
+ * three-dimensional computation, if one is not interested in what happens
+ * inside. Then, the objects that should be drawn are two-dimensional in a
+ * three-dimensional world. The Patch class and associated output functions
+ * handle these cases. The Patch class therefore takes two template
+ * parameters, the first, named <tt>dim</tt> denoting the dimension of the
+ * object (in the above example, this would be two), while the second, named
+ * <tt>spacedim</tt>, denotes the dimension of the embedding space (this would
+ * be three). The corner points of a patch have the dimension of the space,
+ * while their number is determined by the dimension of the patch. By default,
+ * the second template parameter has the same value as the first, which would
+ * correspond to outputting a cell, rather than a face or something else.
  *
  * <h3>DataOutBaseInterface</h3>
  *
  * The members of this namespace are not usually called from user code
- * directly. Rather, classes that use the functions declared here
- * are typically derived from DataOutInterface.
+ * directly. Rather, classes that use the functions declared here are
+ * typically derived from DataOutInterface.
  *
  * The interface of this class basically consists of the declaration of a data
  * type describing a patch and a bunch of functions taking a list of patches
  * and writing them in one format or other to the stream. It is in the
- * responsibility of the derived classes to provide this list of patches.
- * In addition to the list of patches, a name for each data set may be given.
+ * responsibility of the derived classes to provide this list of patches. In
+ * addition to the list of patches, a name for each data set may be given.
  *
  *
  * <h3>Querying interface</h3>
@@ -166,15 +160,15 @@ class XDMFEntry;
  * <h3>Output parameters</h3>
  *
  * All functions take a parameter which is a structure of type
- * <tt>XFlags</tt>, where <tt>X</tt> is the name of the output
- * format. To find out what flags are presently supported, read the
- * documentation of the different structures.
+ * <tt>XFlags</tt>, where <tt>X</tt> is the name of the output format. To find
+ * out what flags are presently supported, read the documentation of the
+ * different structures.
  *
  * Note that usually the output formats used for scientific visualization
- * programs have no or very few parameters (apart from some compatibility flags)
- * because there the actual appearance of output is determined using the
- * visualization program and the files produced by this class store more or less
- * only raw data.
+ * programs have no or very few parameters (apart from some compatibility
+ * flags) because there the actual appearance of output is determined using
+ * the visualization program and the files produced by this class store more
+ * or less only raw data.
  *
  * The direct output formats, like Postscript or Povray need to be given a lot
  * more parameters, though, since there the output file has to contain all
@@ -182,26 +176,26 @@ class XDMFEntry;
  *
  * <h3>Writing backends</h3>
  *
- * An abstraction layer has been introduced to facilitate coding
- * backends for additional visualization tools. It is applicable for
- * data formats separating the information into a field of vertices, a
- * field of connection information for the grid cells and data fields.
+ * An abstraction layer has been introduced to facilitate coding backends for
+ * additional visualization tools. It is applicable for data formats
+ * separating the information into a field of vertices, a field of connection
+ * information for the grid cells and data fields.
  *
  * For each of these fields, output functions are implemented, namely
- * write_nodes(), write_cells() and write_data(). In order to use
- * these functions, a format specific output stream must be written,
- * following the examples of DXStream, GmvStream, VtkStream and so on,
- * implemented in the .cc file.
+ * write_nodes(), write_cells() and write_data(). In order to use these
+ * functions, a format specific output stream must be written, following the
+ * examples of DXStream, GmvStream, VtkStream and so on, implemented in the
+ * .cc file.
  *
- * In this framework, the implementation of a new output format is
- * reduced to writing the section headers and the new output stream
- * class for writing a single mesh object.
+ * In this framework, the implementation of a new output format is reduced to
+ * writing the section headers and the new output stream class for writing a
+ * single mesh object.
  *
  * <h3>Credits</h3>
  * <ul>
  *
- * <li>EPS output based on an earlier implementation by Stefan Nauber
- * for the old DataOut class
+ * <li>EPS output based on an earlier implementation by Stefan Nauber for the
+ * old DataOut class
  *
  * <li>Povray output by Thomas Richter
  *
@@ -210,7 +204,8 @@ class XDMFEntry;
  * </ul>
  *
  * @ingroup output
- * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005, 2006.
+ * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005,
+ * 2006.
  */
 namespace DataOutBase
 {
@@ -221,18 +216,18 @@ namespace DataOutBase
    * A patch consists of the following data:
    * <ul>
    * <li>the corner #vertices,
-   * <li> the number #n_subdivisions of the number of cells the Patch
-   * has in each space direction,
-   * <li> the #data attached to each vertex, in the usual
-   * lexicographic ordering,
+   * <li> the number #n_subdivisions of the number of cells the Patch has in
+   * each space direction,
+   * <li> the #data attached to each vertex, in the usual lexicographic
+   * ordering,
    * <li> Information on #neighbors.
    * </ul>
    *
    * See the general documentation of the DataOutBase class for more
-   * information on its contents and purposes.  In the case of two
-   * dimensions, the next picture ist an example of
-   * <tt>n_subdivision</tt> = 4 because the number of (sub)cells
-   * within each patch is equal to <tt>2<sup>dim</sup></tt>.
+   * information on its contents and purposes.  In the case of two dimensions,
+   * the next picture ist an example of <tt>n_subdivision</tt> = 4 because the
+   * number of (sub)cells within each patch is equal to
+   * <tt>2<sup>dim</sup></tt>.
    *
    * @ingroup output
    *
@@ -247,18 +242,18 @@ namespace DataOutBase
     static const unsigned int space_dim=spacedim;
 
     /**
-     * Corner points of a patch.  Inner points are computed by a
-     * multilinear transform of the unit cell to the cell specified by
-     * these corner points. The order of points is the same as for
-     * cells in the triangulation.
+     * Corner points of a patch.  Inner points are computed by a multilinear
+     * transform of the unit cell to the cell specified by these corner
+     * points. The order of points is the same as for cells in the
+     * triangulation.
      */
     Point<spacedim> vertices[GeometryInfo<dim>::vertices_per_cell];
 
     /**
-     * Numbers of neighbors of a patch.  OpenDX format requires
-     * neighbor information for advanced output. Here the neighborship
-     * relationship of patches is stored. During output, this must be
-     * transformed into neighborship of sub-grid cells.
+     * Numbers of neighbors of a patch.  OpenDX format requires neighbor
+     * information for advanced output. Here the neighborship relationship of
+     * patches is stored. During output, this must be transformed into
+     * neighborship of sub-grid cells.
      */
     unsigned int neighbors[dim > 0
                            ?
@@ -267,37 +262,37 @@ namespace DataOutBase
                            1];
 
     /**
-     * Number of this patch. Since we are not sure patches are handled
-     * in the same order, always, we better store this.
+     * Number of this patch. Since we are not sure patches are handled in the
+     * same order, always, we better store this.
      */
     unsigned int patch_index;
 
     /**
-     * Number of subdivisions with which this patch is to be
-     * written. <tt>1</tt> means no subdivision, <tt>2</tt> means
-     * bisection, <tt>3</tt> trisection, etc.
+     * Number of subdivisions with which this patch is to be written.
+     * <tt>1</tt> means no subdivision, <tt>2</tt> means bisection, <tt>3</tt>
+     * trisection, etc.
      */
     unsigned int n_subdivisions;
 
     /**
-     * Data vectors. The format is as follows: <tt>data(i,.)</tt>
-     * denotes the data belonging to the <tt>i</tt>th data
-     * vector. <tt>data.n()</tt> therefore equals the number of output
-     * points; this number is <tt>(subdivisions+1)^{dim</tt>}.
-     * <tt>data.m()</tt> equals the number of data vectors.
+     * Data vectors. The format is as follows: <tt>data(i,.)</tt> denotes the
+     * data belonging to the <tt>i</tt>th data vector. <tt>data.n()</tt>
+     * therefore equals the number of output points; this number is
+     * <tt>(subdivisions+1)^{dim</tt>}. <tt>data.m()</tt> equals the number of
+     * data vectors.
      *
-     * Within each column, <tt>data(.,j)</tt> are the data values at
-     * the output point <tt>j</tt>, where <tt>j</tt> denotes the usual
-     * lexicographic ordering in deal.II. This is also the order of
-     * points as provided by the <tt>QIterated</tt> class when used
-     * with the <tt>QTrapez</tt> class as subquadrature.
+     * Within each column, <tt>data(.,j)</tt> are the data values at the
+     * output point <tt>j</tt>, where <tt>j</tt> denotes the usual
+     * lexicographic ordering in deal.II. This is also the order of points as
+     * provided by the <tt>QIterated</tt> class when used with the
+     * <tt>QTrapez</tt> class as subquadrature.
      *
-     * Since the number of data vectors is usually the same for all
-     * patches to be printed, <tt>data.size()</tt> should yield the
-     * same value for all patches provided. The exception are patches
-     * for which points_are_available are set, where the actual
-     * coordinates of the point are appended to the 'data' field, see
-     * the documentation of the points_are_available flag.
+     * Since the number of data vectors is usually the same for all patches to
+     * be printed, <tt>data.size()</tt> should yield the same value for all
+     * patches provided. The exception are patches for which
+     * points_are_available are set, where the actual coordinates of the point
+     * are appended to the 'data' field, see the documentation of the
+     * points_are_available flag.
      */
     Table<2,float> data;
 
@@ -322,18 +317,17 @@ namespace DataOutBase
     Patch ();
 
     /**
-     * Compare the present patch for equality with another one. This
-     * is used in a few of the automated tests in our testsuite.
+     * Compare the present patch for equality with another one. This is used
+     * in a few of the automated tests in our testsuite.
      */
     bool operator == (const Patch &patch) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
 
@@ -341,8 +335,10 @@ namespace DataOutBase
      * Value to be used if this patch has no neighbor on one side.
      */
     static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception
@@ -363,10 +359,9 @@ namespace DataOutBase
   struct DXFlags
   {
     /**
-     * Write neighbor information. This information is necessary for
-     * instance, if OpenDX is supposed to compute integral curves
-     * (streamlines). If it is not present, streamlines end at cell
-     * boundaries.
+     * Write neighbor information. This information is necessary for instance,
+     * if OpenDX is supposed to compute integral curves (streamlines). If it
+     * is not present, streamlines end at cell boundaries.
      */
     bool write_neighbors;
     /**
@@ -384,8 +379,8 @@ namespace DataOutBase
     bool data_binary;
 
     /**
-     * Write binary coordinate vectors as double (64 bit) numbers
-     * instead of float (32 bit).
+     * Write binary coordinate vectors as double (64 bit) numbers instead of
+     * float (32 bit).
      */
     bool data_double;
 
@@ -398,23 +393,22 @@ namespace DataOutBase
              const bool data_binary = false);
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and set
-     * the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm);
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
   };
@@ -427,11 +421,11 @@ namespace DataOutBase
   struct UcdFlags
   {
     /**
-     * Write a comment at the beginning of the file stating the date
-     * of creation and some other data.  While this is supported by
-     * the UCD format and AVS, some other programs get confused by
-     * this, so the default is to not write a preamble. However, a
-     * preamble can be written using this flag.
+     * Write a comment at the beginning of the file stating the date of
+     * creation and some other data.  While this is supported by the UCD
+     * format and AVS, some other programs get confused by this, so the
+     * default is to not write a preamble. However, a preamble can be written
+     * using this flag.
      *
      * Default: <code>false</code>.
      */
@@ -443,34 +437,32 @@ namespace DataOutBase
     UcdFlags (const bool write_preamble = false);
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and
-     * set the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm);
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
 
   /**
-   * Flags controlling the details of output in Gnuplot format. At
-   * present no flags are implemented.
+   * Flags controlling the details of output in Gnuplot format. At present no
+   * flags are implemented.
    *
    * @ingroup output
    */
@@ -479,8 +471,8 @@ namespace DataOutBase
   private:
     /**
      * Dummy entry to suppress compiler warnings when copying an empty
-     * structure. Remove this member when adding the first flag to
-     * this structure (and remove the <tt>private</tt> as well).
+     * structure. Remove this member when adding the first flag to this
+     * structure (and remove the <tt>private</tt> as well).
      */
     int dummy;
 
@@ -491,34 +483,32 @@ namespace DataOutBase
     GnuplotFlags ();
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and set
-     * the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
 
   /**
-   * Flags controlling the details of output in Povray format. Several
-   * flags are implemented, see their respective documentation.
+   * Flags controlling the details of output in Povray format. Several flags
+   * are implemented, see their respective documentation.
    *
    * @ingroup output
    */
@@ -539,8 +529,8 @@ namespace DataOutBase
     bool bicubic_patch;
 
     /**
-     * include external "data.inc" with camera, light and texture
-     * definition for the scene.
+     * include external "data.inc" with camera, light and texture definition
+     * for the scene.
      *
      * default = false
      */
@@ -554,59 +544,56 @@ namespace DataOutBase
                  const bool external_data = false);
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and
-     * set the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm);
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
 
 
   /**
-   * Flags controlling the details of output in encapsulated
-   * postscript format.
+   * Flags controlling the details of output in encapsulated postscript
+   * format.
    *
    * @ingroup output
    */
   struct EpsFlags
   {
     /**
-     * This denotes the number of the data vector which shall be used
-     * for generating the height information. By default, the first
-     * data vector is taken, i.e. <tt>height_vector==0</tt>, if there
-     * is any data vector. If there is no data vector, no height
-     * information is generated.
+     * This denotes the number of the data vector which shall be used for
+     * generating the height information. By default, the first data vector is
+     * taken, i.e. <tt>height_vector==0</tt>, if there is any data vector. If
+     * there is no data vector, no height information is generated.
      */
     unsigned int height_vector;
 
     /**
-     * Number of the vector which is to be taken to colorize cells.
-     * The same applies as for #height_vector.
+     * Number of the vector which is to be taken to colorize cells. The same
+     * applies as for #height_vector.
      */
     unsigned int color_vector;
 
     /**
-     * Enum denoting the possibilities whether the scaling should be
-     * done such that the given <tt>size</tt> equals the width or the
-     * height of the resulting picture.
+     * Enum denoting the possibilities whether the scaling should be done such
+     * that the given <tt>size</tt> equals the width or the height of the
+     * resulting picture.
      */
     enum SizeType
     {
@@ -622,9 +609,9 @@ namespace DataOutBase
     SizeType size_type;
 
     /**
-     * Width or height of the output as given in postscript units This
-     * usually is given by the strange unit 1/72 inch. Whether this is
-     * height or width is specified by the flag <tt>size_type</tt>.
+     * Width or height of the output as given in postscript units This usually
+     * is given by the strange unit 1/72 inch. Whether this is height or width
+     * is specified by the flag <tt>size_type</tt>.
      *
      * Default is 300, which represents a size of roughly 10 cm.
      */
@@ -643,13 +630,13 @@ namespace DataOutBase
     double azimut_angle;
 
     /**
-     * Angle by which the viewers position projected onto the
-     * x-y-plane is rotated around the z-axis, in positive sense when
-     * viewed from above. The unit are degrees, and zero equals a
-     * position above or below the negative y-axis.
+     * Angle by which the viewers position projected onto the x-y-plane is
+     * rotated around the z-axis, in positive sense when viewed from above.
+     * The unit are degrees, and zero equals a position above or below the
+     * negative y-axis.
      *
-     * Default is the Gnuplot-default of 30.  An example of a
-     * Gnuplot-default of 0 is the following:
+     * Default is the Gnuplot-default of 30.  An example of a Gnuplot-default
+     * of 0 is the following:
      *
      * @verbatim
      *
@@ -668,50 +655,47 @@ namespace DataOutBase
     double turn_angle;
 
     /**
-     * Factor by which the z-axis is to be stretched as compared to
-     * the x- and y-axes. This is to compensate for the different
-     * sizes that coordinate and solution values may have and to
-     * prevent that the plot looks to much out-of-place (no elevation
-     * at all if solution values are much smaller than coordinate
-     * values, or the common "extremely mountainous area" in the
-     * opposite case.
+     * Factor by which the z-axis is to be stretched as compared to the x- and
+     * y-axes. This is to compensate for the different sizes that coordinate
+     * and solution values may have and to prevent that the plot looks to much
+     * out-of-place (no elevation at all if solution values are much smaller
+     * than coordinate values, or the common "extremely mountainous area" in
+     * the opposite case.
      *
      * Default is <tt>1.0</tt>.
      */
     double z_scaling;
 
     /**
-     * Flag the determines whether the lines bounding the cells (or
-     * the parts of each patch) are to be plotted.
+     * Flag the determines whether the lines bounding the cells (or the parts
+     * of each patch) are to be plotted.
      *
      * Default: <tt>true</tt>.
      */
     bool   draw_mesh;
 
     /**
-     * Flag whether to fill the regions between the lines bounding the
-     * cells or not. If not, no hidden line removal is performed,
-     * which in this crude implementation is done through writing the
-     * cells in a back-to-front order, thereby hiding the cells in the
-     * background by cells in the foreground.
+     * Flag whether to fill the regions between the lines bounding the cells
+     * or not. If not, no hidden line removal is performed, which in this
+     * crude implementation is done through writing the cells in a back-to-
+     * front order, thereby hiding the cells in the background by cells in the
+     * foreground.
      *
-     * If this flag is <tt>false</tt> and #draw_mesh is <tt>false</tt>
-     * as well, nothing will be printed.
+     * If this flag is <tt>false</tt> and #draw_mesh is <tt>false</tt> as
+     * well, nothing will be printed.
      *
-     * If this flag is <tt>true</tt>, then the cells will be drawn
-     * either colored by one of the data sets (if #shade_cells is
-     * <tt>true</tt>), or pure white (if #shade_cells is false or if
-     * there are no data sets).
+     * If this flag is <tt>true</tt>, then the cells will be drawn either
+     * colored by one of the data sets (if #shade_cells is <tt>true</tt>), or
+     * pure white (if #shade_cells is false or if there are no data sets).
      *
      * Default is <tt>true</tt>.
      */
     bool   draw_cells;
 
     /**
-     * Flag to determine whether the cells shall be colorized by the
-     * data set denoted by #color_vector, or simply be painted in
-     * white. This flag only makes sense if
-     * <tt>#draw_cells==true</tt>. Colorization is done through
+     * Flag to determine whether the cells shall be colorized by the data set
+     * denoted by #color_vector, or simply be painted in white. This flag only
+     * makes sense if <tt>#draw_cells==true</tt>. Colorization is done through
      * #color_function.
      *
      * Default is <tt>true</tt>.
@@ -728,37 +712,36 @@ namespace DataOutBase
       float blue;
 
       /**
-       * Return <tt>true</tt> if the color represented by the three
-       * color values is a grey scale, i.e. all components are equal.
+       * Return <tt>true</tt> if the color represented by the three color
+       * values is a grey scale, i.e. all components are equal.
        */
       bool is_grey () const;
     };
 
     /**
-     * Definition of a function pointer type taking a value and
-     * returning a triple of color values in RGB values.
+     * Definition of a function pointer type taking a value and returning a
+     * triple of color values in RGB values.
      *
-     * Besides the actual value by which the color is to be computed,
-     * min and max values of the data to be colorized are given as
-     * well.
+     * Besides the actual value by which the color is to be computed, min and
+     * max values of the data to be colorized are given as well.
      */
     typedef RgbValues (*ColorFunction) (const double value,
                                         const double min_value,
                                         const double max_value);
 
     /**
-     * This is a pointer to the function which is used to colorize the
-     * cells.  By default, it points to the static function
-     * default_color_function() which is a member of this class.
+     * This is a pointer to the function which is used to colorize the cells.
+     * By default, it points to the static function default_color_function()
+     * which is a member of this class.
      */
     ColorFunction color_function;
 
 
     /**
-     * Default colorization function. This one does what one usually
-     * wants: It shifts colors from black (lowest value) through blue,
-     * green and red to white (highest value). For the exact defition
-     * of the color scale refer to the implementation.
+     * Default colorization function. This one does what one usually wants: It
+     * shifts colors from black (lowest value) through blue, green and red to
+     * white (highest value). For the exact defition of the color scale refer
+     * to the implementation.
      *
      * This function was originally written by Stefan Nauber.
      */
@@ -768,10 +751,9 @@ namespace DataOutBase
                             const double max_value);
 
     /**
-     * This is an alternative color function producing a grey scale
-     * between black (lowest values) and white (highest values). You
-     * may use it by setting the #color_function variable to the
-     * address of this function.
+     * This is an alternative color function producing a grey scale between
+     * black (lowest values) and white (highest values). You may use it by
+     * setting the #color_function variable to the address of this function.
      */
     static RgbValues
     grey_scale_color_function (const double value,
@@ -779,11 +761,10 @@ namespace DataOutBase
                                const double max_value);
 
     /**
-     * This is one more alternative color function producing a grey
-     * scale between white (lowest values) and black (highest values),
-     * i.e. the scale is reversed to the previous one. You may use it
-     * by setting the #color_function variable to the address of this
-     * function.
+     * This is one more alternative color function producing a grey scale
+     * between white (lowest values) and black (highest values), i.e. the
+     * scale is reversed to the previous one. You may use it by setting the
+     * #color_function variable to the address of this function.
      */
     static RgbValues
     reverse_grey_scale_color_function (const double value,
@@ -807,37 +788,35 @@ namespace DataOutBase
               const ColorFunction color_function= &default_color_function);
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      *
-     * For coloring, only the color functions declared in this class
-     * are offered.
+     * For coloring, only the color functions declared in this class are
+     * offered.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and set
-     * the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm);
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
 
   /**
-   * Flags controlling the details of output in GMV format. At present
-   * no flags are implemented.
+   * Flags controlling the details of output in GMV format. At present no
+   * flags are implemented.
    *
    * @ingroup output
    */
@@ -846,8 +825,8 @@ namespace DataOutBase
   private:
     /**
      * Dummy entry to suppress compiler warnings when copying an empty
-     * structure. Remove this member when adding the first flag to
-     * this structure (and remove the <tt>private</tt> as well).
+     * structure. Remove this member when adding the first flag to this
+     * structure (and remove the <tt>private</tt> as well).
      */
     int dummy;
 
@@ -858,27 +837,25 @@ namespace DataOutBase
     GmvFlags ();
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and set
-     * the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
@@ -894,47 +871,44 @@ namespace DataOutBase
   public:
 
     /**
-     * This variable is needed to hold the output file name when using
-     * the Tecplot API to write binary files.  If the user doesn't set
-     * the file name with this variable only ASCII Tecplot output will
-     * be produced.
+     * This variable is needed to hold the output file name when using the
+     * Tecplot API to write binary files.  If the user doesn't set the file
+     * name with this variable only ASCII Tecplot output will be produced.
      */
     const char *tecplot_binary_file_name;
 
     /**
-     * Tecplot allows to assign names to zones. This variable stores
-     * this name.
+     * Tecplot allows to assign names to zones. This variable stores this
+     * name.
      */
     const char *zone_name;
 
     /**
      * Constructor
-     **/
+     */
     TecplotFlags (const char *tecplot_binary_file_name = NULL,
                   const char *zone_name = NULL);
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and set
-     * the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
@@ -948,11 +922,11 @@ namespace DataOutBase
   {
   public:
     /**
-     * The time of the time step if this file is part of a time
-     * dependent simulation.
+     * The time of the time step if this file is part of a time dependent
+     * simulation.
      *
-     * The value of this variable is written into the output file
-     * according to the instructions provided in
+     * The value of this variable is written into the output file according to
+     * the instructions provided in
      * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
      * unless it is at its default value of
      * std::numeric_limits<double>::min().
@@ -960,24 +934,23 @@ namespace DataOutBase
     double time;
 
     /**
-     * The number of the time step if this file is part of a time
-     * dependent simulation, or the cycle within a nonlinear or other
-     * iteration.
+     * The number of the time step if this file is part of a time dependent
+     * simulation, or the cycle within a nonlinear or other iteration.
      *
-     * The value of this variable is written into the output file
-     * according to the instructions provided in
+     * The value of this variable is written into the output file according to
+     * the instructions provided in
      * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
-     * unless it is at its default value of
-     * std::numeric_limits<unsigned int>::min().
+     * unless it is at its default value of std::numeric_limits<unsigned
+     * int>::min().
      */
     unsigned int cycle;
 
     /**
-      * Flag to determine whether the current date and time shall be
-      * printed as a comment in the file's second line.
-      *
-      * Default is <tt>true</tt>.
-      */
+     * Flag to determine whether the current date and time shall be printed as
+     * a comment in the file's second line.
+     *
+     * Default is <tt>true</tt>.
+     */
     bool print_date_and_time;
 
     /**
@@ -988,35 +961,33 @@ namespace DataOutBase
               const bool print_date_and_time = true);
 
     /**
-     * Declare the flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare the flags with name and type as offered by this class, for use
+     * in input files.
      *
-     * Unlike the flags in many of the other classes similar to this one, we do
-     * not actually declare parameters for the #cycle and #time member variables
-     * of this class. The reason is that there wouldn't appear to be a case where
-     * one would want to declare these parameters in an input file. Rather, these
-     * are typically values that change during the course of a simulation and
-     * can only reasonably be set as part of the execution of a program, rather
-     * than a priori by a user who runs this program.
+     * Unlike the flags in many of the other classes similar to this one, we
+     * do not actually declare parameters for the #cycle and #time member
+     * variables of this class. The reason is that there wouldn't appear to be
+     * a case where one would want to declare these parameters in an input
+     * file. Rather, these are typically values that change during the course
+     * of a simulation and can only reasonably be set as part of the execution
+     * of a program, rather than a priori by a user who runs this program.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and
-     * set the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite all previous contents of this
-     * object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
@@ -1029,23 +1000,21 @@ namespace DataOutBase
   {
   public:
     /**
-    * Height of the image in SVG
-    * units. Default value is 4000.
-    */
+     * Height of the image in SVG units. Default value is 4000.
+     */
     unsigned int height;
 
     /**
-    * Width of the image in SVG
-    units. If left zero, the width is computed from the height.
-    */
+     * Width of the image in SVG units. If left zero, the width is computed
+     * from the height.
+     */
     unsigned int width;
 
     /**
-     * This denotes the number of the data vector which shall be used
-     * for generating the height information. By default, the first
-     * data vector is taken, i.e. <tt>#height_vector==0</tt>, if there
-     * is any data vector. If there is no data vector, no height
-     * information is generated.
+     * This denotes the number of the data vector which shall be used for
+     * generating the height information. By default, the first data vector is
+     * taken, i.e. <tt>#height_vector==0</tt>, if there is any data vector. If
+     * there is no data vector, no height information is generated.
      */
     unsigned int height_vector;
 
@@ -1057,18 +1026,18 @@ namespace DataOutBase
     unsigned int line_thickness;
 
     /**
-    * Draw a margin of 5% around the plotted area
-    */
+     * Draw a margin of 5% around the plotted area
+     */
     bool margin;
 
     /**
-    * Draw a colorbar encoding the cell coloring
-    */
+     * Draw a colorbar encoding the cell coloring
+     */
     bool draw_colorbar;
 
     /**
-    * Constructor.
-    */
+     * Constructor.
+     */
     SvgFlags(const unsigned int height_vector = 0,
              const int azimuth_angle = 37,
              const int polar_angle = 45,
@@ -1077,20 +1046,19 @@ namespace DataOutBase
              const bool draw_colorbar = true);
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
 
 
   /**
-   * Flags controlling the details of output in deal.II intermediate
-   * format. At present no flags are implemented.
+   * Flags controlling the details of output in deal.II intermediate format.
+   * At present no flags are implemented.
    *
    * @ingroup output
    */
@@ -1098,18 +1066,17 @@ namespace DataOutBase
   {
     /**
      * An indicator of the currect file format version used to write
-     * intermediate format. We do not attempt to be backward
-     * compatible, so this number is used only to verify that the
-     * format we are writing is what the current readers and writers
-     * understand.
+     * intermediate format. We do not attempt to be backward compatible, so
+     * this number is used only to verify that the format we are writing is
+     * what the current readers and writers understand.
      */
     static const unsigned int format_version = 3;
 
   private:
     /**
      * Dummy entry to suppress compiler warnings when copying an empty
-     * structure. Remove this member when adding the first flag to
-     * this structure (and remove the <tt>private</tt> as well).
+     * structure. Remove this member when adding the first flag to this
+     * structure (and remove the <tt>private</tt> as well).
      */
     int dummy;
 
@@ -1120,27 +1087,25 @@ namespace DataOutBase
     Deal_II_IntermediateFlags ();
 
     /**
-     * Declare all flags with name and type as offered by this class,
-     * for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in declare_parameters() and
-     * set the flags for this output format accordingly.
+     * Read the parameters declared in declare_parameters() and set the flags
+     * for this output format accordingly.
      *
-     * The flags thus obtained overwrite
-     * all previous contents of this object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm) const;
 
     /**
-     * Determine an estimate for the memory consumption (in bytes) of
-     * this object. Since sometimes the size of objects can not be
-     * determined exactly (for example: what is the memory consumption
-     * of an STL <tt>std::map</tt> type with a certain number of
-     * elements?), this is only an estimate. however often quite close
-     * to the true value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
   };
@@ -1154,15 +1119,15 @@ namespace DataOutBase
   struct DataOutFilterFlags
   {
     /**
-     * Filter duplicate vertices and associated values. This will
-     * drastically reduce the output data size but may affect the
-     * correctness of some calculated values.
+     * Filter duplicate vertices and associated values. This will drastically
+     * reduce the output data size but may affect the correctness of some
+     * calculated values.
      */
     bool filter_duplicate_vertices;
 
     /**
-     * Whether the XDMF output refers to HDF5 files.
-     * This affects how output is structured.
+     * Whether the XDMF output refers to HDF5 files. This affects how output
+     * is structured.
      */
     bool xdmf_hdf5_output;
 
@@ -1173,27 +1138,21 @@ namespace DataOutBase
                         const bool xdmf_hdf5_output = false);
 
     /**
-     * Declare all flags with name
-     * and type as offered by this
-     * class, for use in input files.
+     * Declare all flags with name and type as offered by this class, for use
+     * in input files.
      */
     static void declare_parameters (ParameterHandler &prm);
 
     /**
-     * Read the parameters declared in
-     * <tt>declare_parameters</tt> and set the
-     * flags for this output format
-     * accordingly.
+     * Read the parameters declared in <tt>declare_parameters</tt> and set the
+     * flags for this output format accordingly.
      *
-     * The flags thus obtained overwrite
-     * all previous contents of this object.
+     * The flags thus obtained overwrite all previous contents of this object.
      */
     void parse_parameters (const ParameterHandler &prm);
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this
+     * Determine an estimate for the memory consumption (in bytes) of this
      * object.
      */
     std::size_t memory_consumption () const;
@@ -1202,23 +1161,23 @@ namespace DataOutBase
   /**
    * DataOutFilter provides a way to remove redundant vertices and values
    * generated by the deal.II output. By default, DataOutBase and the classes
-   * that build on it output data at each corner of each cell. This means
-   * that data is output multiple times for each vertex of the mesh. The
-   * purpose of this scheme is to support output of discontinuous quantities,
-   * either because the finite element space is discontinuous or because the
-   * quantity that is output is computed from a solution field and is
-   * discontinuous across faces.
+   * that build on it output data at each corner of each cell. This means that
+   * data is output multiple times for each vertex of the mesh. The purpose of
+   * this scheme is to support output of discontinuous quantities, either
+   * because the finite element space is discontinuous or because the quantity
+   * that is output is computed from a solution field and is discontinuous
+   * across faces.
    *
    * This class is an attempt to rein in the amount of data that is written.
    * If the fields that are written to files are indeed discontinuous, the
-   * only way to faithfully represent them is indeed to write multiple
-   * values for each vertex (this is typically done by writing multiple
-   * node locations for the same vertex and defining data at these nodes).
-   * However, for fine meshes, one may not necessarily be interested in an
-   * exact representation of output fields that will likely only have
-   * small discontinuities. Rather, it may be sufficient to just output one
-   * value per vertex, which may be chosen arbitrarily from among those that
-   * are defined at this vertex from any of the adjacent cells.
+   * only way to faithfully represent them is indeed to write multiple values
+   * for each vertex (this is typically done by writing multiple node
+   * locations for the same vertex and defining data at these nodes). However,
+   * for fine meshes, one may not necessarily be interested in an exact
+   * representation of output fields that will likely only have small
+   * discontinuities. Rather, it may be sufficient to just output one value
+   * per vertex, which may be chosen arbitrarily from among those that are
+   * defined at this vertex from any of the adjacent cells.
    */
   class DataOutFilter
   {
@@ -1273,10 +1232,9 @@ namespace DataOutBase
     DataOutFilter(const DataOutBase::DataOutFilterFlags &flags) : flags(flags) {};
 
     /**
-     * Write a point with the specified index into the filtered
-     * data set. If the point already exists and we are filtering
-     * redundant values, the provided index will internally refer
-     * to another recorded point.
+     * Write a point with the specified index into the filtered data set. If
+     * the point already exists and we are filtering redundant values, the
+     * provided index will internally refer to another recorded point.
      */
     template<int dim>
     void write_point(const unsigned int &index, const Point<dim> &p);
@@ -1288,23 +1246,22 @@ namespace DataOutBase
     void write_cell(unsigned int index, unsigned int start, unsigned int d1, unsigned int d2, unsigned int d3);
 
     /**
-     * Filter and record a data set. If there are multiple values
-     * at a given vertex and redundant values are being removed, one
-     * is arbitrarily chosen as the recorded value. In the future
-     * this can be expanded to average/min/max multiple values
-     * at a given vertex.
+     * Filter and record a data set. If there are multiple values at a given
+     * vertex and redundant values are being removed, one is arbitrarily
+     * chosen as the recorded value. In the future this can be expanded to
+     * average/min/max multiple values at a given vertex.
      */
     void write_data_set(const std::string &name, const unsigned int &dimension, const unsigned int &set_num, const Table<2,double> &data_vectors);
 
     /**
-     * Resize and fill a vector with all the filtered
-     * node vertex points, for output to a file.
+     * Resize and fill a vector with all the filtered node vertex points, for
+     * output to a file.
      */
     void fill_node_data(std::vector<double> &node_data) const;
 
     /**
-     * Resize and fill a vector with all the filtered
-     * cell vertex indices, for output to a file.
+     * Resize and fill a vector with all the filtered cell vertex indices, for
+     * output to a file.
      */
     void fill_cell_data(const unsigned int &local_node_offset, std::vector<unsigned int> &cell_data) const;
 
@@ -1325,7 +1282,8 @@ namespace DataOutBase
     };
 
     /**
-     * Get the raw double valued data of the data set indicated by the set number.
+     * Get the raw double valued data of the data set indicated by the set
+     * number.
      */
     const double *get_data_set(const unsigned int &set_num) const
     {
@@ -1351,8 +1309,8 @@ namespace DataOutBase
     };
 
     /**
-     * Return the number of filtered data sets in this DataOutFilter. Data sets are
-     * not filtered so this will be the original number of data sets.
+     * Return the number of filtered data sets in this DataOutFilter. Data
+     * sets are not filtered so this will be the original number of data sets.
      */
     unsigned int n_data_sets() const
     {
@@ -1360,8 +1318,8 @@ namespace DataOutBase
     };
 
     /**
-    * Empty functions to do base class inheritance.
-    */
+     * Empty functions to do base class inheritance.
+     */
     void flush_points () {};
 
     /**
@@ -1373,8 +1331,7 @@ namespace DataOutBase
 
 
   /**
-   * Provide a data type specifying the presently supported output
-   * formats.
+   * Provide a data type specifying the presently supported output formats.
    */
   enum OutputFormat
   {
@@ -1416,8 +1373,8 @@ namespace DataOutBase
 
     tecplot,
     /**
-     * Output for Tecplot in binary format. Faster and smaller than
-     * text format.
+     * Output for Tecplot in binary format. Faster and smaller than text
+     * format.
      */
     tecplot_binary,
 
@@ -1449,12 +1406,10 @@ namespace DataOutBase
 
 
   /**
-   * Write the given list of patches to the output stream in OpenDX
-   * format.
+   * Write the given list of patches to the output stream in OpenDX format.
    *
-   * Since OpenDX uses some kind of visual data flow oriented
-   * programming language, some of these programs are provided in
-   * <tt>contrib/dx</tt>.
+   * Since OpenDX uses some kind of visual data flow oriented programming
+   * language, some of these programs are provided in <tt>contrib/dx</tt>.
    */
   template <int dim, int spacedim>
   void write_dx (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1466,49 +1421,46 @@ namespace DataOutBase
   /**
    * Write the given list of patches to the output stream in eps format.
    *
-   * Output in this format circumvents the use of auxiliary graphic
-   * programs converting some output format into a graphics
-   * format. This has the advantage that output is easy and fast, and
-   * the disadvantage that you have to give a whole bunch of
-   * parameters which determine the direction of sight, the mode of
-   * colorization, the scaling of the height axis, etc. (Of course,
-   * all these parameters have reasonable default values, which you
+   * Output in this format circumvents the use of auxiliary graphic programs
+   * converting some output format into a graphics format. This has the
+   * advantage that output is easy and fast, and the disadvantage that you
+   * have to give a whole bunch of parameters which determine the direction of
+   * sight, the mode of colorization, the scaling of the height axis, etc. (Of
+   * course, all these parameters have reasonable default values, which you
    * may want to change.)
    *
-   * This function only supports output for two-dimensional
-   * domains (i.e., with dim==2), with values in the vertical
-   * direction taken from a data vector.
-   *
-   * Basically, output consists of the mesh and the cells in between
-   * them. You can draw either of these, or both, or none if you are
-   * really interested in an empty picture. If written, the mesh uses
-   * black lines. The cells in between the mesh are either not printed
-   * (this will result in a loss of hidden line removal, i.e.  you can
-   * "see through" the cells to lines behind), printed in white (which
-   * does nothing apart from the hidden line removal), or colorized
-   * using one of the data vectors (which need not be the same as the
-   * one used for computing the height information) and a customizable
-   * color function. The default color functions chooses the color
-   * between black, blue, green, red and white, with growing values of
-   * the data field chosen for colorization. At present, cells are
-   * displayed with one color per cell only, which is taken from the
-   * value of the data field at the center of the cell; bilinear
-   * interpolation of the color on a cell is not used.
+   * This function only supports output for two-dimensional domains (i.e.,
+   * with dim==2), with values in the vertical direction taken from a data
+   * vector.
+   *
+   * Basically, output consists of the mesh and the cells in between them. You
+   * can draw either of these, or both, or none if you are really interested
+   * in an empty picture. If written, the mesh uses black lines. The cells in
+   * between the mesh are either not printed (this will result in a loss of
+   * hidden line removal, i.e.  you can "see through" the cells to lines
+   * behind), printed in white (which does nothing apart from the hidden line
+   * removal), or colorized using one of the data vectors (which need not be
+   * the same as the one used for computing the height information) and a
+   * customizable color function. The default color functions chooses the
+   * color between black, blue, green, red and white, with growing values of
+   * the data field chosen for colorization. At present, cells are displayed
+   * with one color per cell only, which is taken from the value of the data
+   * field at the center of the cell; bilinear interpolation of the color on a
+   * cell is not used.
    *
    * By default, the viewpoint is chosen like the default viewpoint in
-   * GNUPLOT, i.e.  with an angle of 60 degrees with respect to the
-   * positive z-axis and rotated 30 degrees in positive sense (as seen
-   * from above) away from the negative y-axis.  Of course you can
-   * change these settings.
+   * GNUPLOT, i.e.  with an angle of 60 degrees with respect to the positive
+   * z-axis and rotated 30 degrees in positive sense (as seen from above) away
+   * from the negative y-axis.  Of course you can change these settings.
    *
    * EPS output is written without a border around the picture, i.e. the
-   * bounding box is close to the output on all four sides. Coordinates
-   * are written using at most five digits, to keep picture size at a
-   * reasonable size.
+   * bounding box is close to the output on all four sides. Coordinates are
+   * written using at most five digits, to keep picture size at a reasonable
+   * size.
    *
    * All parameters along with their default values are listed in the
-   * documentation of the <tt>EpsFlags</tt> member class of this
-   * class. See there for more and detailed information.
+   * documentation of the <tt>EpsFlags</tt> member class of this class. See
+   * there for more and detailed information.
    */
   template <int spacedim>
   void write_eps (const std::vector<Patch<2,spacedim> > &patches,
@@ -1518,10 +1470,9 @@ namespace DataOutBase
                   std::ostream                            &out);
 
   /**
-   * This is the same function as above except for domains that are
-   * not two-dimensional. This function is not implemented (and will
-   * throw an error if called) but is declared to allow for
-   * dimension-independent programs.
+   * This is the same function as above except for domains that are not two-
+   * dimensional. This function is not implemented (and will throw an error if
+   * called) but is declared to allow for dimension-independent programs.
    */
   template <int dim, int spacedim>
   void write_eps (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1532,14 +1483,13 @@ namespace DataOutBase
 
 
   /**
-   * Write the given list of patches to the output stream in
-   * GMV format.
+   * Write the given list of patches to the output stream in GMV format.
    *
-   * Data is written in the following format: nodes are considered the
-   * points of the patches. In spatial dimensions less than three,
-   * zeroes are inserted for the missing coordinates. The data vectors
-   * are written as node or cell data, where for the first the data
-   * space is interpolated to (bi-,tri-)linear elements.
+   * Data is written in the following format: nodes are considered the points
+   * of the patches. In spatial dimensions less than three, zeroes are
+   * inserted for the missing coordinates. The data vectors are written as
+   * node or cell data, where for the first the data space is interpolated to
+   * (bi-,tri-)linear elements.
    */
   template <int dim, int spacedim>
   void write_gmv (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1549,64 +1499,60 @@ namespace DataOutBase
                   std::ostream                            &out);
 
   /**
-   * Write the given list of patches to the output stream in gnuplot
-   * format. Visualization of two-dimensional data can then be achieved by
-   * starting <tt>gnuplot</tt> and endtering the commands
+   * Write the given list of patches to the output stream in gnuplot format.
+   * Visualization of two-dimensional data can then be achieved by starting
+   * <tt>gnuplot</tt> and endtering the commands
    *
    * @verbatim
    * set data style lines
    * splot "filename" using 1:2:n
    * @endverbatim
-   * This example assumes that the number of the data vector displayed
-   * is <b>n-2</b>.
+   * This example assumes that the number of the data vector displayed is
+   * <b>n-2</b>.
    *
    * The GNUPLOT format is not able to handle data on unstructured grids
-   * directly. Directly would mean that you only give the vertices and
-   * the solution values thereon and the program constructs its own grid
-   * to represent the data. This is only possible for a structured
-   * tensor product grid in two dimensions. However, it is possible to
-   * give several such patches within one file, which is exactly what
-   * the respective function of this class does: writing each cell's
-   * data as a patch of data, at least if the patches as passed from
-   * derived classes represent cells. Note that the functions on patches
-   * need not be continuous at interfaces between patches, so this
-   * method also works for discontinuous elements. Note also, that
-   * GNUPLOT can do hidden line removal for patched data.
+   * directly. Directly would mean that you only give the vertices and the
+   * solution values thereon and the program constructs its own grid to
+   * represent the data. This is only possible for a structured tensor product
+   * grid in two dimensions. However, it is possible to give several such
+   * patches within one file, which is exactly what the respective function of
+   * this class does: writing each cell's data as a patch of data, at least if
+   * the patches as passed from derived classes represent cells. Note that the
+   * functions on patches need not be continuous at interfaces between
+   * patches, so this method also works for discontinuous elements. Note also,
+   * that GNUPLOT can do hidden line removal for patched data.
    *
    * While this discussion applies to two spatial dimensions, it is more
-   * complicated in 3d. The reason is that we could still use patches,
-   * but it is difficult when trying to visualize them, since if we use
-   * a cut through the data (by, for example, using x- and
-   * z-coordinates, a fixed y-value and plot function values in
-   * z-direction, then the patched data is not a patch in the sense
-   * GNUPLOT wants it any more. Therefore, we use another approach,
-   * namely writing the data on the 3d grid as a sequence of lines,
-   * i.e. two points each associated with one or more data sets.  There
-   * are therefore 12 lines for each subcells of a patch.
-   *
-   * Given the lines as described above, a cut through this data in
-   * Gnuplot can then be achieved like this (& stands for the dollar
-   * sign in the following):
+   * complicated in 3d. The reason is that we could still use patches, but it
+   * is difficult when trying to visualize them, since if we use a cut through
+   * the data (by, for example, using x- and z-coordinates, a fixed y-value
+   * and plot function values in z-direction, then the patched data is not a
+   * patch in the sense GNUPLOT wants it any more. Therefore, we use another
+   * approach, namely writing the data on the 3d grid as a sequence of lines,
+   * i.e. two points each associated with one or more data sets.  There are
+   * therefore 12 lines for each subcells of a patch.
+   *
+   * Given the lines as described above, a cut through this data in Gnuplot
+   * can then be achieved like this (& stands for the dollar sign in the
+   * following):
    * @verbatim
    *   set data style lines
    *   splot [:][:][0:] "T" using 1:2:(&3==.5 ? &4 : -1)
    * @endverbatim
    *
    * This command plots data in x- and y-direction unbounded, but in
-   * z-direction only those data points which are above the x-y-plane
-   * (we assume here a positive solution, if it has negative values, you
-   * might want to decrease the lower bound). Furthermore, it only takes
-   * the data points with z-values (<tt>&3</tt>) equal to 0.5, i.e. a
-   * cut through the domain at <tt>z=0.5</tt>. For the data points on
-   * this plane, the data values of the first data set (<tt>&4</tt>) are
-   * raised in z-direction above the x-y-plane; all other points are
-   * denoted the value <tt>-1</tt> instead of the value of the data
-   * vector and are not plotted due to the lower bound in z plotting
-   * direction, given in the third pair of brackets.
-   *
-   * More complex cuts are possible, including nonlinear ones. Note
-   * however, that only those points which are actually on the
-   * cut-surface are plotted.
+   * z-direction only those data points which are above the x-y-plane (we
+   * assume here a positive solution, if it has negative values, you might
+   * want to decrease the lower bound). Furthermore, it only takes the data
+   * points with z-values (<tt>&3</tt>) equal to 0.5, i.e. a cut through the
+   * domain at <tt>z=0.5</tt>. For the data points on this plane, the data
+   * values of the first data set (<tt>&4</tt>) are raised in z-direction
+   * above the x-y-plane; all other points are denoted the value <tt>-1</tt>
+   * instead of the value of the data vector and are not plotted due to the
+   * lower bound in z plotting direction, given in the third pair of brackets.
+   *
+   * More complex cuts are possible, including nonlinear ones. Note however,
+   * that only those points which are actually on the cut-surface are plotted.
    */
   template <int dim, int spacedim>
   void write_gnuplot (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1616,31 +1562,29 @@ namespace DataOutBase
                       std::ostream                            &out);
 
   /**
-   * Write the given list of patches to the output stream for the
-   * Povray raytracer.
+   * Write the given list of patches to the output stream for the Povray
+   * raytracer.
    *
-   * Output in this format creates a povray source file, include
-   * standard camera and light source definition for rendering with
-   * povray 3.1 At present, this format only supports output for
-   * two-dimensional data, with values in the third direction taken from
-   * a data vector.
+   * Output in this format creates a povray source file, include standard
+   * camera and light source definition for rendering with povray 3.1 At
+   * present, this format only supports output for two-dimensional data, with
+   * values in the third direction taken from a data vector.
    *
    * The output uses two different povray-objects:
    *
    * <ul>
-   * <li> <tt>BICUBIC_PATCH</tt>
-   * A <tt>bicubic_patch</tt> is a 3-dimensional Bezier patch. It consists of 16 Points
-   * describing the surface. The 4 corner points are touched by the object,
-   * while the other 12 points pull and stretch the patch into shape.
-   * One <tt>bicubic_patch</tt> is generated on each patch. Therefor the number of
-   * subdivisions has to be 3 to provide the patch with 16 points.
-   * A bicubic patch is not exact but generates very smooth images.
-   *
-   * <li> <tt>MESH</tt>
-   * The mesh object is used to store large number of triangles.
-   * Every square of the patch data is split into one upper-left and one
-   * lower-right triangle. If the number of subdivisions is three, 32 triangle
-   * are generated for every patch.
+   * <li> <tt>BICUBIC_PATCH</tt> A <tt>bicubic_patch</tt> is a 3-dimensional
+   * Bezier patch. It consists of 16 Points describing the surface. The 4
+   * corner points are touched by the object, while the other 12 points pull
+   * and stretch the patch into shape. One <tt>bicubic_patch</tt> is generated
+   * on each patch. Therefor the number of subdivisions has to be 3 to provide
+   * the patch with 16 points. A bicubic patch is not exact but generates very
+   * smooth images.
+   *
+   * <li> <tt>MESH</tt> The mesh object is used to store large number of
+   * triangles. Every square of the patch data is split into one upper-left
+   * and one lower-right triangle. If the number of subdivisions is three, 32
+   * triangle are generated for every patch.
    *
    * Using the smooth flag povray interpolates the normals on the triangles,
    * imitating a curved surface
@@ -1648,14 +1592,14 @@ namespace DataOutBase
    *
    * All objects get one texture definition called Tex. This texture has to be
    * declared somewhere before the object data. This may be in an external
-   * data file or at the beginning of the output file.
-   * Setting the <tt>external_data</tt> flag to false, an standard camera, light and
+   * data file or at the beginning of the output file. Setting the
+   * <tt>external_data</tt> flag to false, an standard camera, light and
    * texture (scaled to fit the scene) is added to the outputfile. Set to true
-   * an include file "data.inc" is included. This file is not generated by deal
-   * and has to include camera, light and the texture definition Tex.
+   * an include file "data.inc" is included. This file is not generated by
+   * deal and has to include camera, light and the texture definition Tex.
    *
-   * You need povray (>=3.0) to render the scene. The minimum options for povray
-   * are:
+   * You need povray (>=3.0) to render the scene. The minimum options for
+   * povray are:
    * @verbatim
    *   povray +I<inputfile> +W<horiz. size> +H<ver. size> +L<include path>
    * @endverbatim
@@ -1670,11 +1614,10 @@ namespace DataOutBase
                      std::ostream                            &out);
 
   /**
-   * Write the given list of patches to the output stream in
-   * Tecplot ASCII format (FEBLOCK).
+   * Write the given list of patches to the output stream in Tecplot ASCII
+   * format (FEBLOCK).
    *
-   * For more information consult the Tecplot Users and Reference
-   * manuals.
+   * For more information consult the Tecplot Users and Reference manuals.
    */
   template <int dim, int spacedim>
   void write_tecplot (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1684,25 +1627,23 @@ namespace DataOutBase
                       std::ostream                            &out);
 
   /**
-   * Write the given list of patches to the output stream in
-   * Tecplot binary format.
+   * Write the given list of patches to the output stream in Tecplot binary
+   * format.
    *
-   * For this to work properly <tt>./configure</tt> checks for the
-   * Tecplot API at build time. To write Tecplot binary files directly
-   * make sure that the TECHOME environment variable points to the
-   * Tecplot installation directory, and that the files
-   * \$TECHOME/include/TECIO.h and \$TECHOME/lib/tecio.a are readable.
-   * If these files are not available (or in the case of 1D) this
-   * function will simply call write_tecplot() and thus larger ASCII
-   * data files will be produced rather than more efficient Tecplot
-   * binary files.
+   * For this to work properly <tt>./configure</tt> checks for the Tecplot API
+   * at build time. To write Tecplot binary files directly make sure that the
+   * TECHOME environment variable points to the Tecplot installation
+   * directory, and that the files \$TECHOME/include/TECIO.h and
+   * \$TECHOME/lib/tecio.a are readable. If these files are not available (or
+   * in the case of 1D) this function will simply call write_tecplot() and
+   * thus larger ASCII data files will be produced rather than more efficient
+   * Tecplot binary files.
    *
-   * @warning TecplotFlags::tecplot_binary_file_name indicates the name
-   * of the file to be written.  If the file name is not set ASCII
-   * output is produced.
+   * @warning TecplotFlags::tecplot_binary_file_name indicates the name of the
+   * file to be written.  If the file name is not set ASCII output is
+   * produced.
    *
-   * For more information consult the Tecplot Users and Reference
-   * manuals.
+   * For more information consult the Tecplot Users and Reference manuals.
    */
   template <int dim, int spacedim>
   void write_tecplot_binary (
@@ -1714,18 +1655,17 @@ namespace DataOutBase
 
   /**
    * Write the given list of patches to the output stream in UCD format
-   * described in the AVS developer's guide (now AVS). Due
-   * to limitations in the present format, only node based data can be
-   * output, which in one reason why we invented the patch concept. In
-   * order to write higher order elements, you may split them up into
-   * several subdivisions of each cell. These subcells will then,
-   * however, also appear as different cells by programs which
-   * understand the UCD format.
-   *
-   * No use is made of the possibility to give model data since these
-   * are not supported by all UCD aware programs. You may give cell data
-   * in derived classes by setting all values of a given data set on a
-   * patch to the same value.
+   * described in the AVS developer's guide (now AVS). Due to limitations in
+   * the present format, only node based data can be output, which in one
+   * reason why we invented the patch concept. In order to write higher order
+   * elements, you may split them up into several subdivisions of each cell.
+   * These subcells will then, however, also appear as different cells by
+   * programs which understand the UCD format.
+   *
+   * No use is made of the possibility to give model data since these are not
+   * supported by all UCD aware programs. You may give cell data in derived
+   * classes by setting all values of a given data set on a patch to the same
+   * value.
    */
   template <int dim, int spacedim>
   void write_ucd (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1735,21 +1675,21 @@ namespace DataOutBase
                   std::ostream                            &out);
 
   /**
-   * Write the given list of patches to the output stream in VTK
-   * format. The data is written in the traditional VTK format as opposed to the
-   * XML-based format that write_vtu() produces.
+   * Write the given list of patches to the output stream in VTK format. The
+   * data is written in the traditional VTK format as opposed to the XML-based
+   * format that write_vtu() produces.
    *
    * The vector_data_ranges argument denotes ranges of components in the
-   * output that are considered a vector, rather than simply a
-   * collection of scalar fields. The VTK output format has special
-   * provisions that allow these components to be output by a single
-   * name rather than having to group several scalar fields into a
-   * vector later on in the visualization program.
+   * output that are considered a vector, rather than simply a collection of
+   * scalar fields. The VTK output format has special provisions that allow
+   * these components to be output by a single name rather than having to
+   * group several scalar fields into a vector later on in the visualization
+   * program.
    *
    * @note VTK is a legacy format and has largely been supplanted by the VTU
    * format (an XML-structured version of VTK). In particular, VTU allows for
-   * the compression of data and consequently leads to much smaller file
-   * sizes that equivalent VTK files for large files. Since all visualization
+   * the compression of data and consequently leads to much smaller file sizes
+   * that equivalent VTK files for large files. Since all visualization
    * programs that support VTK also support VTU, you should consider using the
    * latter file format instead, by using the write_vtu() function.
    */
@@ -1762,26 +1702,25 @@ namespace DataOutBase
 
 
   /**
-   * Write the given list of patches to the output stream in VTU
-   * format. The data is written in the XML-based VTK format as opposed to the
-   * traditional format that write_vtk() produces.
+   * Write the given list of patches to the output stream in VTU format. The
+   * data is written in the XML-based VTK format as opposed to the traditional
+   * format that write_vtk() produces.
    *
    * The vector_data_ranges argument denotes ranges of components in the
-   * output that are considered a vector, rather than simply a
-   * collection of scalar fields. The VTK output format has special
-   * provisions that allow these components to be output by a single
-   * name rather than having to group several scalar fields into a
-   * vector later on in the visualization program.
-   *
-   * Some visualization programs, such as ParaView, can read several
-   * separate VTU files to parallelize visualization. In that case, you
-   * need a <code>.pvtu</code> file that describes which VTU files form
-   * a group. The DataOutInterface::write_pvtu_record() function can
-   * generate such a master record. Likewise,
-   * DataOutInterface::write_visit_record() does the same for VisIt
-   * (although VisIt can also read <code>pvtu</code> records since version 2.5.1).
-   * Finally, for time dependent problems, you may also want to look
-   * at DataOutInterface::write_pvd_record()
+   * output that are considered a vector, rather than simply a collection of
+   * scalar fields. The VTK output format has special provisions that allow
+   * these components to be output by a single name rather than having to
+   * group several scalar fields into a vector later on in the visualization
+   * program.
+   *
+   * Some visualization programs, such as ParaView, can read several separate
+   * VTU files to parallelize visualization. In that case, you need a
+   * <code>.pvtu</code> file that describes which VTU files form a group. The
+   * DataOutInterface::write_pvtu_record() function can generate such a master
+   * record. Likewise, DataOutInterface::write_visit_record() does the same
+   * for VisIt (although VisIt can also read <code>pvtu</code> records since
+   * version 2.5.1). Finally, for time dependent problems, you may also want
+   * to look at DataOutInterface::write_pvd_record()
    *
    * The use of this function is explained in step-40.
    */
@@ -1793,27 +1732,24 @@ namespace DataOutBase
                   std::ostream                            &out);
 
   /**
-   * This writes the header for the xml based vtu file format. This
-   * routine is used internally together with
-   * DataOutInterface::write_vtu_footer() and DataOutInterface::write_vtu_main()
-   * by DataOutBase::write_vtu().
+   * This writes the header for the xml based vtu file format. This routine is
+   * used internally together with DataOutInterface::write_vtu_footer() and
+   * DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().
    */
   void write_vtu_header (std::ostream &out,
                          const VtkFlags &flags);
 
   /**
-   * This writes the footer for the xml based vtu file format. This
-   * routine is used internally together with
-   * DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_main()
-   * by DataOutBase::write_vtu().
+   * This writes the footer for the xml based vtu file format. This routine is
+   * used internally together with DataOutInterface::write_vtu_header() and
+   * DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().
    */
   void write_vtu_footer (std::ostream &out);
 
   /**
-   * This writes the main part for the xml based vtu file format. This
-   * routine is used internally together with
-   * DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_footer()
-   * by DataOutBase::write_vtu().
+   * This writes the main part for the xml based vtu file format. This routine
+   * is used internally together with DataOutInterface::write_vtu_header() and
+   * DataOutInterface::write_vtu_footer() by DataOutBase::write_vtu().
    */
   template <int dim, int spacedim>
   void write_vtu_main (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1826,22 +1762,21 @@ namespace DataOutBase
    * Write the given list of patches to the output stream in SVG format.
    *
    * SVG (Scalable Vector Graphics) is an XML-based vector image format
-   * developed and maintained by the World Wide Web Consortium (W3C).
-   * This function conforms to the latest specification SVG 1.1,
-   * released on August 16, 2011. Controlling the graphic output is
-   * possible by setting or clearing the respective flags (see the
-   * SvgFlags struct). At present, this format only supports output
-   * for two-dimensional data, with values in the third direction
-   * taken from a data vector.
-   *
-   * For the output, each patch is subdivided into four triangles
-   * which are then written as polygons and filled with a linear
-   * color gradient. The arising coloring of the patches visualizes
-   * the data values at the vertices taken from the specified data
-   * vector. A colorbar can be drawn to encode the coloring.
-   *
-   * @note This function is so far only implemented for two dimensions
-   * with an additional dimension reserved for data information.
+   * developed and maintained by the World Wide Web Consortium (W3C). This
+   * function conforms to the latest specification SVG 1.1, released on August
+   * 16, 2011. Controlling the graphic output is possible by setting or
+   * clearing the respective flags (see the SvgFlags struct). At present, this
+   * format only supports output for two-dimensional data, with values in the
+   * third direction taken from a data vector.
+   *
+   * For the output, each patch is subdivided into four triangles which are
+   * then written as polygons and filled with a linear color gradient. The
+   * arising coloring of the patches visualizes the data values at the
+   * vertices taken from the specified data vector. A colorbar can be drawn to
+   * encode the coloring.
+   *
+   * @note This function is so far only implemented for two dimensions with an
+   * additional dimension reserved for data information.
    */
   template <int spacedim>
   void write_svg (const std::vector<Patch<2,spacedim> > &patches,
@@ -1854,41 +1789,38 @@ namespace DataOutBase
    * Write the given list of patches to the output stream in deal.II
    * intermediate format. This is not a format understood by any other
    * graphics program, but is rather a direct dump of the intermediate
-   * internal format used by deal.II. This internal format is generated
-   * by the various classes that can generate output using the
-   * DataOutBase class, for example from a finite element solution, and
-   * is then converted in the present class to the final graphics
-   * format.
-   *
-   * Note that the intermediate format is what its name suggests: a
-   * direct representation of internal data. It isn't standardized and
-   * will change whenever we change our internal representation. You can
-   * only expect to process files written in this format using the same
-   * version of deal.II that was used for writing.
-   *
-   * The reason why we offer to write out this intermediate format is
-   * that it can be read back into a deal.II program using the
-   * DataOutReader class, which is helpful in at least two contexts:
-   * First, this can be used to later generate graphical output in any
-   * other graphics format presently understood; this way, it is not
-   * necessary to know at run-time which output format is requested, or
-   * if multiple output files in different formats are needed. Secondly,
-   * in contrast to almost all other graphics formats, it is possible to
-   * merge several files that contain intermediate format data, and
-   * generate a single output file from it, which may be again in
-   * intermediate format or any of the final formats. This latter option
-   * is most helpful for parallel programs: as demonstrated in the
+   * internal format used by deal.II. This internal format is generated by the
+   * various classes that can generate output using the DataOutBase class, for
+   * example from a finite element solution, and is then converted in the
+   * present class to the final graphics format.
+   *
+   * Note that the intermediate format is what its name suggests: a direct
+   * representation of internal data. It isn't standardized and will change
+   * whenever we change our internal representation. You can only expect to
+   * process files written in this format using the same version of deal.II
+   * that was used for writing.
+   *
+   * The reason why we offer to write out this intermediate format is that it
+   * can be read back into a deal.II program using the DataOutReader class,
+   * which is helpful in at least two contexts: First, this can be used to
+   * later generate graphical output in any other graphics format presently
+   * understood; this way, it is not necessary to know at run-time which
+   * output format is requested, or if multiple output files in different
+   * formats are needed. Secondly, in contrast to almost all other graphics
+   * formats, it is possible to merge several files that contain intermediate
+   * format data, and generate a single output file from it, which may be
+   * again in intermediate format or any of the final formats. This latter
+   * option is most helpful for parallel programs: as demonstrated in the
    * step-17 example program, it is possible to let only one processor
-   * generate the graphical output for the entire parallel program, but
-   * this can become vastly inefficient if many processors are involved,
-   * because the load is no longer balanced. The way out is to let each
-   * processor generate intermediate graphical output for its chunk of
-   * the domain, and the later merge the different files into one, which
-   * is an operation that is much cheaper than the generation of the
-   * intermediate data.
+   * generate the graphical output for the entire parallel program, but this
+   * can become vastly inefficient if many processors are involved, because
+   * the load is no longer balanced. The way out is to let each processor
+   * generate intermediate graphical output for its chunk of the domain, and
+   * the later merge the different files into one, which is an operation that
+   * is much cheaper than the generation of the intermediate data.
    *
-   * Intermediate format deal.II data is usually stored in files with
-   * the ending <tt>.d2</tt>.
+   * Intermediate format deal.II data is usually stored in files with the
+   * ending <tt>.d2</tt>.
    */
   template <int dim, int spacedim>
   void write_deal_II_intermediate (
@@ -1899,8 +1831,8 @@ namespace DataOutBase
     std::ostream                            &out);
 
   /**
-   * Write the data in data_filter to a single HDF5 file containing both
-   * the mesh and solution values.
+   * Write the data in data_filter to a single HDF5 file containing both the
+   * mesh and solution values.
    */
   template <int dim, int spacedim>
   void write_hdf5_parallel (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1909,11 +1841,11 @@ namespace DataOutBase
                             MPI_Comm comm);
 
   /**
-   * Write the data in data_filter to HDF5 file(s). If write_mesh_file
-   * is false, the mesh data will not be written and the solution
-   * file will contain only the solution values. If write_mesh_file
-   * is true and the filenames are the same, the resulting file will
-   * contain both mesh data and solution values.
+   * Write the data in data_filter to HDF5 file(s). If write_mesh_file is
+   * false, the mesh data will not be written and the solution file will
+   * contain only the solution values. If write_mesh_file is true and the
+   * filenames are the same, the resulting file will contain both mesh data
+   * and solution values.
    */
   template <int dim, int spacedim>
   void write_hdf5_parallel (const std::vector<Patch<dim,spacedim> > &patches,
@@ -1938,44 +1870,40 @@ namespace DataOutBase
   /**
    * Given an input stream that contains data written by
    * write_deal_II_intermediate(), determine the <tt>dim</tt> and
-   * <tt>spacedim</tt> template parameters with which that function
-   * was called, and return them as a pair of values.
+   * <tt>spacedim</tt> template parameters with which that function was
+   * called, and return them as a pair of values.
    *
-   * Note that this function eats a number of elements at the present
-   * position of the stream, and therefore alters it. In order to read
-   * from it using, for example, the DataOutReader class, you may wish
-   * to either reset the stream to its previous position, or close and
-   * reopen it.
+   * Note that this function eats a number of elements at the present position
+   * of the stream, and therefore alters it. In order to read from it using,
+   * for example, the DataOutReader class, you may wish to either reset the
+   * stream to its previous position, or close and reopen it.
    */
   std::pair<unsigned int, unsigned int>
   determine_intermediate_format_dimensions (std::istream &input);
 
   /**
-   * Return the OutputFormat value corresponding to the given
-   * string. If the string does not match any known format, an
-   * exception is thrown.
+   * Return the OutputFormat value corresponding to the given string. If the
+   * string does not match any known format, an exception is thrown.
    *
    * The main purpose of this function is to allow a program to use any
-   * implemented output format without the need to extend the
-   * program's parser each time a new format is implemented.
+   * implemented output format without the need to extend the program's parser
+   * each time a new format is implemented.
    *
-   * To get a list of presently available format names, e.g. to give
-   * it to the ParameterHandler class, use the function
-   * get_output_format_names().
+   * To get a list of presently available format names, e.g. to give it to the
+   * ParameterHandler class, use the function get_output_format_names().
    */
   OutputFormat parse_output_format (const std::string &format_name);
 
   /**
-   * Return a list of implemented output formats. The different names
-   * are separated by vertical bar signs (<tt>`|'</tt>) as used by the
+   * Return a list of implemented output formats. The different names are
+   * separated by vertical bar signs (<tt>`|'</tt>) as used by the
    * ParameterHandler classes.
    */
   std::string get_output_format_names ();
 
   /**
-   * Provide a function which tells us which suffix a file with a
-   * given output format usually has. At present the following formats
-   * are defined:
+   * Provide a function which tells us which suffix a file with a given output
+   * format usually has. At present the following formats are defined:
    * <ul>
    * <li> <tt>dx</tt>: <tt>.dx</tt>
    * <li> <tt>ucd</tt>: <tt>.inp</tt>
@@ -1993,8 +1921,10 @@ namespace DataOutBase
    */
   std::string default_suffix (const OutputFormat output_format);
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -2008,8 +1938,8 @@ namespace DataOutBase
    */
   DeclException0 (ExcNoPatches);
   /**
-    * Exception
-    */
+   * Exception
+   */
   DeclException0 (ExcTecplotAPIError);
   /**
    * Exception
@@ -2026,67 +1956,64 @@ namespace DataOutBase
 
 
 /**
- * This class is the interface to the functions in the DataOutBase namespace, as already its name
- * might suggest. It does not offer much functionality apart from a way to
- * access the implemented formats and a way to dynamically dispatch what output
- * format to chose.
+ * This class is the interface to the functions in the DataOutBase namespace,
+ * as already its name might suggest. It does not offer much functionality
+ * apart from a way to access the implemented formats and a way to dynamically
+ * dispatch what output format to chose.
  *
- * This class is thought as a base class to classes actually
- * generating data for output. It has two abstract virtual functions,
- * get_patches() and get_dataset_names() produce the data which is
- * actually needed. These are the only functions that need to be
- * overloaded by a derived class.  In additional to that, it has a
- * function for each output format supported by the underlying base
- * class which gets the output data using these two virtual functions
- * and passes them to the raw output functions.
+ * This class is thought as a base class to classes actually generating data
+ * for output. It has two abstract virtual functions, get_patches() and
+ * get_dataset_names() produce the data which is actually needed. These are
+ * the only functions that need to be overloaded by a derived class.  In
+ * additional to that, it has a function for each output format supported by
+ * the underlying base class which gets the output data using these two
+ * virtual functions and passes them to the raw output functions.
  *
- * The purpose of this class is mainly two-fold: to support storing flags
- * by which the output in the different output formats are controlled,
- * and means to work with output in a way where output format, flags and
- * other things are determined at run time. In addition to that it offers
- * the abstract interface to derived classes briefly discussed above.
+ * The purpose of this class is mainly two-fold: to support storing flags by
+ * which the output in the different output formats are controlled, and means
+ * to work with output in a way where output format, flags and other things
+ * are determined at run time. In addition to that it offers the abstract
+ * interface to derived classes briefly discussed above.
  *
  *
  * <h3>Output flags</h3>
  *
- * The way we treat flags in this class is very similar to that used in
- * the <tt>GridOut</tt> class. For detailed information on the why's and how's,
- * as well as an example of programming, we refer to the documentation
- * of that class.
+ * The way we treat flags in this class is very similar to that used in the
+ * <tt>GridOut</tt> class. For detailed information on the why's and how's, as
+ * well as an example of programming, we refer to the documentation of that
+ * class.
  *
  * Basically, this class stores a set of flags for each output format
  * supported by the underlying <tt>DataOutBase</tt> class. These are used
  * whenever one of the <tt>write_*</tt> functions is used. By default, the
- * values of these flags are set to reasonable start-ups, but in case
- * you want to change them, you can create a structure holding the flags
- * for one of the output formats and set it using the <tt>set_flags</tt> functions
- * of this class to determine all future output the object might produce
- * by that output format.
+ * values of these flags are set to reasonable start-ups, but in case you want
+ * to change them, you can create a structure holding the flags for one of the
+ * output formats and set it using the <tt>set_flags</tt> functions of this
+ * class to determine all future output the object might produce by that
+ * output format.
  *
  * For information on what parameters are supported by different output
- * functions, please see the documentation of the <tt>DataOutBase</tt> class and
- * its member classes.
+ * functions, please see the documentation of the <tt>DataOutBase</tt> class
+ * and its member classes.
  *
  *
  * <h3>Run time selection of output parameters</h3>
  *
- * In the output flags classes, described above, many flags are
- * defined for output in the different formats. In order to make them
- * available to the input file handler class <tt>ParameterHandler</tt>, each
- * of these has a function declaring these flags to the parameter
- * handler and to read them back from an actual input file. In order
- * to avoid that in user programs these functions have to be called
- * for each available output format and the respective flag class, the
- * present <tt>DataOutInterface</tt> class offers a function
- * <tt>declare_parameters</tt> which calls the respective function of all
- * known output format flags classes. The flags of each such format
- * are packed together in a subsection in the input file.
- * Likewise, there is a function <tt>parse_parameters</tt> which reads
- * these parameters and stores them in the flags associated with
- * this object (see above).
+ * In the output flags classes, described above, many flags are defined for
+ * output in the different formats. In order to make them available to the
+ * input file handler class <tt>ParameterHandler</tt>, each of these has a
+ * function declaring these flags to the parameter handler and to read them
+ * back from an actual input file. In order to avoid that in user programs
+ * these functions have to be called for each available output format and the
+ * respective flag class, the present <tt>DataOutInterface</tt> class offers a
+ * function <tt>declare_parameters</tt> which calls the respective function of
+ * all known output format flags classes. The flags of each such format are
+ * packed together in a subsection in the input file. Likewise, there is a
+ * function <tt>parse_parameters</tt> which reads these parameters and stores
+ * them in the flags associated with this object (see above).
  *
- * Using these functions, you do not have to track which formats are
- * presently implemented.
+ * Using these functions, you do not have to track which formats are presently
+ * implemented.
  *
  * Usage is as follows:
  * @code
@@ -2106,8 +2033,9 @@ namespace DataOutBase
  *   prm.leave_subsection ();
  *   ...
  * @endcode
- * Note that in the present example, the class <tt>DataOut</tt> was used. However, any
- * other class derived from <tt>DataOutInterface</tt> would work alike.
+ * Note that in the present example, the class <tt>DataOut</tt> was used.
+ * However, any other class derived from <tt>DataOutInterface</tt> would work
+ * alike.
  *
  *
  * <h3>Run time selection of formats</h3>
@@ -2121,20 +2049,19 @@ namespace DataOutBase
  * one of the actual <tt>write_*</tt> functions depending on the output format
  * selected by this value.
  *
- * The functions offering the different output format names are,
- * respectively, <tt>default_suffix</tt>, <tt>parse_output_format</tt>, and
+ * The functions offering the different output format names are, respectively,
+ * <tt>default_suffix</tt>, <tt>parse_output_format</tt>, and
  * <tt>get_output_format_names</tt>. They make the selection of ouput formats
- * in parameter files much easier, and especially independent of
- * the formats presently implemented. User programs need therefore not
- * be changed whenever a new format is implemented.
+ * in parameter files much easier, and especially independent of the formats
+ * presently implemented. User programs need therefore not be changed whenever
+ * a new format is implemented.
  *
- * Additionally, objects of this class have a default format, which
- * can be set by the parameter "Output format" of the parameter
- * file. Within a program, this can be changed by the member function
- * <tt>set_default_format</tt>. Using this default format, it is possible to leave
- * the format selection completely to the parameter file. A suitable
- * suffix for the output file name can be obtained by <tt>default_suffix</tt>
- * without arguments.
+ * Additionally, objects of this class have a default format, which can be set
+ * by the parameter "Output format" of the parameter file. Within a program,
+ * this can be changed by the member function <tt>set_default_format</tt>.
+ * Using this default format, it is possible to leave the format selection
+ * completely to the parameter file. A suitable suffix for the output file
+ * name can be obtained by <tt>default_suffix</tt> without arguments.
  *
  * @ingroup output
  * @author Wolfgang Bangerth, 1999
@@ -2149,206 +2076,146 @@ public:
   DataOutInterface ();
 
   /**
-   * Destructor. Does nothing, but is
-   * declared virtual since this class has
+   * Destructor. Does nothing, but is declared virtual since this class has
    * virtual functions.
    */
   virtual ~DataOutInterface ();
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in OpenDX format. See
-   * DataOutBase::write_dx.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in OpenDX
+   * format. See DataOutBase::write_dx.
    */
   void write_dx (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in EPS format. See
-   * DataOutBase::write_eps.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in EPS
+   * format. See DataOutBase::write_eps.
    */
   void write_eps (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in GMV format. See
-   * DataOutBase::write_gmv.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in GMV
+   * format. See DataOutBase::write_gmv.
    */
   void write_gmv (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in GNUPLOT format. See
-   * DataOutBase::write_gnuplot.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in GNUPLOT
+   * format. See DataOutBase::write_gnuplot.
    */
   void write_gnuplot (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in POVRAY format. See
-   * DataOutBase::write_povray.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in POVRAY
+   * format. See DataOutBase::write_povray.
    */
   void write_povray (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in Tecplot format. See
-   * DataOutBase::write_tecplot.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in Tecplot
+   * format. See DataOutBase::write_tecplot.
    */
   void write_tecplot (std::ostream &out) const;
 
   /**
-   * Obtain data through
-   * get_patches() and write it in
-   * the Tecplot binary output
-   * format. Note that the name of
-   * the output file must be
-   * specified through the
-   * TecplotFlags interface.
+   * Obtain data through get_patches() and write it in the Tecplot binary
+   * output format. Note that the name of the output file must be specified
+   * through the TecplotFlags interface.
    */
   void write_tecplot_binary (std::ostream &out) const;
 
   /**
-   * Obtain data through
-   * get_patches() and write it to
-   * <tt>out</tt> in UCD format for
-   * AVS. See
-   * DataOutBase::write_ucd.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in UCD
+   * format for AVS. See DataOutBase::write_ucd.
    */
   void write_ucd (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in Vtk format. See
-   * DataOutBase::write_vtk.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in Vtk
+   * format. See DataOutBase::write_vtk.
    *
    * @note VTK is a legacy format and has largely been supplanted by the VTU
    * format (an XML-structured version of VTK). In particular, VTU allows for
-   * the compression of data and consequently leads to much smaller file
-   * sizes that equivalent VTK files for large files. Since all visualization
+   * the compression of data and consequently leads to much smaller file sizes
+   * that equivalent VTK files for large files. Since all visualization
    * programs that support VTK also support VTU, you should consider using the
    * latter file format instead, by using the write_vtu() function.
    */
   void write_vtk (std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches()
-   * and write it to <tt>out</tt>
-   * in Vtu (VTK's XML) format. See
-   * DataOutBase::write_vtu.
-   *
-   * Some visualization programs,
-   * such as ParaView, can read
-   * several separate VTU files to
-   * parallelize visualization. In
-   * that case, you need a
-   * <code>.pvtu</code> file that
-   * describes which VTU files form
-   * a group. The
-   * DataOutInterface::write_pvtu_record()
-   * function can generate such a
-   * master record. Likewise,
-   * DataOutInterface::write_visit_record()
-   * does the same for older versions of VisIt
-   * (although VisIt can also read <code>pvtu</code> records since version 2.5.1).
-   * Finally, DataOutInterface::write_pvd_record()
-   * can be used to group together
-   * the files that jointly make up
-   * a time dependent simulation.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in Vtu
+   * (VTK's XML) format. See DataOutBase::write_vtu.
+   *
+   * Some visualization programs, such as ParaView, can read several separate
+   * VTU files to parallelize visualization. In that case, you need a
+   * <code>.pvtu</code> file that describes which VTU files form a group. The
+   * DataOutInterface::write_pvtu_record() function can generate such a master
+   * record. Likewise, DataOutInterface::write_visit_record() does the same
+   * for older versions of VisIt (although VisIt can also read
+   * <code>pvtu</code> records since version 2.5.1). Finally,
+   * DataOutInterface::write_pvd_record() can be used to group together the
+   * files that jointly make up a time dependent simulation.
    */
   void write_vtu (std::ostream &out) const;
 
   /**
-   * Collective MPI call to write the
-   * solution from all participating nodes
-   * (those in the given communicator) to a
-   * single compressed .vtu file on a
-   * shared file system.  The communicator
-   * can be a sub communicator of the one
-   * used by the computation.  This routine
-   * uses MPI I/O to achieve high
-   * performance on parallel filesystems.
-   * Also see
+   * Collective MPI call to write the solution from all participating nodes
+   * (those in the given communicator) to a single compressed .vtu file on a
+   * shared file system.  The communicator can be a sub communicator of the
+   * one used by the computation.  This routine uses MPI I/O to achieve high
+   * performance on parallel filesystems. Also see
    * DataOutInterface::write_vtu().
    */
   void write_vtu_in_parallel (const char *filename, MPI_Comm comm) const;
 
   /**
-   * Some visualization programs, such as
-   * ParaView, can read several separate
-   * VTU files to parallelize
-   * visualization. In that case, you need
-   * a <code>.pvtu</code> file that
-   * describes which VTU files (written,
-   * for example, through the write_vtu()
-   * function) form a group. The current
-   * function can generate such a master
-   * record.
-   *
-   * The file so written contains a list of
-   * (scalar or vector) fields whose values
-   * are described by the individual files
-   * that comprise the set of parallel VTU
-   * files along with the names of these
-   * files. This function gets the names
-   * and types of fields through the
-   * get_patches() function of this class
-   * like all the other write_xxx()
-   * functions. The second argument to this
-   * function specifies the names of the
-   * files that form the parallel set.
-   *
-   * @note See DataOutBase::write_vtu for
-   * writing each piece. Also note that
-   * only one parallel process needs to
-   * call the current function, listing the
-   * names of the files written by all
-   * parallel processes.
-   *
-   * @note The use of this function is
-   * explained in step-40.
-   *
-   * @note In order to tell Paraview to
-   * group together multiple <code>pvtu</code>
-   * files that each describe one time
-   * step of a time dependent simulation,
-   * see the
-   * DataOutInterface::write_pvd_record()
-   * function.
+   * Some visualization programs, such as ParaView, can read several separate
+   * VTU files to parallelize visualization. In that case, you need a
+   * <code>.pvtu</code> file that describes which VTU files (written, for
+   * example, through the write_vtu() function) form a group. The current
+   * function can generate such a master record.
+   *
+   * The file so written contains a list of (scalar or vector) fields whose
+   * values are described by the individual files that comprise the set of
+   * parallel VTU files along with the names of these files. This function
+   * gets the names and types of fields through the get_patches() function of
+   * this class like all the other write_xxx() functions. The second argument
+   * to this function specifies the names of the files that form the parallel
+   * set.
+   *
+   * @note See DataOutBase::write_vtu for writing each piece. Also note that
+   * only one parallel process needs to call the current function, listing the
+   * names of the files written by all parallel processes.
    *
-   * @note Older versions of VisIt (before 2.5.1),
-   * can not read <code>pvtu</code>
-   * records. However, it can read
-   * visit records as written by
-   * the write_visit_record()
+   * @note The use of this function is explained in step-40.
+   *
+   * @note In order to tell Paraview to group together multiple
+   * <code>pvtu</code> files that each describe one time step of a time
+   * dependent simulation, see the DataOutInterface::write_pvd_record()
    * function.
+   *
+   * @note Older versions of VisIt (before 2.5.1), can not read
+   * <code>pvtu</code> records. However, it can read visit records as written
+   * by the write_visit_record() function.
    */
   void write_pvtu_record (std::ostream &out,
                           const std::vector<std::string> &piece_names) const;
 
   /**
-   * In ParaView it is possible to visualize time-dependent
-   * data tagged with the current
-   * integration time of a time dependent simulation. To use this
-   * feature you need a <code>.pvd</code>
-   * file that describes which VTU or PVTU file
-   * belongs to which timestep. This function writes a file that
-   * provides this mapping, i.e., it takes a list of pairs each of
-   * which indicates a particular time instant and the corresponding
-   * file that contains the graphical data for this time instant.
-   *
-   * A typical use case, in program that computes a time dependent
-   * solution, would be the following (<code>time</code> and
-   * <code>time_step</code> are member variables of the class with types
-   * <code>double</code> and <code>unsigned int</code>, respectively;
-   * the variable <code>times_and_names</code> is of type
+   * In ParaView it is possible to visualize time-dependent data tagged with
+   * the current integration time of a time dependent simulation. To use this
+   * feature you need a <code>.pvd</code> file that describes which VTU or
+   * PVTU file belongs to which timestep. This function writes a file that
+   * provides this mapping, i.e., it takes a list of pairs each of which
+   * indicates a particular time instant and the corresponding file that
+   * contains the graphical data for this time instant.
+   *
+   * A typical use case, in program that computes a time dependent solution,
+   * would be the following (<code>time</code> and <code>time_step</code> are
+   * member variables of the class with types <code>double</code> and
+   * <code>unsigned int</code>, respectively; the variable
+   * <code>times_and_names</code> is of type
    * <code>std::vector@<std::pair@<double,std::string@> @></code>):
    *
    * @code
@@ -2373,15 +2240,14 @@ public:
    *  }
    * @endcode
    *
-   * @note See DataOutBase::write_vtu or
-   * DataOutInterface::write_pvtu_record for writing solutions at each
-   * timestep.
+   * @note See DataOutBase::write_vtu or DataOutInterface::write_pvtu_record
+   * for writing solutions at each timestep.
    *
-   * @note The second element of each pair, i.e., the file in which
-   * the graphical data for each time is stored, may itself be again
-   * a file that references other files. For example, it could be
-   * the name for a <code>.pvtu</code> file that references multiple
-   * parts of a parallel computation.
+   * @note The second element of each pair, i.e., the file in which the
+   * graphical data for each time is stored, may itself be again a file that
+   * references other files. For example, it could be the name for a
+   * <code>.pvtu</code> file that references multiple parts of a parallel
+   * computation.
    *
    * @author Marco Engelhard, 2012
    */
@@ -2389,21 +2255,23 @@ public:
                          const std::vector<std::pair<double,std::string> >  &times_and_names) const;
 
   /**
-   * This function is the exact equivalent of the write_pvtu_record()
-   * function but for older versions of the VisIt visualization program and for one visualization graph
-   * (or one time step only). See there for the purpose of this function.
+   * This function is the exact equivalent of the write_pvtu_record() function
+   * but for older versions of the VisIt visualization program and for one
+   * visualization graph (or one time step only). See there for the purpose of
+   * this function.
    *
-   * This function is documented in the "Creating a master file for
-   * parallel" section (section 5.7) of the "Getting data into VisIt"
-   * report that can be found here:
+   * This function is documented in the "Creating a master file for parallel"
+   * section (section 5.7) of the "Getting data into VisIt" report that can be
+   * found here:
    * https://wci.llnl.gov/codes/visit/2.0.0/GettingDataIntoVisIt2.0.0.pdf
    */
   void write_visit_record (std::ostream &out,
                            const std::vector<std::string> &piece_names) const;
 
   /**
-   * This function is equivalent to the write_visit_record() above but for multiple
-   * time steps. Here is an example of how the function would be used:
+   * This function is equivalent to the write_visit_record() above but for
+   * multiple time steps. Here is an example of how the function would be
+   * used:
    * @code
    *  DataOut<dim> data_out;
    *
@@ -2424,36 +2292,35 @@ public:
    *  data_out.write_visit_record(visit_output, piece_names);
    * @endcode
    *
-   * This function is documented in the "Creating a master file for
-   * parallel" section (section 5.7) of the "Getting data into VisIt"
-   * report that can be found here:
+   * This function is documented in the "Creating a master file for parallel"
+   * section (section 5.7) of the "Getting data into VisIt" report that can be
+   * found here:
    * https://wci.llnl.gov/codes/visit/2.0.0/GettingDataIntoVisIt2.0.0.pdf
    */
   void write_visit_record (std::ostream &out,
                            const std::vector<std::vector<std::string> > &piece_names) const;
 
   /**
-   * Obtain data through get_patches() and write it to <tt>out</tt> in
-   * SVG format. See DataOutBase::write_svg.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in SVG
+   * format. See DataOutBase::write_svg.
    */
   void write_svg(std::ostream &out) const;
 
   /**
-   * Obtain data through get_patches() and write it to <tt>out</tt> in
-   * deal.II intermediate format. See
-   * DataOutBase::write_deal_II_intermediate.
+   * Obtain data through get_patches() and write it to <tt>out</tt> in deal.II
+   * intermediate format. See DataOutBase::write_deal_II_intermediate.
    *
-   * Note that the intermediate format is what its name suggests: a
-   * direct representation of internal data. It isn't standardized and
-   * will change whenever we change our internal representation. You
-   * can only expect to process files written in this format using the
-   * same version of deal.II that was used for writing.
+   * Note that the intermediate format is what its name suggests: a direct
+   * representation of internal data. It isn't standardized and will change
+   * whenever we change our internal representation. You can only expect to
+   * process files written in this format using the same version of deal.II
+   * that was used for writing.
    */
   void write_deal_II_intermediate (std::ostream &out) const;
 
   /**
    * Create an XDMFEntry based on the data in this DataOutInterface.
-  @deprecated: use create_xdmf_entry(DataOutFilter, ...) instead
+   * @deprecated: use create_xdmf_entry(DataOutFilter, ...) instead
    */
   XDMFEntry create_xdmf_entry (const std::string &h5_filename,
                                const double cur_time,
@@ -2481,8 +2348,9 @@ public:
                                MPI_Comm comm) const;
 
   /**
-   * Write an XDMF file based on the provided vector of XDMFEntry objects. Below is
-   * an example of how to use this function with HDF5 and the DataOutFilter:
+   * Write an XDMF file based on the provided vector of XDMFEntry objects.
+   * Below is an example of how to use this function with HDF5 and the
+   * DataOutFilter:
    *
    * @code
    * DataOutBase::DataOutFilter   data_filter(DataOutBase::DataOutFilterFlags(true, true));
@@ -2504,17 +2372,17 @@ public:
                         MPI_Comm comm) const;
 
   /**
-   * Write the data in this class without redundancy filtering to a
-   * single HDF5 file containing both the mesh and solution values.
-  @deprecated: use write_hdf5_parallel(DataOutFilter, ...) instead
+   * Write the data in this class without redundancy filtering to a single
+   * HDF5 file containing both the mesh and solution values.
+   * @deprecated: use write_hdf5_parallel(DataOutFilter, ...) instead
    */
   void write_hdf5_parallel (const std::string &filename,
                             MPI_Comm comm) const DEAL_II_DEPRECATED;
 
   /**
-   * Write the data in data_filter to a single HDF5 file containing both
-   * the mesh and solution values. Below is an example of how to use this
-   * function with the DataOutFilter:
+   * Write the data in data_filter to a single HDF5 file containing both the
+   * mesh and solution values. Below is an example of how to use this function
+   * with the DataOutFilter:
    *
    * @code
    * DataOutBase::DataOutFilter   data_filter(DataOutBase::DataOutFilterFlags(true, true));
@@ -2528,11 +2396,11 @@ public:
                             const std::string &filename, MPI_Comm comm) const;
 
   /**
-   * Write the data in data_filter to HDF5 file(s). If write_mesh_file
-   * is false, the mesh data will not be written and the solution
-   * file will contain only the solution values. If write_mesh_file
-   * is true and the filenames are the same, the resulting file will
-   * contain both mesh data and solution values.
+   * Write the data in data_filter to HDF5 file(s). If write_mesh_file is
+   * false, the mesh data will not be written and the solution file will
+   * contain only the solution values. If write_mesh_file is true and the
+   * filenames are the same, the resulting file will contain both mesh data
+   * and solution values.
    */
   void write_hdf5_parallel (const DataOutBase::DataOutFilter &data_filter,
                             const bool write_mesh_file, const std::string &mesh_filename, const std::string &solution_filename, MPI_Comm comm) const;
@@ -2547,25 +2415,19 @@ public:
 
 
   /**
-   * Write data and grid to <tt>out</tt>
-   * according to the given data
-   * format. This function simply
-   * calls the appropriate
-   * <tt>write_*</tt> function. If no
-   * output format is requested,
-   * the <tt>default_format</tt> is
-   * written.
+   * Write data and grid to <tt>out</tt> according to the given data format.
+   * This function simply calls the appropriate <tt>write_*</tt> function. If
+   * no output format is requested, the <tt>default_format</tt> is written.
    *
-   * An error occurs if no format
-   * is provided and the default
-   * format is <tt>default_format</tt>.
+   * An error occurs if no format is provided and the default format is
+   * <tt>default_format</tt>.
    */
   void write (std::ostream       &out,
               const DataOutBase::OutputFormat  output_format = DataOutBase::default_format) const;
 
   /**
-   * Set the default format. The value set here is used anytime,
-   * output for format <tt>default_format</tt> is requested.
+   * Set the default format. The value set here is used anytime, output for
+   * format <tt>default_format</tt> is requested.
    */
   void set_default_format (const DataOutBase::OutputFormat default_format);
 
@@ -2615,97 +2477,91 @@ public:
   void set_flags (const DataOutBase::SvgFlags &svg_flags);
 
   /**
-   * Set the flags to be used for output in deal.II intermediate
-   * format.
+   * Set the flags to be used for output in deal.II intermediate format.
    */
   void set_flags (const DataOutBase::Deal_II_IntermediateFlags &deal_II_intermediate_flags);
 
   /**
-   * A function that returns the same string as the respective
-   * function in the base class does; the only exception being that if
-   * the parameter is omitted, then the value for the present default
-   * format is returned, i.e. the correct suffix for the format that
-   * was set through set_default_format() or parse_parameters() before
-   * calling this function.
+   * A function that returns the same string as the respective function in the
+   * base class does; the only exception being that if the parameter is
+   * omitted, then the value for the present default format is returned, i.e.
+   * the correct suffix for the format that was set through
+   * set_default_format() or parse_parameters() before calling this function.
    */
   std::string
   default_suffix (const DataOutBase::OutputFormat output_format = DataOutBase::default_format) const;
 
   /**
-   * Declare parameters for all output formats by declaring
-   * subsections within the parameter file for each output format and
-   * call the respective <tt>declare_parameters</tt> functions of the
-   * flag classes for each output format.
+   * Declare parameters for all output formats by declaring subsections within
+   * the parameter file for each output format and call the respective
+   * <tt>declare_parameters</tt> functions of the flag classes for each output
+   * format.
    *
    * Some of the declared subsections may not contain entries, if the
    * respective format does not export any flags.
    *
-   * Note that the top-level parameters denoting the number of
-   * subdivisions per patch and the output format are not declared,
-   * since they are only passed to virtual functions and are not
-   * stored inside objects of this type. You have to declare them
-   * yourself.
+   * Note that the top-level parameters denoting the number of subdivisions
+   * per patch and the output format are not declared, since they are only
+   * passed to virtual functions and are not stored inside objects of this
+   * type. You have to declare them yourself.
    */
   static void declare_parameters (ParameterHandler &prm);
 
   /**
-   * Read the parameters declared in declare_parameters() and
-   * set the flags for the output formats accordingly.
+   * Read the parameters declared in declare_parameters() and set the flags
+   * for the output formats accordingly.
    *
-   * The flags thus obtained overwrite all previous contents of the
-   * flag objects as default-constructed or set by the set_flags()
-   * function.
+   * The flags thus obtained overwrite all previous contents of the flag
+   * objects as default-constructed or set by the set_flags() function.
    */
   void parse_parameters (ParameterHandler &prm);
 
   /**
-   * Determine an estimate for the memory consumption (in bytes) of
-   * this object. Since sometimes the size of objects can not be
-   * determined exactly (for example: what is the memory consumption
-   * of an STL <tt>std::map</tt> type with a certain number of
-   * elements?), this is only an estimate. however often quite close
-   * to the true value.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   std::size_t memory_consumption () const;
 
 protected:
   /**
-   * This is the abstract function through which derived classes
-   * propagate preprocessed data in the form of Patch structures
-   * (declared in the base class DataOutBase) to the actual output
-   * function. You need to overload this function to allow the output
-   * functions to know what they shall print.
+   * This is the abstract function through which derived classes propagate
+   * preprocessed data in the form of Patch structures (declared in the base
+   * class DataOutBase) to the actual output function. You need to overload
+   * this function to allow the output functions to know what they shall
+   * print.
    */
   virtual
   const std::vector<DataOutBase::Patch<dim,spacedim> > &
   get_patches () const = 0;
 
   /**
-   * Abstract virtual function through which the names of data sets
-   * are obtained by the output functions of the base class.
+   * Abstract virtual function through which the names of data sets are
+   * obtained by the output functions of the base class.
    */
   virtual
   std::vector<std::string>
   get_dataset_names () const = 0;
 
   /**
-   * This functions returns information about how the individual
-   * components of output files that consist of more than one data set
-   * are to be interpreted.
+   * This functions returns information about how the individual components of
+   * output files that consist of more than one data set are to be
+   * interpreted.
    *
-   * It returns a list of index pairs and corresponding name
-   * indicating which components of the output are to be considered
-   * vector-valued rather than just a collection of scalar data. The
-   * index pairs are inclusive; for example, if we have a Stokes
-   * problem in 2d with components (u,v,p), then the corresponding
-   * vector data range should be (0,1), and the returned list would
-   * consist of only a single element with a tuple such as
+   * It returns a list of index pairs and corresponding name indicating which
+   * components of the output are to be considered vector-valued rather than
+   * just a collection of scalar data. The index pairs are inclusive; for
+   * example, if we have a Stokes problem in 2d with components (u,v,p), then
+   * the corresponding vector data range should be (0,1), and the returned
+   * list would consist of only a single element with a tuple such as
    * (0,1,"velocity").
    *
-   * Since some of the derived classes do not know about vector data,
-   * this function has a default implementation that simply returns an
-   * empty string, meaning that all data is to be considered a
-   * collection of scalar fields.
+   * Since some of the derived classes do not know about vector data, this
+   * function has a default implementation that simply returns an empty
+   * string, meaning that all data is to be considered a collection of scalar
+   * fields.
    */
   virtual
   std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
@@ -2713,82 +2569,76 @@ protected:
 
   /**
    * The default number of subdivisions for patches. This is filled by
-   * parse_parameters() and should be obeyed by build_patches() in
-   * derived classes.
+   * parse_parameters() and should be obeyed by build_patches() in derived
+   * classes.
    */
   unsigned int default_subdivisions;
 
 private:
   /**
-   * Standard output format.  Use this format, if output format
-   * default_format is requested. It can be changed by the
-   * <tt>set_format</tt> function or in a parameter file.
+   * Standard output format.  Use this format, if output format default_format
+   * is requested. It can be changed by the <tt>set_format</tt> function or in
+   * a parameter file.
    */
   DataOutBase::OutputFormat default_fmt;
 
   /**
-   * Flags to be used upon output of OpenDX data. Can be changed by
-   * using the <tt>set_flags</tt> function.
+   * Flags to be used upon output of OpenDX data. Can be changed by using the
+   * <tt>set_flags</tt> function.
    */
   DataOutBase::DXFlags     dx_flags;
 
   /**
-   * Flags to be used upon output of UCD data. Can be changed by using
-   * the <tt>set_flags</tt> function.
+   * Flags to be used upon output of UCD data. Can be changed by using the
+   * <tt>set_flags</tt> function.
    */
   DataOutBase::UcdFlags     ucd_flags;
 
   /**
-   * Flags to be used upon output of GNUPLOT data. Can be changed by
-   * using the <tt>set_flags</tt> function.
+   * Flags to be used upon output of GNUPLOT data. Can be changed by using the
+   * <tt>set_flags</tt> function.
    */
   DataOutBase::GnuplotFlags gnuplot_flags;
 
   /**
-   * Flags to be used upon output of POVRAY data. Can be changed by
-   * using the <tt>set_flags</tt> function.
+   * Flags to be used upon output of POVRAY data. Can be changed by using the
+   * <tt>set_flags</tt> function.
    */
   DataOutBase::PovrayFlags povray_flags;
 
   /**
-   * Flags to be used upon output of EPS data in one space
-   * dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of EPS data in one space dimension. Can be
+   * changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::EpsFlags     eps_flags;
 
   /**
-   * Flags to be used upon output of gmv data in one space
-   * dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of gmv data in one space dimension. Can be
+   * changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::GmvFlags     gmv_flags;
 
   /**
-   * Flags to be used upon output of Tecplot data in one space
-   * dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of Tecplot data in one space dimension. Can
+   * be changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::TecplotFlags tecplot_flags;
 
   /**
-   * Flags to be used upon output of vtk data in one space
-   * dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of vtk data in one space dimension. Can be
+   * changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::VtkFlags     vtk_flags;
 
   /**
-   * Flags to be used upon output of svg data in one space
-   * dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of svg data in one space dimension. Can be
+   * changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::SvgFlags     svg_flags;
 
   /**
-   * Flags to be used upon output of deal.II intermediate data in one
-   * space dimension. Can be changed by using the <tt>set_flags</tt>
-   * function.
+   * Flags to be used upon output of deal.II intermediate data in one space
+   * dimension. Can be changed by using the <tt>set_flags</tt> function.
    */
   DataOutBase::Deal_II_IntermediateFlags     deal_II_intermediate_flags;
 };
@@ -2796,35 +2646,33 @@ private:
 
 
 /**
- * A class that is used to read data written in deal.II intermediate
- * format back in, so that it can be written out in any of the other
- * supported graphics formats. This class has two main purposes:
+ * A class that is used to read data written in deal.II intermediate format
+ * back in, so that it can be written out in any of the other supported
+ * graphics formats. This class has two main purposes:
  *
- * The first use of this class is so that application programs can
- * defer the decision of which graphics format to use until after the
- * program has been run. The data is written in intermediate format
- * into a file, and later on it can then be converted into any
- * graphics format you wish. This may be useful, for example, if you
- * want to convert it to gnuplot format to get a quick glimpse and
- * later on want to convert it to OpenDX format as well to get a high
- * quality version of the data. The present class allows to read this
- * intermediate format back into the program, and allows it to be
- * written in any other supported format using the relevant functions
- * of the base class.
+ * The first use of this class is so that application programs can defer the
+ * decision of which graphics format to use until after the program has been
+ * run. The data is written in intermediate format into a file, and later on
+ * it can then be converted into any graphics format you wish. This may be
+ * useful, for example, if you want to convert it to gnuplot format to get a
+ * quick glimpse and later on want to convert it to OpenDX format as well to
+ * get a high quality version of the data. The present class allows to read
+ * this intermediate format back into the program, and allows it to be written
+ * in any other supported format using the relevant functions of the base
+ * class.
  *
- * The second use is mostly useful in parallel programs: rather than
- * having one central process generate the graphical output for the
- * entire program, one can let each process generate the graphical
- * data for the cells it owns, and write it into a separate file in
- * intermediate format. Later on, all these intermediate files can
- * then be read back in and merged together, a process that is fast
- * compared to generating the data in the first place. The use of the
- * intermediate format is mostly because it allows separate files to
- * be merged, while this is almost impossible once the data has been
+ * The second use is mostly useful in parallel programs: rather than having
+ * one central process generate the graphical output for the entire program,
+ * one can let each process generate the graphical data for the cells it owns,
+ * and write it into a separate file in intermediate format. Later on, all
+ * these intermediate files can then be read back in and merged together, a
+ * process that is fast compared to generating the data in the first place.
+ * The use of the intermediate format is mostly because it allows separate
+ * files to be merged, while this is almost impossible once the data has been
  * written out in any of the supported established graphics formats.
  *
- * This second use scenario is explained in some detail in the step-18
- * example program.
+ * This second use scenario is explained in some detail in the step-18 example
+ * program.
  *
  * Both these applications are implemented in the step-19 example program.
  * There, a slight complication is also explained: in order to read data back
@@ -2836,11 +2684,11 @@ private:
  * around using the DataOutBase::determine_intermediate_format_dimensions()
  * function is explained in step-19.
  *
- * Note that the intermediate format is what its name suggests: a
- * direct representation of internal data. It isn't standardized and
- * will change whenever we change our internal representation. You can
- * only expect to process files written in this format using the same
- * version of deal.II that was used for writing.
+ * Note that the intermediate format is what its name suggests: a direct
+ * representation of internal data. It isn't standardized and will change
+ * whenever we change our internal representation. You can only expect to
+ * process files written in this format using the same version of deal.II that
+ * was used for writing.
  *
  * @ingroup input output
  * @author Wolfgang Bangerth, 2005
@@ -2851,33 +2699,31 @@ class DataOutReader : public DataOutInterface<dim,spacedim>
 public:
   /**
    * Read a sequence of patches as written previously by
-   * <tt>DataOutBase::write_deal_II_intermediate</tt> and store them
-   * in the present object. This overwrites any previous content.
+   * <tt>DataOutBase::write_deal_II_intermediate</tt> and store them in the
+   * present object. This overwrites any previous content.
    */
   void read (std::istream &in);
 
   /**
-   * This function can be used to merge the patches read by the other
-   * object into the patches that this present object stores. This is
-   * sometimes handy if one has, for example, a domain decomposition
-   * algorithm where each block is represented by a DoFHandler of its
-   * own, but one wants to output the solution on all the blocks at
-   * the same time. Alternatively, it may also be used for parallel
-   * programs, where each process only generates output for its share
-   * of the cells, even if all processes can see all cells.
+   * This function can be used to merge the patches read by the other object
+   * into the patches that this present object stores. This is sometimes handy
+   * if one has, for example, a domain decomposition algorithm where each
+   * block is represented by a DoFHandler of its own, but one wants to output
+   * the solution on all the blocks at the same time. Alternatively, it may
+   * also be used for parallel programs, where each process only generates
+   * output for its share of the cells, even if all processes can see all
+   * cells.
    *
-   * For this to work, the input files for the present object and the
-   * given argument need to have the same number of output vectors,
-   * and they need to use the same number of subdivisions per
-   * patch. The output will probably look rather funny if patches in
-   * both objects overlap in space.
+   * For this to work, the input files for the present object and the given
+   * argument need to have the same number of output vectors, and they need to
+   * use the same number of subdivisions per patch. The output will probably
+   * look rather funny if patches in both objects overlap in space.
    *
-   * If you call read() for this object after merging in patches, the
-   * previous state is overwritten, and the merged-in patches are
-   * lost.
+   * If you call read() for this object after merging in patches, the previous
+   * state is overwritten, and the merged-in patches are lost.
    *
-   * This function will fail if either this or the other object did
-   * not yet set up any patches.
+   * This function will fail if either this or the other object did not yet
+   * set up any patches.
    *
    * The use of this function is demonstrated in step-19.
    */
@@ -2907,43 +2753,41 @@ public:
 
 protected:
   /**
-   * This is the function through which this class propagates
-   * preprocessed data in the form of Patch structures (declared in
-   * the base class DataOutBase) to the actual output function.
+   * This is the function through which this class propagates preprocessed
+   * data in the form of Patch structures (declared in the base class
+   * DataOutBase) to the actual output function.
    *
-   * It returns the patches as read the last time a stream was given
-   * to the read() function.
+   * It returns the patches as read the last time a stream was given to the
+   * read() function.
    */
   virtual const std::vector<dealii::DataOutBase::Patch<dim,spacedim> > &
   get_patches () const;
 
   /**
-   * Abstract virtual function through which the names of data sets
-   * are obtained by the output functions of the base class.
+   * Abstract virtual function through which the names of data sets are
+   * obtained by the output functions of the base class.
    *
-   * Return the names of the variables as read the last time we read a
-   * file.
+   * Return the names of the variables as read the last time we read a file.
    */
   virtual std::vector<std::string> get_dataset_names () const;
 
   /**
-   * This functions returns information about how the individual
-   * components of output files that consist of more than one data set
-   * are to be interpreted.
+   * This functions returns information about how the individual components of
+   * output files that consist of more than one data set are to be
+   * interpreted.
    *
-   * It returns a list of index pairs and corresponding name
-   * indicating which components of the output are to be considered
-   * vector-valued rather than just a collection of scalar data. The
-   * index pairs are inclusive; for example, if we have a Stokes
-   * problem in 2d with components (u,v,p), then the corresponding
-   * vector data range should be (0,1), and the returned list would
-   * consist of only a single element with a tuple such as
+   * It returns a list of index pairs and corresponding name indicating which
+   * components of the output are to be considered vector-valued rather than
+   * just a collection of scalar data. The index pairs are inclusive; for
+   * example, if we have a Stokes problem in 2d with components (u,v,p), then
+   * the corresponding vector data range should be (0,1), and the returned
+   * list would consist of only a single element with a tuple such as
    * (0,1,"velocity").
    *
-   * Since some of the derived classes do not know about vector data,
-   * this function has a default implementation that simply returns an
-   * empty string, meaning that all data is to be considered a
-   * collection of scalar fields.
+   * Since some of the derived classes do not know about vector data, this
+   * function has a default implementation that simply returns an empty
+   * string, meaning that all data is to be considered a collection of scalar
+   * fields.
    */
   virtual
   std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
@@ -2958,8 +2802,8 @@ private:
   std::vector<std::string> dataset_names;
 
   /**
-   * Information about whether certain components of the output field
-   * are to be considered vectors.
+   * Information about whether certain components of the output field are to
+   * be considered vectors.
    */
   std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
   vector_data_ranges;
@@ -2969,13 +2813,12 @@ private:
 
 
 /**
- * A class to store relevant data to use when writing the light data
- * XDMF file. This should only contain valid data on the root node which
- * writes the files, the rest of the nodes will have valid set to false.
- * The XDMF file in turn points to heavy data files (such as HDF5) where
- * the actual simulation data is stored. This allows flexibility in
- * arranging the data, and also allows the mesh to be separated from
- * the the point data.
+ * A class to store relevant data to use when writing the light data XDMF
+ * file. This should only contain valid data on the root node which writes the
+ * files, the rest of the nodes will have valid set to false. The XDMF file in
+ * turn points to heavy data files (such as HDF5) where the actual simulation
+ * data is stored. This allows flexibility in arranging the data, and also
+ * allows the mesh to be separated from the the point data.
  */
 class XDMFEntry
 {
@@ -3050,11 +2893,10 @@ namespace DataOutBase
   /* -------------------- template functions ------------------- */
 
   /**
-   * Output operator for an object of type
-   * <tt>DataOutBase::Patch</tt>. This operator dumps the intermediate
-   * graphics format represented by the patch data structure. It may
-   * later be converted into regular formats for a number of graphics
-   * programs.
+   * Output operator for an object of type <tt>DataOutBase::Patch</tt>. This
+   * operator dumps the intermediate graphics format represented by the patch
+   * data structure. It may later be converted into regular formats for a
+   * number of graphics programs.
    *
    * @author Wolfgang Bangerth, 2005
    */
@@ -3066,10 +2908,10 @@ namespace DataOutBase
 
 
   /**
-   * Input operator for an object of type
-   * <tt>DataOutBase::Patch</tt>. This operator reads the intermediate
-   * graphics format represented by the patch data structure, using the
-   * format in which it was written using the operator<<.
+   * Input operator for an object of type <tt>DataOutBase::Patch</tt>. This
+   * operator reads the intermediate graphics format represented by the patch
+   * data structure, using the format in which it was written using the
+   * operator<<.
    *
    * @author Wolfgang Bangerth, 2005
    */
index 8961bb8bc9242f6b4fbfb7141f97e99dd2d978ba..596a029674506bb67108689f3302726921f033c7 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
-   This class represents the (tangential) derivatives of a function
-   $ f: {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$.
-   Such functions are always used to map the reference dim-dimensional
-   cell into spacedim-dimensional space.
-   For such objects, the first  derivative of the function is a linear map from
-   ${\mathbb R}^{\text{dim}}$  to ${\mathbb R}^{\text{spacedim}}$,
-   the second derivative a bilinear map
-   from  ${\mathbb R}^{\text{dim}} \times  {\mathbb R}^{\text{dim}}$
-   to ${\mathbb R}^{\text{spacedim}}$ and so on.
-
-   In deal.II we represent these derivaties using objects of
-   type DerivativeForm<1,dim,spacedim>, DerivativeForm<2,dim,spacedim> and so on.
-
-   @author Sebastian Pauletti, 2011
-*/
+ * This class represents the (tangential) derivatives of a function $ f:
+ * {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$. Such
+ * functions are always used to map the reference dim-dimensional cell into
+ * spacedim-dimensional space. For such objects, the first  derivative of the
+ * function is a linear map from ${\mathbb R}^{\text{dim}}$  to ${\mathbb
+ * R}^{\text{spacedim}}$, the second derivative a bilinear map from  ${\mathbb
+ * R}^{\text{dim}} \times  {\mathbb R}^{\text{dim}}$ to ${\mathbb
+ * R}^{\text{spacedim}}$ and so on.  In deal.II we represent these derivaties
+ * using objects of type DerivativeForm<1,dim,spacedim>,
+ * DerivativeForm<2,dim,spacedim> and so on.
+ * @author Sebastian Pauletti, 2011
+ */
 template <int order, int dim, int spacedim>
 class DerivativeForm
 {
 public:
   /**
-   * Constructor. Initialize all entries
-   * to zero.
+   * Constructor. Initialize all entries to zero.
    */
   DerivativeForm ();
 
   /**
-     Constructor from a second order tensor.
-  */
+   * Constructor from a second order tensor.
+   */
   DerivativeForm (const Tensor<2,dim> &);
 
   /**
@@ -62,69 +58,60 @@ public:
   const Tensor<order,dim> &operator [] (const unsigned int i) const;
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   DerivativeForm   &operator = (const DerivativeForm <order, dim, spacedim> &);
 
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   DerivativeForm   &operator = (const Tensor<2,dim> &);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   DerivativeForm   &operator = (const Tensor<1,dim> &);
 
   /**
-     Converts a DerivativeForm <1,dim, dim>
-     to Tensor<2,dim>.
-     If the derivative is the Jacobian of F,
-     then Tensor[i] = grad(F^i).
-  */
+   * Converts a DerivativeForm <1,dim, dim> to Tensor<2,dim>. If the
+   * derivative is the Jacobian of F, then Tensor[i] = grad(F^i).
+   */
   operator Tensor<2,dim>() const;
 
   /**
-     Converts a DerivativeForm <1, dim, 1>
-     to Tensor<1,dim>.
-  */
+   * Converts a DerivativeForm <1, dim, 1> to Tensor<1,dim>.
+   */
   operator Tensor<1,dim>() const;
 
   /**
-     Return the transpose of a rectangular DerivativeForm,
-     that is to say viewed as a two dimensional matrix.
-  */
+   * Return the transpose of a rectangular DerivativeForm, that is to say
+   * viewed as a two dimensional matrix.
+   */
   DerivativeForm<1, spacedim, dim> transpose () const;
 
 
   /**
-     Computes the volume element associated with the
-     jacobian of the tranformation F.
-     That is to say if $DF$ is square, it computes
-     $\det(DF)$, in case DF is not square returns
-     $\sqrt(\det(DF^{t} * DF))$.
-  */
+   * Computes the volume element associated with the jacobian of the
+   * tranformation F. That is to say if $DF$ is square, it computes
+   * $\det(DF)$, in case DF is not square returns $\sqrt(\det(DF^{t} * DF))$.
+   */
   double determinant () const;
 
 
   /**
-     Assuming (*this) stores the jacobian of
-     the mapping F, it computes its covariant
-     matrix, namely $DF*G^{-1}$, where
-     $G = DF^{t}*DF$.
-     If $DF$ is square, covariant from
-     gives $DF^{-t}$.
-  */
+   * Assuming (*this) stores the jacobian of the mapping F, it computes its
+   * covariant matrix, namely $DF*G^{-1}$, where $G = DF^{t}*DF$. If $DF$ is
+   * square, covariant from gives $DF^{-t}$.
+   */
   DerivativeForm<1, dim, spacedim> covariant_form() const;
 
 
 
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   static std::size_t memory_consumption ();
 
@@ -137,15 +124,15 @@ public:
 
 
 private:
-  /** Auxiliary function that computes
-      (*this) * T^{t} */
+  /**
+   * Auxiliary function that computes (*this) * T^{t}
+   */
   DerivativeForm<1, dim, spacedim> times_T_t (Tensor<2,dim> T) const;
 
 
 private:
   /**
-   * Array of tensors holding the
-   * subelements.
+   * Array of tensors holding the subelements.
    */
   Tensor<order,dim> tensor[spacedim];
 
@@ -393,15 +380,12 @@ DerivativeForm<order, dim, spacedim>::memory_consumption ()
 
 
 /**
-   One of the uses of DerivativeForm is to apply it as a transformation.
-   This is what this function does.
-
-   If @p T is DerivativeForm<1,dim,1> it computes $DF * T$,
-   if @p T is DerivativeForm<1,dim,rank> it computes $T*DF^{t}$.
-
-   @relates DerivativeForm
-   @author Sebastian Pauletti, 2011
-*/
+ * One of the uses of DerivativeForm is to apply it as a transformation. This
+ * is what this function does.  If @p T is DerivativeForm<1,dim,1> it computes
+ * $DF * T$, if @p T is DerivativeForm<1,dim,rank> it computes $T*DF^{t}$.
+ * @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
 template <int spacedim, int dim>
 inline
 Tensor<1, spacedim>
@@ -417,11 +401,10 @@ apply_transformation (const DerivativeForm<1,dim,spacedim> &DF,
 
 
 /**
-   Similar to previous apply_transformation.
-   It computes $T*DF^{t}$
-   @relates DerivativeForm
-   @author Sebastian Pauletti, 2011
-*/
+ * Similar to previous apply_transformation. It computes $T*DF^{t}$ @relates
+ * DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
 //rank=2
 template <int spacedim, int dim>
 inline
@@ -438,11 +421,10 @@ apply_transformation (const DerivativeForm<1,dim,spacedim> &DF,
 }
 
 /**
-   Similar to previous apply_transformation.
-   It computes $DF2*DF1^{t}$
-   @relates DerivativeForm
-   @author Sebastian Pauletti, 2011
-*/
+ * Similar to previous apply_transformation. It computes $DF2*DF1^{t}$
+ * @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
 template <int spacedim, int dim>
 inline
 Tensor<2, spacedim>
@@ -459,11 +441,10 @@ apply_transformation (const DerivativeForm<1,dim,spacedim> &DF1,
 
 
 /**
-   Transpose of a rectangular DerivativeForm DF,
-   mostly for compatibility reasons.
-   @relates DerivativeForm
-   @author Sebastian Pauletti, 2011
-*/
+ * Transpose of a rectangular DerivativeForm DF, mostly for compatibility
+ * reasons. @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
 template <int dim, int spacedim>
 inline
 DerivativeForm<1,spacedim,dim>
index 89cad3e1dfa93c29f3dc674642a2b43a2fd88aa4..c6ae12838ae47073aa259d2b3e59e96b8a90cc55 100644 (file)
@@ -28,13 +28,13 @@ DEAL_II_NAMESPACE_OPEN
 namespace Algorithms
 {
   /**
-   * Objects of this kind are used to notify interior applications of
-   * changes provoked by an outer loop. They are handed to the
-   * application through Operator::notify() and it is up to the
-   * actual application how to handle them.
+   * Objects of this kind are used to notify interior applications of changes
+   * provoked by an outer loop. They are handed to the application through
+   * Operator::notify() and it is up to the actual application how to handle
+   * them.
    *
-   * Event is organized as an extensible binary enumerator. Every class
-   * can add its own events using assign(). A typical code example is
+   * Event is organized as an extensible binary enumerator. Every class can
+   * add its own events using assign(). A typical code example is
    *
    * @code
    * class A
@@ -49,26 +49,20 @@ namespace Algorithms
   {
   public:
     /**
-     * This function registers a
-     * new event type and assigns a
-     * unique identifier to it. The
-     * result of this function
-     * should be stored for later
-     * use.
+     * This function registers a new event type and assigns a unique
+     * identifier to it. The result of this function should be stored for
+     * later use.
      */
     static Event assign (const char *name);
 
     /**
-     * If you forgot to store the
-     * result of assign, here is
-     * how to retrieve it knowing
-     * the name.
+     * If you forgot to store the result of assign, here is how to retrieve it
+     * knowing the name.
      */
 //      static Event find(const std::string& name);
 
     /**
-     * Constructor, generating a
-     * clear Event.
+     * Constructor, generating a clear Event.
      */
     Event ();
 
@@ -93,15 +87,13 @@ namespace Algorithms
     Event &operator -= (const Event &event);
 
     /**
-     * Test whether all the flags
-     * set in the other Event are
-     * also set in this one.
+     * Test whether all the flags set in the other Event are also set in this
+     * one.
      */
     bool test (const Event &event) const;
 
     /**
-     * Return <tt>true</tt> if any
-     * event is set.
+     * Return <tt>true</tt> if any event is set.
      */
     bool any () const;
 
@@ -119,11 +111,8 @@ namespace Algorithms
 
   private:
     /**
-     * Sometimes, actions have to
-     * be taken by all
-     * means. Therefore, if this
-     * value is true, test() always
-     * returns true.
+     * Sometimes, actions have to be taken by all means. Therefore, if this
+     * value is true, test() always returns true.
      */
     bool all_true;
 
@@ -145,9 +134,7 @@ namespace Algorithms
   namespace Events
   {
     /**
-     * The program has just started
-     * and everything should be
-     * new.
+     * The program has just started and everything should be new.
      */
     extern const Event initial;
 
@@ -157,15 +144,12 @@ namespace Algorithms
     extern const Event remesh;
 
     /**
-     * The current derivative leads
-     * to slow convergence of
-     * Newton's method.
+     * The current derivative leads to slow convergence of Newton's method.
      */
     extern const Event bad_derivative;
 
     /**
-     * The time stepping scheme
-     * starts a new time step.
+     * The time stepping scheme starts a new time step.
      */
     extern const Event new_time;
 
@@ -299,8 +283,7 @@ namespace Algorithms
 
 
   /**
-   * Output shift operator for
-   * events. Calls Event::print().
+   * Output shift operator for events. Calls Event::print().
    *
    * @relates Event
    */
index 9eb2006be1b30be0b65c3430099c6cb971a38815..4db4a7e09e9bf87a97c41f8e24748ed88570a64d 100644 (file)
@@ -17,8 +17,7 @@
 #define __deal2__exceptions_h
 
 /**
- * @file
- * Here, the deal.II exception handling is located.
+ * @file Here, the deal.II exception handling is located.
  */
 
 #include <deal.II/base/config.h>
@@ -31,13 +30,13 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class is the base class for all exception classes. Do not use
- * its methods and variables directly since the interface and
- * mechanism may be subject to change. Rather create new exception
- * classes using the <tt>DeclException</tt> macro family.
+ * This class is the base class for all exception classes. Do not use its
+ * methods and variables directly since the interface and mechanism may be
+ * subject to change. Rather create new exception classes using the
+ * <tt>DeclException</tt> macro family.
  *
- * See the @ref Exceptions module for more details on this class and
- * what can be done with classes derived from it.
+ * See the @ref Exceptions module for more details on this class and what can
+ * be done with classes derived from it.
  *
  * @ingroup Exceptions
  * @author Wolfgang Bangerth, 1997, 1998, Matthias Maier, 2013
@@ -61,9 +60,9 @@ public:
   virtual ~ExceptionBase () throw();
 
   /**
-   * Set the file name and line of where the exception appeared as
-   * well as the violated condition and the name of the exception as
-   * a char pointer. This function also populates the stacktrace.
+   * Set the file name and line of where the exception appeared as well as the
+   * violated condition and the name of the exception as a char pointer. This
+   * function also populates the stacktrace.
    */
   void set_fields (const char *file,
                    const int   line,
@@ -88,14 +87,14 @@ public:
   void print_exc_data (std::ostream &out) const;
 
   /**
-   * Print more specific information about the exception which
-   * occurred. Overload this function in your own exception classes.
+   * Print more specific information about the exception which occurred.
+   * Overload this function in your own exception classes.
    */
   virtual void print_info (std::ostream &out) const;
 
   /**
-   * Print a stacktrace, if one has been recorded previously, to the
-   * given stream.
+   * Print a stacktrace, if one has been recorded previously, to the given
+   * stream.
    */
   void print_stack_trace (std::ostream &out) const;
 
@@ -126,14 +125,14 @@ protected:
   const char  *exc;
 
   /**
-   * A backtrace to the position where the problem happened, if the
-   * system supports this.
+   * A backtrace to the position where the problem happened, if the system
+   * supports this.
    */
   mutable char **stacktrace;
 
   /**
-   * The number of stacktrace frames that are stored in the previous
-   * variable. Zero if the system does not support stack traces.
+   * The number of stacktrace frames that are stored in the previous variable.
+   * Zero if the system does not support stack traces.
    */
   int n_stacktrace_frames;
 
@@ -151,8 +150,8 @@ private:
   void generate_message() const;
 
   /**
-   * A pointer to the c_string that will be printed by what(). It is
-   * populated by generate_message()
+   * A pointer to the c_string that will be printed by what(). It is populated
+   * by generate_message()
    */
   mutable std::string what_str;
 };
@@ -160,8 +159,8 @@ private:
 
 
 /**
- * In this namespace, functions in connection with the Assert and
- * AssertThrow mechanism are declared.
+ * In this namespace, functions in connection with the Assert and AssertThrow
+ * mechanism are declared.
  *
  * @ingroup Exceptions
  */
@@ -172,12 +171,11 @@ namespace deal_II_exceptions
    * Set a string that is printed upon output of the message indicating a
    * triggered <tt>Assert</tt> statement. This string, which is printed in
    * addition to the usual output may indicate information that is otherwise
-   * not readily available unless we are using a debugger. For example,
-   * with distributed programs on cluster computers, the output of all
-   * processes is redirected to the same console window. In this case,
-   * it is convenient to set as additional name the name of the host on
-   * which the program runs, so that one can see in which instance of the
-   * program the exception occurred.
+   * not readily available unless we are using a debugger. For example, with
+   * distributed programs on cluster computers, the output of all processes is
+   * redirected to the same console window. In this case, it is convenient to
+   * set as additional name the name of the host on which the program runs, so
+   * that one can see in which instance of the program the exception occurred.
    *
    * The string pointed to by the argument is copied, so doesn't need to be
    * stored after the call to this function.
@@ -188,33 +186,32 @@ namespace deal_II_exceptions
   void set_additional_assert_output (const char *const p);
 
   /**
-   * Calling this function disables printing a stacktrace along with
-   * the other output printed when an exception occurs. Most of the time,
-   * you will want to see such a stacktrace; suppressing it, however, is
-   * useful if one wants to compare the output of a program across different
-   * machines and systems, since the stacktrace shows memory addresses
-   * and library names/paths that depend on the exact setup of a machine.
+   * Calling this function disables printing a stacktrace along with the other
+   * output printed when an exception occurs. Most of the time, you will want
+   * to see such a stacktrace; suppressing it, however, is useful if one wants
+   * to compare the output of a program across different machines and systems,
+   * since the stacktrace shows memory addresses and library names/paths that
+   * depend on the exact setup of a machine.
    */
   void suppress_stacktrace_in_exceptions ();
 
   /**
-   * Calling this function switches off the use of <tt>std::abort()</tt>
-   * when an exception is created using the Assert() macro. Instead, the
-   * Exception will be thrown using 'throw', so it can be caught if
-   * desired. Generally, you want to abort the execution of a program when
-   * Assert() is called, but it needs to be switched off if you want to log
-   * all exceptions created, or if you want to test if an assertion is
-   * working correctly. This is done for example in regression tests.
-   * Please note that some fatal errors will still call abort(), e.g. when
-   * an exception is caught during exception handling.
+   * Calling this function switches off the use of <tt>std::abort()</tt> when
+   * an exception is created using the Assert() macro. Instead, the Exception
+   * will be thrown using 'throw', so it can be caught if desired. Generally,
+   * you want to abort the execution of a program when Assert() is called, but
+   * it needs to be switched off if you want to log all exceptions created, or
+   * if you want to test if an assertion is working correctly. This is done
+   * for example in regression tests. Please note that some fatal errors will
+   * still call abort(), e.g. when an exception is caught during exception
+   * handling.
    */
   void disable_abort_on_exception ();
 
   /**
-   * The functions in this namespace are in connection with the Assert
-   * and AssertThrow mechanism but are solely for internal purposes and
-   * are not for use outside the exception handling and throwing
-   * mechanism.
+   * The functions in this namespace are in connection with the Assert and
+   * AssertThrow mechanism but are solely for internal purposes and are not
+   * for use outside the exception handling and throwing mechanism.
    *
    * @ingroup Exceptions
    */
@@ -225,15 +222,15 @@ namespace deal_II_exceptions
      * Conditionally abort the program.
      *
      * Depending on whether disable_abort_on_exception was called, this
-     * function either aborts the program flow by printing the error
-     * message provided by @p exc and calling <tt>std::abort()</tt>, or
-     * throws @p exc instead (if @p nothrow is set to <tt>false</tt>).
+     * function either aborts the program flow by printing the error message
+     * provided by @p exc and calling <tt>std::abort()</tt>, or throws @p exc
+     * instead (if @p nothrow is set to <tt>false</tt>).
      *
-     * If the boolean @p nothrow is set to true and
-     * disable_abort_on_exception was called, the exception type is just
-     * printed to deallog and program flow continues. This is useful if
-     * throwing an exception is prohibited (e.g. in a destructor with
-     * <tt>noexcept(true)</tt> or <tt>throw()</tt>).
+     * If the boolean @p nothrow is set to true and disable_abort_on_exception
+     * was called, the exception type is just printed to deallog and program
+     * flow continues. This is useful if throwing an exception is prohibited
+     * (e.g. in a destructor with <tt>noexcept(true)</tt> or
+     * <tt>throw()</tt>).
      */
     void abort (const ExceptionBase &exc, bool nothrow = false);
 
@@ -248,8 +245,8 @@ namespace deal_II_exceptions
     };
 
     /**
-     * This routine does the main work for the exception generation
-     * mechanism used in the <tt>Assert</tt> macro.
+     * This routine does the main work for the exception generation mechanism
+     * used in the <tt>Assert</tt> macro.
      *
      * @ref ExceptionBase
      */
@@ -285,9 +282,9 @@ namespace deal_II_exceptions
 
 
 /**
- * This is the main routine in the exception mechanism for debug mode
- * error checking. It asserts that a certain condition is fulfilled,
- * otherwise issues an error and aborts the program.
+ * This is the main routine in the exception mechanism for debug mode error
+ * checking. It asserts that a certain condition is fulfilled, otherwise
+ * issues an error and aborts the program.
  *
  * See the <tt>ExceptionBase</tt> class for more information.
  *
@@ -310,12 +307,12 @@ namespace deal_II_exceptions
 
 
 /**
- * A variant of the <tt>Assert</tt> macro above that exhibits the same
- * runtime behaviour as long as disable_abort_on_exception was not called.
+ * A variant of the <tt>Assert</tt> macro above that exhibits the same runtime
+ * behaviour as long as disable_abort_on_exception was not called.
  *
- * However, if disable_abort_on_exception was called, this macro merely
- * prints the exception that would be thrown to deallog and continues
- * normally without throwing an exception.
+ * However, if disable_abort_on_exception was called, this macro merely prints
+ * the exception that would be thrown to deallog and continues normally
+ * without throwing an exception.
  *
  * See the <tt>ExceptionBase</tt> class for more information.
  *
@@ -339,9 +336,9 @@ namespace deal_II_exceptions
 
 
 /**
- * This is the main routine in the exception mechanism for run-time
- * mode error checking. It assert that a certain condition is
- * fulfilled, otherwise issues an error and aborts the program.
+ * This is the main routine in the exception mechanism for run-time mode error
+ * checking. It assert that a certain condition is fulfilled, otherwise issues
+ * an error and aborts the program.
  *
  * See the <tt>ExceptionBase</tt> class for more information.
  *
@@ -382,8 +379,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with one
- * additional parameter.
+ * Declare an exception class derived from ExceptionBase with one additional
+ * parameter.
  *
  * @ingroup Exceptions
  */
@@ -401,8 +398,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with
- * two additional parameters.
+ * Declare an exception class derived from ExceptionBase with two additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -422,8 +419,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with
- * three additional parameters.
+ * Declare an exception class derived from ExceptionBase with three additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -444,8 +441,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with
- * four additional parameters.
+ * Declare an exception class derived from ExceptionBase with four additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -468,8 +465,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with
- * five additional parameters.
+ * Declare an exception class derived from ExceptionBase with five additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -506,8 +503,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with one
- * additional parameter.
+ * Declare an exception class derived from ExceptionBase with one additional
+ * parameter.
  *
  * @ingroup Exceptions
  */
@@ -516,8 +513,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with two
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with two additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -526,8 +523,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with three
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with three additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -536,8 +533,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with four
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with four additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -546,8 +543,8 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare an exception class derived from ExceptionBase with five
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with five additional
+ * parameters.
  *
  * @ingroup Exceptions
  */
@@ -558,10 +555,10 @@ namespace deal_II_exceptions
 
 
 /**
- * Declare some exceptions that occur over and over. This way, you can
- * simply use these exceptions, instead of having to declare them locally
- * in your class. The namespace in which these exceptions are declared is
- * later included into the global namespace by
+ * Declare some exceptions that occur over and over. This way, you can simply
+ * use these exceptions, instead of having to declare them locally in your
+ * class. The namespace in which these exceptions are declared is later
+ * included into the global namespace by
  * @code
  * using namespace StandardExceptions;
  * @endcode
@@ -588,9 +585,9 @@ namespace StandardExceptions
   /**
    * Exception raised if a number is not finite.
    *
-   * This exception should be used to catch infinite or not a number
-   * results of arithmetic operations that do not result from a division by
-   * zero (use ExcDivideByZero for those).
+   * This exception should be used to catch infinite or not a number results
+   * of arithmetic operations that do not result from a division by zero (use
+   * ExcDivideByZero for those).
    */
   DeclException0 (ExcNumberNotFinite);
 
@@ -600,9 +597,8 @@ namespace StandardExceptions
   DeclException0 (ExcOutOfMemory);
 
   /**
-   * A memory handler reached a point where all allocated objects should
-   * have been released. Since this exception is thrown, some were still
-   * allocated.
+   * A memory handler reached a point where all allocated objects should have
+   * been released. Since this exception is thrown, some were still allocated.
    */
   DeclException1 (ExcMemoryLeak, int,
                   << "Destroying memory handler while " << arg1
@@ -616,59 +612,57 @@ namespace StandardExceptions
   /**
    * An error occurred opening the named file.
    *
-   * The constructor takes a single argument of type <tt>char*</tt>
-   * naming the file.
+   * The constructor takes a single argument of type <tt>char*</tt> naming the
+   * file.
    */
   DeclException1 (ExcFileNotOpen,
                   char *,
                   << "Could not open file " << arg1);
 
   /**
-   * Exception denoting a part of the library or application program that
-   * has not yet been implemented. In many cases, this only indicates that
-   * there wasn't much need for something yet, not that this is difficult
-   * to implement. It is therefore quite worth the effort to take a look
-   * at the corresponding place and see whether it can be implemented
-   * without too much effort.
+   * Exception denoting a part of the library or application program that has
+   * not yet been implemented. In many cases, this only indicates that there
+   * wasn't much need for something yet, not that this is difficult to
+   * implement. It is therefore quite worth the effort to take a look at the
+   * corresponding place and see whether it can be implemented without too
+   * much effort.
    */
   DeclException0 (ExcNotImplemented);
 
   /**
-   * This exception usually indicates that some condition which the
-   * programmer thinks must be satisfied at a certain point in an algorithm,
-   * is not fulfilled. This might be due to some programming error above,
-   * due to changes to the algorithm that did not preserve this assertion,
-   * or due to assumptions the programmer made that are not valid at all
-   * (i.e. the exception is thrown although there is no error here). Within
-   * the library, this exception is most often used when we write some kind
-   * of complicated algorithm and are not yet sure whether we got it right;
-   * we then put in assertions after each part of the algorithm that check
-   * for some conditions that should hold there, and throw an exception
-   * if they do not.
+   * This exception usually indicates that some condition which the programmer
+   * thinks must be satisfied at a certain point in an algorithm, is not
+   * fulfilled. This might be due to some programming error above, due to
+   * changes to the algorithm that did not preserve this assertion, or due to
+   * assumptions the programmer made that are not valid at all (i.e. the
+   * exception is thrown although there is no error here). Within the library,
+   * this exception is most often used when we write some kind of complicated
+   * algorithm and are not yet sure whether we got it right; we then put in
+   * assertions after each part of the algorithm that check for some
+   * conditions that should hold there, and throw an exception if they do not.
    *
-   * We usually leave in these assertions even after we are confident
-   * that the implementation is correct, since if someone later changes
-   * or extends the algorithm, these exceptions will indicate to him if he
-   * violates assumptions that are used later in the algorithm. Furthermore,
-   * it sometimes happens that an algorithm does not work in very rare
-   * corner cases. These cases will then be trapped sooner or later by the
-   * exception, so that the algorithm can then be fixed for these cases
-   * as well.
+   * We usually leave in these assertions even after we are confident that the
+   * implementation is correct, since if someone later changes or extends the
+   * algorithm, these exceptions will indicate to him if he violates
+   * assumptions that are used later in the algorithm. Furthermore, it
+   * sometimes happens that an algorithm does not work in very rare corner
+   * cases. These cases will then be trapped sooner or later by the exception,
+   * so that the algorithm can then be fixed for these cases as well.
    */
   DeclException0 (ExcInternalError);
 
   /**
-   * This exception is used in functions that may not be called (i.e. in
-   * pure functions) but could not be declared pure since the class is
-   * intended to be used anyway, even though the respective function may
-   * only be called if a derived class is used.
+   * This exception is used in functions that may not be called (i.e. in pure
+   * functions) but could not be declared pure since the class is intended to
+   * be used anyway, even though the respective function may only be called if
+   * a derived class is used.
    */
   DeclException0 (ExcPureFunctionCalled);
 
   /**
-   * Used for constructors that are disabled. Examples are copy
-   * constructors and assignment operators of large objects, which are
-   * only allowed for empty objects.
+   * Used for constructors that are disabled. Examples are copy constructors
+   * and assignment operators of large objects, which are only allowed for
+   * empty objects.
    */
   DeclException0 (ExcInvalidConstructorCall);
 
@@ -683,8 +677,8 @@ namespace StandardExceptions
   DeclException0 (ExcInvalidState);
 
   /**
-   * This exception is raised if a functionality is not possible in the
-   * given dimension. Mostly used to throw function calls in 1d.
+   * This exception is raised if a functionality is not possible in the given
+   * dimension. Mostly used to throw function calls in 1d.
    *
    * The constructor takes a single <tt>int</tt>, denoting the dimension.
    */
@@ -704,19 +698,19 @@ namespace StandardExceptions
   DeclException0(ExcEmptyObject);
 
   /**
-   * This exception is raised whenever the sizes of two objects were
-   * assumed to be equal, but were not.
+   * This exception is raised whenever the sizes of two objects were assumed
+   * to be equal, but were not.
    *
-   * Parameters to the constructor are the first and second size, both of
-   * type <tt>int</tt>.
+   * Parameters to the constructor are the first and second size, both of type
+   * <tt>int</tt>.
    */
   DeclException2 (ExcDimensionMismatch,
                   std::size_t, std::size_t,
                   << "Dimension " << arg1 << " not equal to " << arg2);
 
   /**
-   * The first dimension should be either equal to the second or the
-   * third, but it is neither.
+   * The first dimension should be either equal to the second or the third,
+   * but it is neither.
    */
   DeclException3 (ExcDimensionMismatch2,
                   int, int, int,
@@ -724,15 +718,15 @@ namespace StandardExceptions
                   << " nor to " << arg3);
 
   /**
-   * This exception is one of the most often used ones, and indicates
-   * that an index is not within the expected range. For example, you
-   * might try to access an element of a vector which does not exist.
+   * This exception is one of the most often used ones, and indicates that an
+   * index is not within the expected range. For example, you might try to
+   * access an element of a vector which does not exist.
    *
    * The constructor takes three <tt>int</tt>, namely
    * <ol>
-   *   <li> the violating index
-   *   <li> the lower bound
-   *   <li> the upper bound plus one
+   * <li> the violating index
+   * <li> the lower bound
+   * <li> the upper bound plus one
    * </ol>
    */
   DeclException3 (ExcIndexRange,
@@ -741,8 +735,8 @@ namespace StandardExceptions
                   << arg3 << "[");
 
   /**
-   * This generic exception will allow(enforce) the user to specify
-   * the type of indices which adds type safety to the program.
+   * This generic exception will allow(enforce) the user to specify the type
+   * of indices which adds type safety to the program.
    */
   template<typename T>
   DeclException3 (ExcIndexRangeType,
@@ -768,8 +762,8 @@ namespace StandardExceptions
                   << arg2);
 
   /**
-   * This exception indicates that the first argument should be an
-   * integer multiple of the second, but is not.
+   * This exception indicates that the first argument should be an integer
+   * multiple of the second, but is not.
    */
   DeclException2 (ExcNotMultiple,
                   int, int,
@@ -777,34 +771,33 @@ namespace StandardExceptions
                   << " has remainder different from zero");
 
   /**
-   * This exception is thrown if the iterator you access has corrupted
-   * data. It might for instance be, that the container it refers does
-   * not have an entry at the point the iterator refers.
+   * This exception is thrown if the iterator you access has corrupted data.
+   * It might for instance be, that the container it refers does not have an
+   * entry at the point the iterator refers.
    *
    * Typically, this will be an internal error of deal.II, because the
-   * increment and decrement operators should never yield an invalid
-   * iterator.
+   * increment and decrement operators should never yield an invalid iterator.
    */
   DeclException0 (ExcInvalidIterator);
 
   /**
-   * This exception is thrown if the iterator you incremented or
-   * decremented was already at its final state.
+   * This exception is thrown if the iterator you incremented or decremented
+   * was already at its final state.
    */
   DeclException0 (ExcIteratorPastEnd);
 
   /**
-   * This exception works around a design flaw in the
-   * <tt>DeclException0</tt> macro: exceptions declared through
-   * DeclException0 do not allow one to specify a message that is displayed
-   * when the exception is raised, as opposed to the other exceptions which
-   * allow to show a text along with the given parameters.
+   * This exception works around a design flaw in the <tt>DeclException0</tt>
+   * macro: exceptions declared through DeclException0 do not allow one to
+   * specify a message that is displayed when the exception is raised, as
+   * opposed to the other exceptions which allow to show a text along with the
+   * given parameters.
    *
    * When throwing this exception, you can give a message as a
-   * <tt>std::string</tt> as argument to the exception that is then
-   * displayed. The argument can, of course, be constructed at run-time,
-   * for example including the name of a file that can't be opened, or
-   * any other text you may want to assemble from different pieces.
+   * <tt>std::string</tt> as argument to the exception that is then displayed.
+   * The argument can, of course, be constructed at run-time, for example
+   * including the name of a file that can't be opened, or any other text you
+   * may want to assemble from different pieces.
    */
   DeclException1 (ExcMessage,
                   std::string,
@@ -816,11 +809,11 @@ namespace StandardExceptions
   DeclException0 (ExcGhostsPresent);
 
   /**
-   * Some of our numerical classes allow for setting alll entries to
-   * zero using the assignment operator <tt>=</tt>.
+   * Some of our numerical classes allow for setting alll entries to zero
+   * using the assignment operator <tt>=</tt>.
    *
-   * In many cases, this assignment operator makes sense <b>only</b>
-   * for the argument zero. In other cases, this exception is thrown.
+   * In many cases, this assignment operator makes sense <b>only</b> for the
+   * argument zero. In other cases, this exception is thrown.
    */
   DeclException0 (ExcScalarAssignmentOnlyForZeroValue);
 
@@ -848,8 +841,8 @@ namespace StandardExceptions
  * Special assertion for dimension mismatch.
  *
  * Since this is used very often and always repeats the arguments, we
- * introduce this special assertion for ExcDimensionMismatch in order
- * to keep the user codes shorter.
+ * introduce this special assertion for ExcDimensionMismatch in order to keep
+ * the user codes shorter.
  *
  * @ingroup Exceptions
  * @author Guido Kanschat 2007
@@ -859,9 +852,8 @@ namespace StandardExceptions
 
 
 /**
- * Special assertion, testing whether <tt>vec</tt> has size
- * <tt>dim1</tt>, and each entry of the vector has the
- * size <tt>dim2</tt>
+ * Special assertion, testing whether <tt>vec</tt> has size <tt>dim1</tt>, and
+ * each entry of the vector has the size <tt>dim2</tt>
  *
  * @ingroup Exceptions
  * @author Guido Kanschat 2010
@@ -874,12 +866,12 @@ namespace StandardExceptions
  * Special assertion for index range of nonnegative indices.
  *
  * Since this is used very often and always repeats the arguments, we
- * introduce this special assertion for ExcIndexRange in order
- * to keep the user codes shorter.
+ * introduce this special assertion for ExcIndexRange in order to keep the
+ * user codes shorter.
  *
- * Called wit arguments <tt>index</tt> and <tt>range</tt> it asserts
- * that <tt>index&lt;range</tt> and throws
- * ExcIndexRange(index,0,range) if it fails.
+ * Called wit arguments <tt>index</tt> and <tt>range</tt> it asserts that
+ * <tt>index&lt;range</tt> and throws ExcIndexRange(index,0,range) if it
+ * fails.
  *
  * @ingroup Exceptions
  * @author Guido Kanschat 2007
index d4ee5e5f6b358947c2510f6b413960b87a4a90ac..3b54817848b4ec471d8a0a3aa9c8c5d85f88ede4 100644 (file)
@@ -30,16 +30,15 @@ namespace Functions
    * Base class for analytic solutions to incompressible flow problems.
    *
    * Additional to the Function interface, this function provides for an
-   * offset of the pressure: if the pressure of the computed solution
-   * has an integral mean value different from zero, this value can be
-   * given to pressure_adjustment() in order to compute correct pressure
-   * errors.
+   * offset of the pressure: if the pressure of the computed solution has an
+   * integral mean value different from zero, this value can be given to
+   * pressure_adjustment() in order to compute correct pressure errors.
    *
-   * @note Derived classes should implement pressures with integral mean
-   * value zero always.
+   * @note Derived classes should implement pressures with integral mean value
+   * zero always.
    *
-   * @note Thread safety: Some of the functions make use of internal data to compute
-   * values. Therefore, every thread should obtain its own object of
+   * @note Thread safety: Some of the functions make use of internal data to
+   * compute values. Therefore, every thread should obtain its own object of
    * derived classes.
    *
    * @ingroup functions
@@ -50,8 +49,7 @@ namespace Functions
   {
   public:
     /**
-     * Constructor, setting up some
-     * internal data structures.
+     * Constructor, setting up some internal data structures.
      */
     FlowFunction();
 
@@ -61,46 +59,32 @@ namespace Functions
     virtual ~FlowFunction();
 
     /**
-     * Store an adjustment for the
-     * pressure function, such that
-     * its mean value is
-     * <tt>p</tt>.
+     * Store an adjustment for the pressure function, such that its mean value
+     * is <tt>p</tt>.
      */
     void pressure_adjustment(double p);
 
     /**
-     * Values in a structure more
-     * suitable for vector valued
-     * functions. The outer vector
-     * is indexed by solution
-     * component, the inner by
-     * quadrature point.
+     * Values in a structure more suitable for vector valued functions. The
+     * outer vector is indexed by solution component, the inner by quadrature
+     * point.
      */
     virtual void vector_values (const std::vector<Point<dim> > &points,
                                 std::vector<std::vector<double> > &values) const = 0;
     /**
-     * Gradients in a structure more
-     * suitable for vector valued
-     * functions. The outer vector
-     * is indexed by solution
-     * component, the inner by
-     * quadrature point.
+     * Gradients in a structure more suitable for vector valued functions. The
+     * outer vector is indexed by solution component, the inner by quadrature
+     * point.
      */
     virtual void vector_gradients (const std::vector<Point<dim> >            &points,
                                    std::vector<std::vector<Tensor<1,dim> > > &gradients) const = 0;
     /**
-     * Force terms in a structure more
-     * suitable for vector valued
-     * functions. The outer vector
-     * is indexed by solution
-     * component, the inner by
+     * Force terms in a structure more suitable for vector valued functions.
+     * The outer vector is indexed by solution component, the inner by
      * quadrature point.
      *
-     * @warning This is not the
-     * true Laplacian, but the
-     * force term to be used as
-     * right hand side in Stokes'
-     * equations
+     * @warning This is not the true Laplacian, but the force term to be used
+     * as right hand side in Stokes' equations
      */
     virtual void vector_laplacians (const std::vector<Point<dim> > &points,
                                     std::vector<std::vector<double> >   &values) const = 0;
@@ -112,8 +96,7 @@ namespace Functions
     virtual void vector_gradient_list (const std::vector<Point<dim> >            &points,
                                        std::vector<std::vector<Tensor<1,dim> > > &gradients) const;
     /**
-     * The force term in the
-     * momentum equation.
+     * The force term in the momentum equation.
      */
     virtual void vector_laplacian_list (const std::vector<Point<dim> > &points,
                                         std::vector<Vector<double> >   &values) const;
@@ -122,38 +105,32 @@ namespace Functions
 
   protected:
     /**
-     * Mean value of the pressure
-     * to be added by derived
-     * classes.
+     * Mean value of the pressure to be added by derived classes.
      */
     double mean_pressure;
 
   private:
 
     /**
-     * A mutex that guards the
-     * following scratch arrays.
+     * A mutex that guards the following scratch arrays.
      */
     mutable Threads::Mutex mutex;
 
     /**
-     * Auxiliary values for the usual
-     * Function interface.
+     * Auxiliary values for the usual Function interface.
      */
     mutable std::vector<std::vector<double> > aux_values;
 
     /**
-     * Auxiliary values for the usual
-     * Function interface.
+     * Auxiliary values for the usual Function interface.
      */
     mutable std::vector<std::vector<Tensor<1,dim> > > aux_gradients;
   };
 
   /**
-   * Laminar pipe flow in two and three dimensions. The channel
-   * stretches along the <i>x</i>-axis and has radius @p radius. The
-   * @p Reynolds number is used to scale the pressure properly for a
-   * Navier-Stokes problem.
+   * Laminar pipe flow in two and three dimensions. The channel stretches
+   * along the <i>x</i>-axis and has radius @p radius. The @p Reynolds number
+   * is used to scale the pressure properly for a Navier-Stokes problem.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2007
@@ -163,10 +140,8 @@ namespace Functions
   {
   public:
     /**
-     * Construct an object for the
-     * given channel radius
-     * <tt>r</tt> and the Reynolds
-     * number <tt>Re</tt>.
+     * Construct an object for the given channel radius <tt>r</tt> and the
+     * Reynolds number <tt>Re</tt>.
      */
     PoisseuilleFlow<dim> (const double r,
                           const double Re);
@@ -186,8 +161,8 @@ namespace Functions
 
 
   /**
-   * Artificial divergence free function with homogeneous boundary
-   * conditions on the cube [-1,1]<sup>dim</sup>.
+   * Artificial divergence free function with homogeneous boundary conditions
+   * on the cube [-1,1]<sup>dim</sup>.
    *
    * The function in 2D is
    * @f[
@@ -204,15 +179,12 @@ namespace Functions
   {
   public:
     /**
-     * Constructor setting the
-     * Reynolds number required for
-     * pressure computation and
-     * scaling of the right hand side.
+     * Constructor setting the Reynolds number required for pressure
+     * computation and scaling of the right hand side.
      */
     StokesCosine (const double viscosity = 1., const double reaction = 0.);
     /**
-     * Change the viscosity and the
-     * reaction parameter.
+     * Change the viscosity and the reaction parameter.
      */
     void set_parameters (const double viscosity, const double reaction);
     virtual ~StokesCosine();
@@ -278,8 +250,7 @@ namespace Functions
   /**
    * Flow solution in 2D by Kovasznay (1947).
    *
-   * This function is valid on the half plane right of the line
-   * <i>x=1/2</i>.
+   * This function is valid on the half plane right of the line <i>x=1/2</i>.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2007
@@ -288,18 +259,11 @@ namespace Functions
   {
   public:
     /**
-     * Construct an object for the
-     * give Reynolds number
-     * <tt>Re</tt>. If the
-     * parameter <tt>Stokes</tt> is
-     * true, the right hand side of
-     * the momentum equation
-     * returned by
-     * vector_laplacians() contains
-     * the nonlinearity, such that
-     * the Kovasznay solution can
-     * be obtained as the solution
-     * to a Stokes problem.
+     * Construct an object for the give Reynolds number <tt>Re</tt>. If the
+     * parameter <tt>Stokes</tt> is true, the right hand side of the momentum
+     * equation returned by vector_laplacians() contains the nonlinearity,
+     * such that the Kovasznay solution can be obtained as the solution to a
+     * Stokes problem.
      */
     Kovasznay (const double Re, bool Stokes = false);
     virtual ~Kovasznay();
index 2a28f6d08deea37a218245de8eb27ea8ab3563ed..4d62a580f429f1c2ca48c5fe2b8bf96ca58006af 100644 (file)
@@ -38,17 +38,16 @@ template <int rank, int dim, typename Number> class TensorFunction;
  * to evaluate the function, returns a vector of values with one or more
  * components.
  *
- * The class serves the purpose
- * of representing both scalar and vector valued functions. To this end, we
- * consider scalar functions as a special case of vector valued
- * functions, in the former case only having a single component return
- * vector. Since handling vectors is comparatively expensive, the interface
- * of this class has functions which only ask for a single component of the
- * vector-valued results (this is what you will usually need in case you know that
- * your function is scalar-valued) as well as functions you can ask for an
- * entire vector of results with as many components as the function object
- * represents. Access to function objects therefore is through the following
- * methods:
+ * The class serves the purpose of representing both scalar and vector valued
+ * functions. To this end, we consider scalar functions as a special case of
+ * vector valued functions, in the former case only having a single component
+ * return vector. Since handling vectors is comparatively expensive, the
+ * interface of this class has functions which only ask for a single component
+ * of the vector-valued results (this is what you will usually need in case
+ * you know that your function is scalar-valued) as well as functions you can
+ * ask for an entire vector of results with as many components as the function
+ * object represents. Access to function objects therefore is through the
+ * following methods:
  * @code
  *                 // access to one component at one point
  *   double value        (const Point<dim, Number>   &p,
@@ -72,42 +71,38 @@ template <int rank, int dim, typename Number> class TensorFunction;
  *                             std::vector<Vector<double> >      &value_list) const;
  * @endcode
  *
- * Furthermore, there are functions returning the gradient of the
- * function or even higher derivatives at one or several points.
+ * Furthermore, there are functions returning the gradient of the function or
+ * even higher derivatives at one or several points.
  *
- * You will usually only overload those functions you need; the
- * functions returning several values at a time (value_list(),
- * vector_value_list(), and gradient analogs) will call those
- * returning only one value (value(), vector_value(), and gradient
- * analogs), while those ones will throw an exception when called but
- * not overloaded.
+ * You will usually only overload those functions you need; the functions
+ * returning several values at a time (value_list(), vector_value_list(), and
+ * gradient analogs) will call those returning only one value (value(),
+ * vector_value(), and gradient analogs), while those ones will throw an
+ * exception when called but not overloaded.
  *
  * Note however, that conversely the functions returning all components of the
  * function at one or several points (i.e. vector_value(),
- * vector_value_list()), will not call the function returning one
- * component at one point repeatedly, once for each point and
- * component. The reason is efficiency: this would amount to too many
- * virtual function calls. If you have vector-valued functions, you
- * should therefore also provide overloads of the virtual functions
- * for all components at a time.
+ * vector_value_list()), will not call the function returning one component at
+ * one point repeatedly, once for each point and component. The reason is
+ * efficiency: this would amount to too many virtual function calls. If you
+ * have vector-valued functions, you should therefore also provide overloads
+ * of the virtual functions for all components at a time.
  *
- * Also note, that unless only called a very small number of times,
- * you should overload all sets of functions (returning only one
- * value, as well as those returning a whole array), since the cost of
- * evaluation of a point value is often less than the virtual function
- * call itself.
+ * Also note, that unless only called a very small number of times, you should
+ * overload all sets of functions (returning only one value, as well as those
+ * returning a whole array), since the cost of evaluation of a point value is
+ * often less than the virtual function call itself.
  *
  *
- * Support for time dependent functions can be found in the base
- * class FunctionTime.
+ * Support for time dependent functions can be found in the base class
+ * FunctionTime.
  *
- * @note If the functions you are dealing with have sizes which
- * are a priori known (for example, <tt>dim</tt> elements), you might
- * consider using the TensorFunction class instead. On the other hand,
- * functions like VectorTools::interpolate or
- * VectorTools::interpolate_boundary_values definitely only want objects
- * of the current type. You can use the VectorFunctionFromTensorFunction
- * class to convert the former to the latter.
+ * @note If the functions you are dealing with have sizes which are a priori
+ * known (for example, <tt>dim</tt> elements), you might consider using the
+ * TensorFunction class instead. On the other hand, functions like
+ * VectorTools::interpolate or VectorTools::interpolate_boundary_values
+ * definitely only want objects of the current type. You can use the
+ * VectorFunctionFromTensorFunction class to convert the former to the latter.
  *
  * @ingroup functions
  * @author Wolfgang Bangerth, 1998, 1999, Luca Heltai 2014
@@ -118,8 +113,8 @@ class Function : public FunctionTime<Number>,
 {
 public:
   /**
-   * Export the value of the template parameter as a static member
-   * constant. Sometimes useful for some expression template programming.
+   * Export the value of the template parameter as a static member constant.
+   * Sometimes useful for some expression template programming.
    */
   static const unsigned int dimension = dim;
 
@@ -130,8 +125,8 @@ public:
 
   /**
    * Constructor. May take an initial value for the number of components
-   * (which defaults to one, i.e. a scalar function), and the time
-   * variable, which defaults to zero.
+   * (which defaults to one, i.e. a scalar function), and the time variable,
+   * which defaults to zero.
    */
   Function (const unsigned int n_components = 1,
             const Number       initial_time = 0.0);
@@ -140,39 +135,38 @@ public:
    * Virtual destructor; absolutely necessary in this case.
    *
    * This destructor is declared pure virtual, such that objects of this class
-   * cannot be created. Since all the other virtual functions have a
-   * pseudo-implementation to avoid overhead in derived classes, they can not
-   * be abstract. As a consequence, we could generate an object of this class
+   * cannot be created. Since all the other virtual functions have a pseudo-
+   * implementation to avoid overhead in derived classes, they can not be
+   * abstract. As a consequence, we could generate an object of this class
    * because none of this class's functions are abstract.
    *
    * We circumvent this problem by making the destructor of this class
    * abstract virtual. This ensures that at least one member function is
-   * abstract, and consequently, no objects of type Function can be
-   * created. However, there is no need for derived classes to explicitly
-   * implement a destructor: every class has a destructor, either explicitly
-   * implemented or implicitly generated by the compiler, and this resolves
-   * the abstractness of any derived class even if they do not have an
-   * explicitly declared destructor.
+   * abstract, and consequently, no objects of type Function can be created.
+   * However, there is no need for derived classes to explicitly implement a
+   * destructor: every class has a destructor, either explicitly implemented
+   * or implicitly generated by the compiler, and this resolves the
+   * abstractness of any derived class even if they do not have an explicitly
+   * declared destructor.
    *
-   * Nonetheless, since derived classes want to call the destructor of a
-   * base class, this destructor is implemented (despite it being pure
-   * virtual).
+   * Nonetheless, since derived classes want to call the destructor of a base
+   * class, this destructor is implemented (despite it being pure virtual).
    */
   virtual ~Function () = 0;
 
   /**
    * Assignment operator. This is here only so that you can have objects of
-   * derived classes in containers, or assign them otherwise. It will raise
-   * an exception if the object from which you assign has a different
-   * number of components than the one being assigned to.
+   * derived classes in containers, or assign them otherwise. It will raise an
+   * exception if the object from which you assign has a different number of
+   * components than the one being assigned to.
    */
   Function &operator= (const Function &f);
 
   /**
-   * Return the value of the function at the given point. Unless there is
-   * only one component (i.e. the function is scalar), you should state the
-   * component you want to have evaluated; it defaults to zero, i.e. the
-   * first component.
+   * Return the value of the function at the given point. Unless there is only
+   * one component (i.e. the function is scalar), you should state the
+   * component you want to have evaluated; it defaults to zero, i.e. the first
+   * component.
    */
   virtual Number value (const Point<dim, Number>   &p,
                         const unsigned int  component = 0) const;
@@ -180,8 +174,7 @@ public:
   /**
    * Return all components of a vector-valued function at a given point.
    *
-   * <tt>values</tt> shall have the right size beforehand, i.e.
-   * #n_components.
+   * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
    *
    * The default implementation will call value() for each component.
    */
@@ -189,10 +182,10 @@ public:
                              Vector<Number>     &values) const;
 
   /**
-   * Set <tt>values</tt> to the point values of the specified component of
-   * the function at the <tt>points</tt>.  It is assumed that
-   * <tt>values</tt> already has the right size, i.e.  the same size as the
-   * <tt>points</tt> array.
+   * Set <tt>values</tt> to the point values of the specified component of the
+   * function at the <tt>points</tt>.  It is assumed that <tt>values</tt>
+   * already has the right size, i.e.  the same size as the <tt>points</tt>
+   * array.
    *
    * By default, this function repeatedly calls value() for each point
    * separately, to fill the output array.
@@ -208,15 +201,15 @@ public:
    * all elements be vectors with the same number of components as this
    * function has.
    *
-   * By default, this function repeatedly calls vector_value() for each
-   * point separately, to fill the output array.
+   * By default, this function repeatedly calls vector_value() for each point
+   * separately, to fill the output array.
    */
   virtual void vector_value_list (const std::vector<Point<dim, Number> > &points,
                                   std::vector<Vector<Number> >   &values) const;
 
   /**
-   * For each component of the function, fill a vector of values, one for
-   * each point.
+   * For each component of the function, fill a vector of values, one for each
+   * point.
    *
    * The default implementation of this function in Function calls
    * value_list() for each component. In order to improve performance, this
@@ -233,25 +226,24 @@ public:
                                           const unsigned int  component = 0) const;
 
   /**
-   * Return the gradient of all components of the function at the given
-   * point.
+   * Return the gradient of all components of the function at the given point.
    */
   virtual void vector_gradient (const Point<dim, Number>            &p,
                                 std::vector<Tensor<1,dim, Number> > &gradients) const;
 
   /**
-   * Set <tt>gradients</tt> to the gradients of the specified component of
-   * the function at the <tt>points</tt>.  It is assumed that
-   * <tt>gradients</tt> already has the right size, i.e.  the same size as
-   * the <tt>points</tt> array.
+   * Set <tt>gradients</tt> to the gradients of the specified component of the
+   * function at the <tt>points</tt>.  It is assumed that <tt>gradients</tt>
+   * already has the right size, i.e.  the same size as the <tt>points</tt>
+   * array.
    */
   virtual void gradient_list (const std::vector<Point<dim, Number> > &points,
                               std::vector<Tensor<1,dim, Number> >    &gradients,
                               const unsigned int              component = 0) const;
 
   /**
-   * For each component of the function, fill a vector of gradient values,
-   * one for each point.
+   * For each component of the function, fill a vector of gradient values, one
+   * for each point.
    *
    * The default implementation of this function in Function calls
    * value_list() for each component. In order to improve performance, this
@@ -263,8 +255,8 @@ public:
   /**
    * Set <tt>gradients</tt> to the gradients of the function at the
    * <tt>points</tt>, for all components. It is assumed that
-   * <tt>gradients</tt> already has the right size, i.e. the same size as
-   * the <tt>points</tt> array.
+   * <tt>gradients</tt> already has the right size, i.e. the same size as the
+   * <tt>points</tt> array.
    *
    * The outer loop over <tt>gradients</tt> is over the points in the list,
    * the inner loop over the different components of the function.
@@ -300,10 +292,10 @@ public:
 
   /**
    * Determine an estimate for the memory consumption (in bytes) of this
-   * object. Since sometimes the size of objects can not be determined
-   * exactly (for example: what is the memory consumption of an STL
-   * <tt>std::map</tt> type with a certain number of elements?), this is
-   * only an estimate. however often quite close to the true value.
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   std::size_t memory_consumption () const;
 };
@@ -311,11 +303,10 @@ public:
 
 
 /**
- * Provide a function which always returns zero. Obviously, also the
- * derivates of this function are zero. Also, it returns zero on all
- * components in case the function is not a scalar one, which can be
- * obtained by passing the constructor the appropriate number of
- * components.
+ * Provide a function which always returns zero. Obviously, also the derivates
+ * of this function are zero. Also, it returns zero on all components in case
+ * the function is not a scalar one, which can be obtained by passing the
+ * constructor the appropriate number of components.
  *
  * This function is of use when you want to implement homogeneous boundary
  * conditions, or zero initial conditions.
@@ -368,24 +359,24 @@ public:
 
 
 /**
- * Provide a function which always returns the constant value
- * handed to the constructor.
+ * Provide a function which always returns the constant value handed to the
+ * constructor.
  *
- * Obviously, the derivates of this function are zero, which is why we
- * derive this class from <tt>ZeroFunction</tt>: we then only have to
- * overload the value functions, not all the derivatives. In some way, it
- * would be more obvious to do the derivation in the opposite direction,
- * i.e. let <tt>ZeroFunction</tt> be a more specialized version of
- * <tt>ConstantFunction</tt>; however, this would be less efficient, since
- * we could not make use of the fact that the function value of the
+ * Obviously, the derivates of this function are zero, which is why we derive
+ * this class from <tt>ZeroFunction</tt>: we then only have to overload the
+ * value functions, not all the derivatives. In some way, it would be more
+ * obvious to do the derivation in the opposite direction, i.e. let
+ * <tt>ZeroFunction</tt> be a more specialized version of
+ * <tt>ConstantFunction</tt>; however, this would be less efficient, since we
+ * could not make use of the fact that the function value of the
  * <tt>ZeroFunction</tt> is known at compile time and need not be looked up
  * somewhere in memory.
  *
  * You can pass to the constructor an integer denoting the number of
- * components this function shall have. It defaults to one. If it is
- * greater than one, then the function will return the constant value in
- * all its components, which might not be overly useful a feature in most
- * cases, however.
+ * components this function shall have. It defaults to one. If it is greater
+ * than one, then the function will return the constant value in all its
+ * components, which might not be overly useful a feature in most cases,
+ * however.
  *
  * @ingroup functions
  * @author Wolfgang Bangerth, 1998, 1999
@@ -395,8 +386,8 @@ class ConstantFunction : public ZeroFunction<dim, Number>
 {
 public:
   /**
-   * Constructor; takes the constant function value as an argument. The
-   * number of components is preset to one.
+   * Constructor; takes the constant function value as an argument. The number
+   * of components is preset to one.
    */
   ConstantFunction (const Number       value,
                     const unsigned int n_components = 1);
@@ -431,15 +422,14 @@ protected:
 
 
 /**
- * This is a constant vector-valued function, in which one or more
- * components of the vector have a constant value and all other components
- * are zero.  It is especially useful as a weight function for
- * VectorTools::integrate_difference, where it allows to integrate only one
- * or a few vector components, rather than the entire vector-valued
- * solution. In other words, it acts as a component mask with a single
- * component selected (see the @ref GlossComponentMask "the glossary entry
- * on component masks"). See the step-20 tutorial program for a detailed
- * explanation and a use case.
+ * This is a constant vector-valued function, in which one or more components
+ * of the vector have a constant value and all other components are zero.  It
+ * is especially useful as a weight function for
+ * VectorTools::integrate_difference, where it allows to integrate only one or
+ * a few vector components, rather than the entire vector-valued solution. In
+ * other words, it acts as a component mask with a single component selected
+ * (see the @ref GlossComponentMask "the glossary entry on component masks").
+ * See the step-20 tutorial program for a detailed explanation and a use case.
  *
  * @ingroup functions
  * @author Guido Kanschat, 2000, Wolfgang Bangerth 2006
@@ -450,8 +440,8 @@ class ComponentSelectFunction : public ConstantFunction<dim, Number>
 public:
   /**
    * Constructor if only a single component shall be non-zero. Arguments
-   * denote the component selected, the value for that component and the
-   * total number of vector components.
+   * denote the component selected, the value for that component and the total
+   * number of vector components.
    */
   ComponentSelectFunction (const unsigned int selected,
                            const Number       value,
@@ -465,37 +455,36 @@ public:
                            const unsigned int n_components);
 
   /**
-   * Constructor if multiple components shall have non-zero, unit values
-   * (i.e. this should be a mask for multiple components). The first
-   * argument denotes a half-open interval of components (for example
-   * std::pair(0,dim) for the first dim components), and the second
-   * argument is the total number of vector components.
+   * Constructor if multiple components shall have non-zero, unit values (i.e.
+   * this should be a mask for multiple components). The first argument
+   * denotes a half-open interval of components (for example std::pair(0,dim)
+   * for the first dim components), and the second argument is the total
+   * number of vector components.
    */
   ComponentSelectFunction (const std::pair<unsigned int, unsigned int> &selected,
                            const unsigned int n_components);
 
   /**
-   * Return the value of the function at the given point for all
-   * components.
+   * Return the value of the function at the given point for all components.
    */
   virtual void   vector_value (const Point<dim, Number> &p,
                                Vector<Number>   &return_value) const;
 
   /**
    * Set <tt>values</tt> to the point values of the function at the
-   * <tt>points</tt>, for all components. It is assumed that
-   * <tt>values</tt> already has the right size, i.e. the same size as the
-   * <tt>points</tt> array.
+   * <tt>points</tt>, for all components. It is assumed that <tt>values</tt>
+   * already has the right size, i.e. the same size as the <tt>points</tt>
+   * array.
    */
   virtual void vector_value_list (const std::vector<Point<dim, Number> > &points,
                                   std::vector<Vector<Number> >   &values) const;
 
   /**
    * Determine an estimate for the memory consumption (in bytes) of this
-   * object. Since sometimes the size of objects can not be determined
-   * exactly (for example: what is the memory consumption of an STL
-   * <tt>std::map</tt> type with a certain number of elements?), this is
-   * only an estimate. however often quite close to the true value.
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   std::size_t memory_consumption () const;
 
@@ -515,27 +504,27 @@ protected:
  * @endcode
  * into an object of type Function@<dim@>. Since the argument returns a
  * scalar, the result is clearly a Function object for which
- * <code>function.n_components==1</code>. The class works by storing a
- * pointer to the given function and every time
+ * <code>function.n_components==1</code>. The class works by storing a pointer
+ * to the given function and every time
  * <code>function.value(p,component)</code> is called, calls
- * <code>foo(p)</code> and returns the corresponding value. It also makes
- * sure that <code>component</code> is in fact zero, as needs be for scalar
+ * <code>foo(p)</code> and returns the corresponding value. It also makes sure
+ * that <code>component</code> is in fact zero, as needs be for scalar
  * functions.
  *
  * The class provides an easy way to turn a simple global function into
  * something that has the required Function@<dim@> interface for operations
  * like VectorTools::interpolate_boundary_values() etc., and thereby allows
- * for simpler experimenting without having to write all the boiler plate
- * code of declaring a class that is derived from Function and implementing
- * the Function::value() function. An example of this is given in the results
+ * for simpler experimenting without having to write all the boiler plate code
+ * of declaring a class that is derived from Function and implementing the
+ * Function::value() function. An example of this is given in the results
  * section of step-53.
  *
- * The class gains additional expressive power because the argument it
- * takes does not have to be a pointer to an actual function. Rather, it is
- * a function object, i.e., it can also be the result of call to std::bind
- * (or boost::bind) or some other object that can be called with a single
- * argument. For example, if you need a Function object that returns the
- * norm of a point, you could write it like so:
+ * The class gains additional expressive power because the argument it takes
+ * does not have to be a pointer to an actual function. Rather, it is a
+ * function object, i.e., it can also be the result of call to std::bind (or
+ * boost::bind) or some other object that can be called with a single
+ * argument. For example, if you need a Function object that returns the norm
+ * of a point, you could write it like so:
  * @code
  *   template <int dim, typename Number>
  *   class Norm : public Function<dim, Number> {
@@ -549,8 +538,8 @@ protected:
  *
  *    Norm<2> my_norm_object;
  * @endcode
- * and then pass the <code>my_norm_object</code> around, or you could write
- * it like so:
+ * and then pass the <code>my_norm_object</code> around, or you could write it
+ * like so:
  * @code
  *   ScalarFunctionFromFunctionObject<dim, Number> my_norm_object (&Point<dim, Number>::norm);
  * @endcode
@@ -591,7 +580,8 @@ class ScalarFunctionFromFunctionObject : public Function<dim, Number>
 public:
   /**
    * Given a function object that takes a Point and returns a Number value,
-   * convert this into an object that matches the Function<dim, Number> interface.
+   * convert this into an object that matches the Function<dim, Number>
+   * interface.
    */
   ScalarFunctionFromFunctionObject (const std_cxx11::function<Number (const Point<dim, Number> &)> &function_object);
 
@@ -606,30 +596,29 @@ private:
   /**
    * The function object which we call when this class's value() or
    * value_list() functions are called.
-   **/
+   */
   const std_cxx11::function<Number (const Point<dim, Number> &)> function_object;
 };
 
 
 
 /**
- * This class is similar to the ScalarFunctionFromFunctionObject class in
- * that it allows for the easy conversion of a function object to something
- * that satisfies the interface of the Function base class. The difference
- * is that here, the given function object is still a scalar function (i.e.
- * it has a single value at each space point) but that the Function object
- * generated is vector valued. The number of vector components is specified
- * in the constructor, where one also selectes a single one of these vector
+ * This class is similar to the ScalarFunctionFromFunctionObject class in that
+ * it allows for the easy conversion of a function object to something that
+ * satisfies the interface of the Function base class. The difference is that
+ * here, the given function object is still a scalar function (i.e. it has a
+ * single value at each space point) but that the Function object generated is
+ * vector valued. The number of vector components is specified in the
+ * constructor, where one also selectes a single one of these vector
  * components that should be filled by the passed object. The result is a
  * vector Function object that returns zero in each component except the
- * single selected one where it returns the value returned by the given as
- * the first argument to the constructor.
+ * single selected one where it returns the value returned by the given as the
+ * first argument to the constructor.
  *
  * @note In the above discussion, note the difference between the (scalar)
- * "function object" (i.e., a C++ object <code>x</code> that can be called
- * as in <code>x(p)</code>) and the capitalized (vector valued) "Function
- * object" (i.e., an object of a class that is derived from the Function
- * base class).
+ * "function object" (i.e., a C++ object <code>x</code> that can be called as
+ * in <code>x(p)</code>) and the capitalized (vector valued) "Function object"
+ * (i.e., an object of a class that is derived from the Function base class).
  *
  * To be more concrete, let us consider the following example:
  * @code
@@ -638,11 +627,11 @@ private:
  *      component_mask (&one, 1, 3);
  * @endcode
  * Here, <code>component_mask</code> then represents a Function object that
- * for every point returns the vector $(0, 1, 0)^T$, i.e. a mask function
- * that could, for example, be passed to
- * VectorTools::integrate_difference(). This effect can also be achieved
- * using the ComponentSelectFunction class but is obviously easily extended
- * to functions that are non-constant in their one component.
+ * for every point returns the vector $(0, 1, 0)^T$, i.e. a mask function that
+ * could, for example, be passed to VectorTools::integrate_difference(). This
+ * effect can also be achieved using the ComponentSelectFunction class but is
+ * obviously easily extended to functions that are non-constant in their one
+ * component.
  *
  * @author Wolfgang Bangerth, 2011
  */
@@ -651,17 +640,16 @@ class VectorFunctionFromScalarFunctionObject : public Function<dim, Number>
 {
 public:
   /**
-   * Given a function object that takes a Point and returns a Number
-   * value, convert this into an object that matches the Function@<dim@>
-   * interface.
+   * Given a function object that takes a Point and returns a Number value,
+   * convert this into an object that matches the Function@<dim@> interface.
    *
    * @param function_object The scalar function that will form one component
-   *     of the resulting Function object.
+   * of the resulting Function object.
    * @param n_components The total number of vector components of the
-   *     resulting Function object.
-   * @param selected_component The single component that should be
-   *     filled by the first argument.
-   **/
+   * resulting Function object.
+   * @param selected_component The single component that should be filled by
+   * the first argument.
+   */
   VectorFunctionFromScalarFunctionObject (const std_cxx11::function<Number (const Point<dim, Number> &)> &function_object,
                                           const unsigned int selected_component,
                                           const unsigned int n_components);
@@ -676,8 +664,7 @@ public:
   /**
    * Return all components of a vector-valued function at a given point.
    *
-   * <tt>values</tt> shall have the right size beforehand, i.e.
-   * #n_components.
+   * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
    */
   virtual void vector_value (const Point<dim, Number>   &p,
                              Vector<Number>     &values) const;
@@ -686,7 +673,7 @@ private:
   /**
    * The function object which we call when this class's value() or
    * value_list() functions are called.
-   **/
+   */
   const std_cxx11::function<Number (const Point<dim, Number> &)> function_object;
 
   /**
@@ -698,36 +685,36 @@ private:
 
 
 /**
- * This class is built as a means of translating the <code>Tensor<1,dim, Number>
- * </code> values produced by objects of type TensorFunction and returning
- * them as a multiple component version of the same thing as a Vector for
- * use in, for example, the VectorTools::interpolate or the many other
- * functions taking Function objects. It allows the user to place the
+ * This class is built as a means of translating the <code>Tensor<1,dim,
+ * Number> </code> values produced by objects of type TensorFunction and
+ * returning them as a multiple component version of the same thing as a
+ * Vector for use in, for example, the VectorTools::interpolate or the many
+ * other functions taking Function objects. It allows the user to place the
  * desired components into an <tt>n_components</tt> long vector starting at
- * the <tt>selected_component</tt> location in that vector and have all
- * other components be 0.
+ * the <tt>selected_component</tt> location in that vector and have all other
+ * components be 0.
  *
- *  For example: Say you created a class called
+ * For example: Say you created a class called
  *  @code
  *    class RightHandSide : public TensorFunction<rank,dim, Number>
  *  @endcode
- *  which extends the TensorFunction class and you have an object
+ * which extends the TensorFunction class and you have an object
  *  @code
  *    RightHandSide<1,dim, Number> rhs;
  *  @endcode
- *  of that class which you want to interpolate onto your mesh using the
- *  VectorTools::interpolate function, but the finite element you use for
- *  the DoFHandler object has 3 copies of a finite element with
- *  <tt>dim</tt> components, for a total of 3*dim components. To
- *  interpolate onto that DoFHandler, you need an object of type Function
- *  that has 3*dim vector components. Creating such an object from the
- *  existing <code>rhs</code> object is done using this piece of code:
+ * of that class which you want to interpolate onto your mesh using the
+ * VectorTools::interpolate function, but the finite element you use for the
+ * DoFHandler object has 3 copies of a finite element with <tt>dim</tt>
+ * components, for a total of 3*dim components. To interpolate onto that
+ * DoFHandler, you need an object of type Function that has 3*dim vector
+ * components. Creating such an object from the existing <code>rhs</code>
+ * object is done using this piece of code:
  *  @code
  *      RighHandSide<1,dim, Number> rhs;
  *      VectorFunctionFromTensorFunction<dim, Number> rhs_vector_function (rhs, 0, 3*dim);
  *  @endcode
- *  where the <code>dim</code> components of the tensor function are placed into
- *  the first <code>dim</code> components of the function object.
+ * where the <code>dim</code> components of the tensor function are placed
+ * into the first <code>dim</code> components of the function object.
  *
  * @author Spencer Patty, 2013
  */
@@ -736,21 +723,20 @@ class VectorFunctionFromTensorFunction : public Function<dim, Number>
 {
 public:
   /**
-   * Given a TensorFunction object that takes a <tt>Point</tt> and returns
-   * <tt>Tensor<1,dim, Number></tt> value, convert this into an object that
+   * Given a TensorFunction object that takes a <tt>Point</tt> and returns a
+   * <tt>Tensor<1,dim, Number></tt> value, convert this into an object that
    * matches the Function@<dim@> interface.
    *
    * By default, create a Vector object of the same size as
    * <tt>tensor_function</tt> returns, i.e., with <tt>dim</tt> components.
    *
-   * @param tensor_function The TensorFunction that will form one component
-   *     of the resulting Vector Function object.
+   * @param tensor_function The TensorFunction that will form one component of
+   * the resulting Vector Function object.
    * @param n_components The total number of vector components of the
-   *     resulting TensorFunction object.
-   * @param selected_component The first component that should be
-   *     filled by the first argument.  This should be such that the entire
-   *     tensor_function fits inside the <tt>n_component</tt> length return
-   *     vector.
+   * resulting TensorFunction object.
+   * @param selected_component The first component that should be filled by
+   * the first argument.  This should be such that the entire tensor_function
+   * fits inside the <tt>n_component</tt> length return vector.
    */
   VectorFunctionFromTensorFunction (const TensorFunction<1,dim, Number> &tensor_function,
                                     const unsigned int selected_component=0,
@@ -763,8 +749,7 @@ public:
   virtual ~VectorFunctionFromTensorFunction();
 
   /**
-   * Return a single component of a vector-valued function at a given
-   * point.
+   * Return a single component of a vector-valued function at a given point.
    */
   virtual Number value (const Point<dim, Number> &p,
                         const unsigned int component = 0) const;
@@ -772,8 +757,7 @@ public:
   /**
    * Return all components of a vector-valued function at a given point.
    *
-   * <tt>values</tt> shall have the right size beforehand, i.e.
-   * #n_components.
+   * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
    */
   virtual void vector_value (const Point<dim, Number> &p,
                              Vector<Number>   &values) const;
@@ -790,9 +774,9 @@ public:
 
 private:
   /**
-   * The TensorFunction object which we call when this class's
-   * vector_value() or vector_value_list() functions are called.
-   **/
+   * The TensorFunction object which we call when this class's vector_value()
+   * or vector_value_list() functions are called.
+   */
   const TensorFunction<1,dim,Number> &tensor_function;
 
   /**
index 3951b10ec9fe58ab83a4c017fae53ed0f7108c72..2e2efda46795262f9a433b629ffa02dd80653f07 100644 (file)
@@ -25,17 +25,17 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Derivative of a function object.  The value access functions of
- * this class return the directional derivative of a function with
- * respect to a direction provided on construction. If <tt>b</tt> is the
- * vector, the derivative <tt>b . grad f</tt> is computed. This derivative
- * is evaluated directly, not by computing the gradient of <tt>f</tt> and
- * its scalar product with <tt>b</tt>.
+ * Derivative of a function object.  The value access functions of this class
+ * return the directional derivative of a function with respect to a direction
+ * provided on construction. If <tt>b</tt> is the vector, the derivative <tt>b
+ * . grad f</tt> is computed. This derivative is evaluated directly, not by
+ * computing the gradient of <tt>f</tt> and its scalar product with
+ * <tt>b</tt>.
  *
  * The derivative is computed numerically, using one of the provided
- * difference formulas (see <tt>set_formula</tt> for available
- * schemes). Experimenting with <tt>h</tt> and the difference scheme may be
- * necessary to obtain sufficient results.
+ * difference formulas (see <tt>set_formula</tt> for available schemes).
+ * Experimenting with <tt>h</tt> and the difference scheme may be necessary to
+ * obtain sufficient results.
  *
  * @ingroup functions
  * @author Guido Kanschat, 2000
@@ -45,59 +45,42 @@ class FunctionDerivative : public AutoDerivativeFunction<dim>
 {
 public:
   /**
-   * Constructor. Provided are the
-   * functions to compute
-   * derivatives of, the direction
-   * vector of the differentiation
-   * and the step size <tt>h</tt> of the
-   * difference formula.
+   * Constructor. Provided are the functions to compute derivatives of, the
+   * direction vector of the differentiation and the step size <tt>h</tt> of
+   * the difference formula.
    */
   FunctionDerivative (const Function<dim> &f,
                       const Point<dim>    &direction,
                       const double         h = 1.e-6);
 
   /**
-   * Constructor. Provided are the
-   * functions to compute
-   * derivatives of and the
-   * direction vector of the
-   * differentiation in each
-   * quadrature point and the
+   * Constructor. Provided are the functions to compute derivatives of and the
+   * direction vector of the differentiation in each quadrature point and the
    * difference step size.
    *
-   * This is the constructor for a
-   * variable velocity field. Most
-   * probably, a new object of
-   * <tt>FunctionDerivative</tt> has to
-   * be constructed for each set of
-   * quadrature points.
+   * This is the constructor for a variable velocity field. Most probably, a
+   * new object of <tt>FunctionDerivative</tt> has to be constructed for each
+   * set of quadrature points.
    *
-   * The number of quadrature point
-   * must still be the same, when
-   * values are accessed.
+   * The number of quadrature point must still be the same, when values are
+   * accessed.
    */
   FunctionDerivative (const Function<dim>            &f,
                       const std::vector<Point<dim> > &direction,
                       const double                    h = 1.e-6);
 
   /**
-   * Choose the difference formula.
-   * This is set to the default in
-   * the constructor.
+   * Choose the difference formula. This is set to the default in the
+   * constructor.
    *
-   * Formulas implemented right now
-   * are first order backward Euler
-   * (<tt>UpwindEuler</tt>), second
-   * order symmetric Euler
-   * (<tt>Euler</tt>) and a symmetric
-   * fourth order formula
-   * (<tt>FourthOrder</tt>).
+   * Formulas implemented right now are first order backward Euler
+   * (<tt>UpwindEuler</tt>), second order symmetric Euler (<tt>Euler</tt>) and
+   * a symmetric fourth order formula (<tt>FourthOrder</tt>).
    */
   void set_formula (typename AutoDerivativeFunction<dim>::DifferenceFormula formula
                     = AutoDerivativeFunction<dim>::Euler);
   /**
-   * Change the base step size of
-   * the difference formula
+   * Change the base step size of the difference formula
    */
   void set_h (const double h);
 
@@ -112,25 +95,18 @@ public:
                            const unsigned int              component = 0) const;
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
-   * object. Since sometimes
-   * the size of objects can
-   * not be determined exactly
-   * (for example: what is the
-   * memory consumption of an
-   * STL <tt>std::map</tt> type with a
-   * certain number of
-   * elements?), this is only
-   * an estimate. however often
-   * quite close to the true
-   * value.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception.
@@ -144,8 +120,7 @@ private:
   const Function<dim> &f;
 
   /**
-   * Step size of the difference
-   * formula.
+   * Step size of the difference formula.
    */
   double h;
 
@@ -155,9 +130,7 @@ private:
   typename AutoDerivativeFunction<dim>::DifferenceFormula formula;
 
   /**
-   * Helper object. Contains the
-   * increment vector for the
-   * formula.
+   * Helper object. Contains the increment vector for the formula.
    */
   std::vector<Point<dim> > incr;
 };
index b6fea1c1bee10abaa2ae89a2ea7148d863ac39aa..37e45e0decc0b51012beaf794b8268b3de00d99a 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Namespace implementing some concrete classes derived from the
- * Function class that describe actual functions. This is rather
- * a collection of classes that we have needed for our own programs
- * once and thought might be useful to others as well at some
- * point.
+ * Namespace implementing some concrete classes derived from the Function
+ * class that describe actual functions. This is rather a collection of
+ * classes that we have needed for our own programs once and thought might be
+ * useful to others as well at some point.
  *
  * @ingroup functions
  */
@@ -77,9 +76,8 @@ namespace Functions
 
 
   /**
-   * The function <tt>xy</tt> in 2d and 3d, not implemented in 1d.
-   * This function serves as an example for
-   * a vanishing Laplacian.
+   * The function <tt>xy</tt> in 2d and 3d, not implemented in 1d. This
+   * function serves as an example for a vanishing Laplacian.
    *
    * @ingroup functions
    * @author: Guido Kanschat, 2000
@@ -131,8 +129,8 @@ namespace Functions
    * boundary values on the domain $(-1,1)^d$. In the inside, it is the
    * product of $1-x_i^2$ over all space dimensions.
    *
-   * Providing a non-zero argument to the constructor, the whole function
-   * can be offset by a constant.
+   * Providing a non-zero argument to the constructor, the whole function can
+   * be offset by a constant.
    *
    * Together with the function, its derivatives and Laplacian are defined.
    *
@@ -144,9 +142,8 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Provide a
-     * constant that will be added to
-     * each function value.
+     * Constructor. Provide a constant that will be added to each function
+     * value.
      */
     PillowFunction (const double offset=0.);
 
@@ -195,9 +192,9 @@ namespace Functions
 
 
   /**
-   * Cosine-shaped pillow function.
-   * This is another function with zero boundary values on $[-1,1]^d$. In the interior
-   * it is the product of $\cos(\pi/2 x_i)$.
+   * Cosine-shaped pillow function. This is another function with zero
+   * boundary values on $[-1,1]^d$. In the interior it is the product of
+   * $\cos(\pi/2 x_i)$.
    *
    * @ingroup functions
    * @author Guido Kanschat, 1999
@@ -207,11 +204,8 @@ namespace Functions
   {
   public:
     /**
-     * Constructor which allows to
-     * optionally generate a vector
-     * valued cosine function with
-     * the same value in each
-     * component.
+     * Constructor which allows to optionally generate a vector valued cosine
+     * function with the same value in each component.
      */
     CosineFunction (const unsigned int n_components = 1);
 
@@ -240,15 +234,13 @@ namespace Functions
                                  const unsigned int              component = 0) const;
 
     /**
-     * Second derivatives at a
-     * single point.
+     * Second derivatives at a single point.
      */
     virtual Tensor<2,dim> hessian (const Point<dim>   &p,
                                    const unsigned int  component = 0) const;
 
     /**
-     * Second derivatives at
-     * multiple points.
+     * Second derivatives at multiple points.
      */
     virtual void hessian_list (const std::vector<Point<dim> > &points,
                                std::vector<Tensor<2,dim> >    &hessians,
@@ -260,11 +252,10 @@ namespace Functions
   /**
    * Gradient of the cosine-shaped pillow function.
    *
-   * This is a vector-valued function with @p dim components, the
-   * gradient of CosineFunction. On the square [-1,1], it has tangential
-   * boundary conditions zero. Thus, it can be used to test
-   * implementations of Maxwell operators without bothering about
-   * boundary terms.
+   * This is a vector-valued function with @p dim components, the gradient of
+   * CosineFunction. On the square [-1,1], it has tangential boundary
+   * conditions zero. Thus, it can be used to test implementations of Maxwell
+   * operators without bothering about boundary terms.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2010
@@ -274,8 +265,7 @@ namespace Functions
   {
   public:
     /**
-     * Constructor, creating a
-     * function with @p dim components.
+     * Constructor, creating a function with @p dim components.
      */
     CosineGradFunction ();
 
@@ -401,8 +391,8 @@ namespace Functions
   /**
    * Gradient of the harmonic singularity on the L-shaped domain in 2D.
    *
-   * The gradient of LSingularityFunction, which is a vector valued
-   * function with vanishing curl and divergence.
+   * The gradient of LSingularityFunction, which is a vector valued function
+   * with vanishing curl and divergence.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2010
@@ -411,8 +401,7 @@ namespace Functions
   {
   public:
     /**
-     * Default constructor setting
-     * the dimension to 2.
+     * Default constructor setting the dimension to 2.
      */
     LSingularityGradFunction ();
     virtual double value (const Point<2>   &p,
@@ -527,11 +516,11 @@ namespace Functions
    * A jump in x-direction transported into some direction.
    *
    * If the advection is parallel to the y-axis, the function is
-   * <tt>-atan(sx)</tt>, where <tt>s</tt> is the steepness parameter provided in
-   * the constructor.
+   * <tt>-atan(sx)</tt>, where <tt>s</tt> is the steepness parameter provided
+   * in the constructor.
    *
-   * For different advection directions, this function will be turned in
-   * the parameter space.
+   * For different advection directions, this function will be turned in the
+   * parameter space.
    *
    * Together with the function, its derivatives and Laplacian are defined.
    *
@@ -543,9 +532,8 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Provide the
-     * advection direction here and
-     * the steepness of the slope.
+     * Constructor. Provide the advection direction here and the steepness of
+     * the slope.
      */
     JumpFunction (const Point<dim> &direction,
                   const double      steepness);
@@ -557,8 +545,7 @@ namespace Functions
                           const unsigned int  component = 0) const;
 
     /**
-     * Function values at multiple
-     * points.
+     * Function values at multiple points.
      */
     virtual void value_list (const std::vector<Point<dim> > &points,
                              std::vector<double>            &values,
@@ -571,8 +558,8 @@ namespace Functions
                                     const unsigned int  component = 0) const;
 
     /**
-       Gradients at multiple points.
-    */
+     * Gradients at multiple points.
+     */
     virtual void gradient_list (const std::vector<Point<dim> > &points,
                                 std::vector<Tensor<1,dim> >    &gradients,
                                 const unsigned int              component = 0) const;
@@ -591,20 +578,11 @@ namespace Functions
                                  const unsigned int              component = 0) const;
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this
-     * object. Since sometimes
-     * the size of objects can
-     * not be determined exactly
-     * (for example: what is the
-     * memory consumption of an
-     * STL <tt>std::map</tt> type with a
-     * certain number of
-     * elements?), this is only
-     * an estimate. however often
-     * quite close to the true
-     * value.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. Since sometimes the size of objects can not be determined
+     * exactly (for example: what is the memory consumption of an STL
+     * <tt>std::map</tt> type with a certain number of elements?), this is
+     * only an estimate. however often quite close to the true value.
      */
     std::size_t memory_consumption () const;
 
@@ -615,8 +593,7 @@ namespace Functions
     const Point<dim> direction;
 
     /**
-     * Steepness (maximal derivative)
-     * of the slope.
+     * Steepness (maximal derivative) of the slope.
      */
     const double steepness;
 
@@ -639,13 +616,13 @@ namespace Functions
 
 
   /**
-   * Given a wavenumber vector generate a cosine function. The
-   * wavenumber coefficient is given as a $d$-dimensional point $k$
-   * in Fourier space, and the function is then recovered as $f(x) =
-   * \cos(\sum_i k_i x_i) = Re(\exp(i k.x))$.
+   * Given a wavenumber vector generate a cosine function. The wavenumber
+   * coefficient is given as a $d$-dimensional point $k$ in Fourier space, and
+   * the function is then recovered as $f(x) = \cos(\sum_i k_i x_i) =
+   * Re(\exp(i k.x))$.
    *
-   * The class has its name from the fact that it resembles one
-   * component of a Fourier cosine decomposition.
+   * The class has its name from the fact that it resembles one component of a
+   * Fourier cosine decomposition.
    *
    * @ingroup functions
    * @author Wolfgang Bangerth, 2001
@@ -655,37 +632,29 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Take the Fourier
-     * coefficients in each space
-     * direction as argument.
+     * Constructor. Take the Fourier coefficients in each space direction as
+     * argument.
      */
     FourierCosineFunction (const Point<dim> &fourier_coefficients);
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component you
-     * want to have evaluated; it
-     * defaults to zero, i.e. the
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
      * first component.
      */
     virtual double value (const Point<dim>   &p,
                           const unsigned int  component = 0) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at the given point.
+     * Return the gradient of the specified component of the function at the
+     * given point.
      */
     virtual Tensor<1,dim> gradient (const Point<dim>   &p,
                                     const unsigned int  component = 0) const;
 
     /**
-     * Compute the Laplacian of a
-     * given component at point <tt>p</tt>.
+     * Compute the Laplacian of a given component at point <tt>p</tt>.
      */
     virtual double laplacian (const Point<dim>   &p,
                               const unsigned int  component = 0) const;
@@ -699,13 +668,13 @@ namespace Functions
 
 
   /**
-   * Given a wavenumber vector generate a sine function. The
-   * wavenumber coefficient is given as a $d$-dimensional point $k$
-   * in Fourier space, and the function is then recovered as $f(x) =
-   * \sin(\sum_i k_i x_i) = Im(\exp(i k.x))$.
+   * Given a wavenumber vector generate a sine function. The wavenumber
+   * coefficient is given as a $d$-dimensional point $k$ in Fourier space, and
+   * the function is then recovered as $f(x) = \sin(\sum_i k_i x_i) =
+   * Im(\exp(i k.x))$.
    *
-   * The class has its name from the fact that it resembles one
-   * component of a Fourier sine decomposition.
+   * The class has its name from the fact that it resembles one component of a
+   * Fourier sine decomposition.
    *
    * @ingroup functions
    * @author Wolfgang Bangerth, 2001
@@ -715,37 +684,29 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Take the Fourier
-     * coefficients in each space
-     * direction as argument.
+     * Constructor. Take the Fourier coefficients in each space direction as
+     * argument.
      */
     FourierSineFunction (const Point<dim> &fourier_coefficients);
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component you
-     * want to have evaluated; it
-     * defaults to zero, i.e. the
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
      * first component.
      */
     virtual double value (const Point<dim>   &p,
                           const unsigned int  component = 0) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at the given point.
+     * Return the gradient of the specified component of the function at the
+     * given point.
      */
     virtual Tensor<1,dim> gradient (const Point<dim>   &p,
                                     const unsigned int  component = 0) const;
 
     /**
-     * Compute the Laplacian of a
-     * given component at point <tt>p</tt>.
+     * Compute the Laplacian of a given component at point <tt>p</tt>.
      */
     virtual double laplacian (const Point<dim>   &p,
                               const unsigned int  component = 0) const;
@@ -758,10 +719,9 @@ namespace Functions
 
 
   /**
-   * Given a sequence of wavenumber vectors and weights generate a sum
-   * of sine functions. Each wavenumber coefficient is given as a
-   * $d$-dimensional point $k$ in Fourier space, and the entire
-   * function is then recovered as
+   * Given a sequence of wavenumber vectors and weights generate a sum of sine
+   * functions. Each wavenumber coefficient is given as a $d$-dimensional
+   * point $k$ in Fourier space, and the entire function is then recovered as
    * $f(x) = \sum_j w_j sin(\sum_i k_i x_i) = Im(\sum_j w_j \exp(i k.x))$.
    *
    * @ingroup functions
@@ -772,45 +732,36 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Take the Fourier
-     * coefficients in each space
-     * direction as argument.
+     * Constructor. Take the Fourier coefficients in each space direction as
+     * argument.
      */
     FourierSineSum (const std::vector<Point<dim> > &fourier_coefficients,
                     const std::vector<double>      &weights);
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component you
-     * want to have evaluated; it
-     * defaults to zero, i.e. the
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
      * first component.
      */
     virtual double value (const Point<dim>   &p,
                           const unsigned int  component = 0) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at the given point.
+     * Return the gradient of the specified component of the function at the
+     * given point.
      */
     virtual Tensor<1,dim> gradient (const Point<dim>   &p,
                                     const unsigned int  component = 0) const;
 
     /**
-     * Compute the Laplacian of a
-     * given component at point <tt>p</tt>.
+     * Compute the Laplacian of a given component at point <tt>p</tt>.
      */
     virtual double laplacian (const Point<dim>   &p,
                               const unsigned int  component = 0) const;
   private:
     /**
-     * Stored Fourier coefficients
-     * and weights.
+     * Stored Fourier coefficients and weights.
      */
     const std::vector<Point<dim> > fourier_coefficients;
     const std::vector<double>      weights;
@@ -819,11 +770,11 @@ namespace Functions
 
 
   /**
-   * Given a sequence of wavenumber vectors and weights generate a sum
-   * of cosine functions. Each wavenumber coefficient is given as a
-   * $d$-dimensional point $k$ in Fourier space, and the entire
-   * function is then recovered as
-   * $f(x) = \sum_j w_j cos(\sum_i k_i x_i) = Re(\sum_j w_j \exp(i k.x))$.
+   * Given a sequence of wavenumber vectors and weights generate a sum of
+   * cosine functions. Each wavenumber coefficient is given as a
+   * $d$-dimensional point $k$ in Fourier space, and the entire function is
+   * then recovered as $f(x) = \sum_j w_j cos(\sum_i k_i x_i) = Re(\sum_j w_j
+   * \exp(i k.x))$.
    *
    * @ingroup functions
    * @author Wolfgang Bangerth, 2001
@@ -833,46 +784,37 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Take the Fourier
-     * coefficients in each space
-     * direction as argument.
+     * Constructor. Take the Fourier coefficients in each space direction as
+     * argument.
      */
     FourierCosineSum (const std::vector<Point<dim> > &fourier_coefficients,
                       const std::vector<double>      &weights);
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component you
-     * want to have evaluated; it
-     * defaults to zero, i.e. the
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
      * first component.
      */
     virtual double value (const Point<dim>   &p,
                           const unsigned int  component = 0) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at the given point.
+     * Return the gradient of the specified component of the function at the
+     * given point.
      */
     virtual Tensor<1,dim> gradient (const Point<dim>   &p,
                                     const unsigned int  component = 0) const;
 
     /**
-     * Compute the Laplacian of a
-     * given component at point <tt>p</tt>.
+     * Compute the Laplacian of a given component at point <tt>p</tt>.
      */
     virtual double laplacian (const Point<dim>   &p,
                               const unsigned int  component = 0) const;
 
   private:
     /**
-     * Stored Fourier coefficients
-     * and weights.
+     * Stored Fourier coefficients and weights.
      */
     const std::vector<Point<dim> > fourier_coefficients;
     const std::vector<double>      weights;
@@ -880,10 +822,9 @@ namespace Functions
 
 
   /**
-   * Base function for cut-off function. This class stores the center
-   * and the radius of the supporting ball of a cut-off function. It
-   * also stores the number of the non-zero component, if the function
-   * is vector-valued.
+   * Base function for cut-off function. This class stores the center and the
+   * radius of the supporting ball of a cut-off function. It also stores the
+   * number of the non-zero component, if the function is vector-valued.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2002
@@ -893,24 +834,16 @@ namespace Functions
   {
   public:
     /**
-     * Value used in the
-     * constructor of this and
-     * derived classes to denote
-     * that no component is
-     * selected.
+     * Value used in the constructor of this and derived classes to denote
+     * that no component is selected.
      */
     static const unsigned int no_component = numbers::invalid_unsigned_int;
 
     /**
-     * Constructor. Arguments are the
-     * center of the ball and its
-     * radius.
+     * Constructor. Arguments are the center of the ball and its radius.
      *
-     * If an argument <tt>select</tt> is
-     * given and not -1, the
-     * cut-off function will be
-     * non-zero for this component
-     * only.
+     * If an argument <tt>select</tt> is given and not -1, the cut-off
+     * function will be non-zero for this component only.
      */
     CutOffFunctionBase (const double radius = 1.,
                         const Point<dim> = Point<dim>(),
@@ -918,8 +851,7 @@ namespace Functions
                         const unsigned int select = CutOffFunctionBase<dim>::no_component);
 
     /**
-     * Move the center of the ball
-     * to new point <tt>p</tt>.
+     * Move the center of the ball to new point <tt>p</tt>.
      */
     void new_center (const Point<dim> &p);
 
@@ -940,9 +872,8 @@ namespace Functions
     double radius;
 
     /**
-     * Component selected. If
-     * <tt>no_component</tt>, the function is
-     * the same in all components.
+     * Component selected. If <tt>no_component</tt>, the function is the same
+     * in all components.
      */
     const unsigned int selected;
   };
@@ -950,14 +881,10 @@ namespace Functions
 
 
   /**
-   * Cut-off function in L-infinity for an arbitrary ball.  This
-   * function is the characteristic function of a ball around <tt>center</tt>
-   * with a specified <tt>radius</tt>, that is,
-   * \f[
-   * f = \chi(B_r(c)).
-   * \f]
-   * If vector valued, it can be restricted
-   * to a single component.
+   * Cut-off function in L-infinity for an arbitrary ball.  This function is
+   * the characteristic function of a ball around <tt>center</tt> with a
+   * specified <tt>radius</tt>, that is, \f[ f = \chi(B_r(c)). \f] If vector
+   * valued, it can be restricted to a single component.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2001, 2002
@@ -967,15 +894,10 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Arguments are the
-     * center of the ball and its
-     * radius.
+     * Constructor. Arguments are the center of the ball and its radius.
      *
-     * If an argument <tt>select</tt> is
-     * given and not -1, the
-     * cut-off function will be
-     * non-zero for this component
-     * only.
+     * If an argument <tt>select</tt> is given and not -1, the cut-off
+     * function will be non-zero for this component only.
      */
     CutOffFunctionLinfty (const double radius = 1.,
                           const Point<dim> = Point<dim>(),
@@ -1004,10 +926,10 @@ namespace Functions
 
 
   /**
-   * Cut-off function for an arbitrary ball. This function is a cone
-   * with support in a ball of certain <tt>radius</tt> around <tt>center</tt>. The
-   * maximum value is 1. If vector valued, it can be restricted
-   * to a single component.
+   * Cut-off function for an arbitrary ball. This function is a cone with
+   * support in a ball of certain <tt>radius</tt> around <tt>center</tt>. The
+   * maximum value is 1. If vector valued, it can be restricted to a single
+   * component.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2001, 2002
@@ -1017,15 +939,11 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Arguments are the
-     * center of the ball and its
-     * radius.
+     * Constructor. Arguments are the center of the ball and its radius.
      * radius.
      *
-     * If an argument <tt>select</tt> is
-     * given, the cut-off function
-     * will be non-zero for this
-     * component only.
+     * If an argument <tt>select</tt> is given, the cut-off function will be
+     * non-zero for this component only.
      */
     CutOffFunctionW1 (const double radius = 1.,
                       const Point<dim> = Point<dim>(),
@@ -1054,11 +972,11 @@ namespace Functions
 
 
   /**
-   * Cut-off function for an arbitrary ball. This is the traditional
-   * cut-off function in C-infinity for a ball of certain <tt>radius</tt>
-   * around <tt>center</tt>, $f(r)=exp(1-1/(1-r**2/s**2))$, where $r$ is the
-   * distance to the center, and $s$ is the radius of the sphere. If
-   * vector valued, it can be restricted to a single component.
+   * Cut-off function for an arbitrary ball. This is the traditional cut-off
+   * function in C-infinity for a ball of certain <tt>radius</tt> around
+   * <tt>center</tt>, $f(r)=exp(1-1/(1-r**2/s**2))$, where $r$ is the distance
+   * to the center, and $s$ is the radius of the sphere. If vector valued, it
+   * can be restricted to a single component.
    *
    * @ingroup functions
    * @author Guido Kanschat, 2001, 2002
@@ -1068,15 +986,11 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. Arguments are the
-     * center of the ball and its
-     * radius.
+     * Constructor. Arguments are the center of the ball and its radius.
      * radius.
      *
-     * If an argument <tt>select</tt> is
-     * given, the cut-off function
-     * will be non-zero for this
-     * component only.
+     * If an argument <tt>select</tt> is given, the cut-off function will be
+     * non-zero for this component only.
      */
     CutOffFunctionCinfty (const double radius = 1.,
                           const Point<dim> = Point<dim>(),
@@ -1117,9 +1031,9 @@ namespace Functions
    * $x^\alpha$, in 2-d the form $x_1^{\alpha_1}x_2^{\alpha_2}$, and in 3-d
    * $x_1^{\alpha_1}x_2^{\alpha_2}x_3^{\alpha_3}$. Monomials are therefore
    * described by a $dim$-tuple of exponents. Consequently, the class's
-   * constructor takes a Tensor<1,dim> to describe the set of exponents. Most of
-   * the time these exponents will of course be integers, but real exponents are
-   * of course equally valid.
+   * constructor takes a Tensor<1,dim> to describe the set of exponents. Most
+   * of the time these exponents will of course be integers, but real
+   * exponents are of course equally valid.
    *
    * @author Wolfgang Bangerth, 2006
    */
@@ -1128,13 +1042,10 @@ namespace Functions
   {
   public:
     /**
-     * Constructor. The first argument is
-     * explained in the general description
-     * of the class. The second argument
-     * denotes the number of vector
-     * components this object shall
-     * represent. All vector components
-     * will have the same value.
+     * Constructor. The first argument is explained in the general description
+     * of the class. The second argument denotes the number of vector
+     * components this object shall represent. All vector components will have
+     * the same value.
      */
     Monomial (const Tensor<1,dim> &exponents,
               const unsigned int n_components = 1);
@@ -1146,13 +1057,10 @@ namespace Functions
                           const unsigned int  component = 0) const;
 
     /**
-     * Return all components of a
-     * vector-valued function at a
-     * given point.
+     * Return all components of a vector-valued function at a given point.
      *
-     * <tt>values</tt> shall have the right
-     * size beforehand,
-     * i.e. #n_components.
+     * <tt>values</tt> shall have the right size beforehand, i.e.
+     * #n_components.
      */
     virtual void vector_value (const Point<dim>   &p,
                                Vector<double>     &values) const;
@@ -1180,35 +1088,34 @@ namespace Functions
 
 
   /**
-   * A scalar function that computes its values by (bi-, tri-)linear interpolation
-   * from a set of point data that are arranged on a possibly non-uniform
-   * tensor product mesh. In other words, considering the three-dimensional case,
-   * let there be points $x_0,\ldotx, x_{K-1}$,
+   * A scalar function that computes its values by (bi-, tri-)linear
+   * interpolation from a set of point data that are arranged on a possibly
+   * non-uniform tensor product mesh. In other words, considering the three-
+   * dimensional case, let there be points $x_0,\ldotx, x_{K-1}$,
    * $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$, and data $d_{klm}$ defined at
-   * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point
-   * $\mathbf x=(x,y,z)$ will find the box so that
-   * $x_k\le x\le x_{k+1}, y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a
-   * trilinear interpolation of the data on this cell. Similar operations are
-   * done in lower dimensions.
+   * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point $\mathbf
+   * x=(x,y,z)$ will find the box so that $x_k\le x\le x_{k+1}, y_l\le x\le
+   * y_{l+1}, z_m\le z\le z_{m+1}$, and do a trilinear interpolation of the
+   * data on this cell. Similar operations are done in lower dimensions.
    *
    * This class is most often used for either evaluating coefficients or right
-   * hand sides that are provided experimentally at a number of points inside the
-   * domain, or for comparing outputs of a solution on a finite element mesh
-   * against previously obtained data defined on a grid.
+   * hand sides that are provided experimentally at a number of points inside
+   * the domain, or for comparing outputs of a solution on a finite element
+   * mesh against previously obtained data defined on a grid.
    *
-   * @note If the points $x_i$ are actually equally spaced on an interval $[x_0,x_1]$
-   * and the same is true for the other data points in higher dimensions, you should
-   * use the InterpolatedUniformGridData class instead.
+   * @note If the points $x_i$ are actually equally spaced on an interval
+   * $[x_0,x_1]$ and the same is true for the other data points in higher
+   * dimensions, you should use the InterpolatedUniformGridData class instead.
    *
    * If a point is requested outside the box defined by the end points of the
    * coordinate arrays, then the function is assumed to simply extend by
-   * constant values beyond the last data point in each coordinate
-   * direction. (The class does not throw an error if a point lies outside the
-   * box since it frequently happens that a point lies just outside the box
-   * by an amount on the order of numerical roundoff.)
+   * constant values beyond the last data point in each coordinate direction.
+   * (The class does not throw an error if a point lies outside the box since
+   * it frequently happens that a point lies just outside the box by an amount
+   * on the order of numerical roundoff.)
    *
-   * @note The use of the related class InterpolatedUniformGridData
-   * is discussed in step-53.
+   * @note The use of the related class InterpolatedUniformGridData is
+   * discussed in step-53.
    *
    * @author Wolfgang Bangerth, 2013
    */
@@ -1219,17 +1126,15 @@ namespace Functions
     /**
      * Constructor.
      * @param coordinate_values An array of dim arrays. Each of the inner
-     *   arrays contains the coordinate values $x_0,\ldotx, x_{K-1}$ and
-     *   similarly for the other coordinate directions. These arrays
-     *   need not have the same size. Obviously, we need dim such arrays
-     *   for a dim-dimensional function object. The coordinate values
-     *   within this array are assumed to be strictly ascending to allow
-     *   for efficient lookup.
-     * @param data_values A dim-dimensional table of data at each of the
-     *   mesh points defined by the coordinate arrays above. Note that the
-     *   Table class has a number of conversion constructors that allow
-     *   converting other data types into a table where you specify this
-     *   argument.
+     * arrays contains the coordinate values $x_0,\ldotx, x_{K-1}$ and
+     * similarly for the other coordinate directions. These arrays need not
+     * have the same size. Obviously, we need dim such arrays for a dim-
+     * dimensional function object. The coordinate values within this array
+     * are assumed to be strictly ascending to allow for efficient lookup.
+     * @param data_values A dim-dimensional table of data at each of the mesh
+     * points defined by the coordinate arrays above. Note that the Table
+     * class has a number of conversion constructors that allow converting
+     * other data types into a table where you specify this argument.
      */
     InterpolatedTensorProductGridData (const std_cxx11::array<std::vector<double>,dim> &coordinate_values,
                                        const Table<dim,double>                         &data_values);
@@ -1240,9 +1145,9 @@ namespace Functions
      *
      * @param p The point at which the function is to be evaluated.
      * @param component The vector component. Since this function is scalar,
-     *   only zero is a valid argument here.
-     * @return The interpolated value at this point. If the point lies outside
-     *   the set of coordinates, the function is extended by a constant.
+     * only zero is a valid argument here. @return The interpolated value at
+     * this point. If the point lies outside the set of coordinates, the
+     * function is extended by a constant.
      */
     virtual
     double
@@ -1263,23 +1168,23 @@ namespace Functions
 
 
   /**
-   * A scalar function that computes its values by (bi-, tri-)linear interpolation
-   * from a set of point data that are arranged on a uniformly spaced
-   * tensor product mesh. In other words, considering the three-dimensional case,
-   * let there be points $x_0,\ldotx, x_{K-1}$ that result from a uniform subdivision
-   * of the interval $[x_0,x_{K-1}]$ into $K-1$ sub-intervals of size $\Delta x
-   * = (x_{K-1}-x_0)/(K-1)$, and similarly
-   * $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$. Also consider data $d_{klm}$ defined at
-   * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point
-   * $\mathbf x=(x,y,z)$ will find the box so that
-   * $x_k\le x\le x_{k+1}, y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a
-   * trilinear interpolation of the data on this cell. Similar operations are
-   * done in lower dimensions.
+   * A scalar function that computes its values by (bi-, tri-)linear
+   * interpolation from a set of point data that are arranged on a uniformly
+   * spaced tensor product mesh. In other words, considering the three-
+   * dimensional case, let there be points $x_0,\ldotx, x_{K-1}$ that result
+   * from a uniform subdivision of the interval $[x_0,x_{K-1}]$ into $K-1$
+   * sub-intervals of size $\Delta x = (x_{K-1}-x_0)/(K-1)$, and similarly
+   * $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$. Also consider data $d_{klm}$
+   * defined at point $(x_k,y_l,z_m)^T$, then evaluating the function at a
+   * point $\mathbf x=(x,y,z)$ will find the box so that $x_k\le x\le x_{k+1},
+   * y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a trilinear
+   * interpolation of the data on this cell. Similar operations are done in
+   * lower dimensions.
    *
    * This class is most often used for either evaluating coefficients or right
-   * hand sides that are provided experimentally at a number of points inside the
-   * domain, or for comparing outputs of a solution on a finite element mesh
-   * against previously obtained data defined on a grid.
+   * hand sides that are provided experimentally at a number of points inside
+   * the domain, or for comparing outputs of a solution on a finite element
+   * mesh against previously obtained data defined on a grid.
    *
    * @note If you have a problem where the points $x_i$ are not equally spaced
    * (e.g., they result from a computation on a graded mesh that is denser
@@ -1288,10 +1193,10 @@ namespace Functions
    *
    * If a point is requested outside the box defined by the end points of the
    * coordinate arrays, then the function is assumed to simply extend by
-   * constant values beyond the last data point in each coordinate
-   * direction. (The class does not throw an error if a point lies outside the
-   * box since it frequently happens that a point lies just outside the box
-   * by an amount on the order of numerical roundoff.)
+   * constant values beyond the last data point in each coordinate direction.
+   * (The class does not throw an error if a point lies outside the box since
+   * it frequently happens that a point lies just outside the box by an amount
+   * on the order of numerical roundoff.)
    *
    * @note The use of this class is discussed in step-53.
    *
@@ -1303,18 +1208,17 @@ namespace Functions
   public:
     /**
      * Constructor
-     * @param interval_endpoints The left and right end points of the (uniformly
-     *   subdivided) intervals in each of the coordinate directions.
-     * @param n_subdivisions The number of subintervals of the subintervals
-     *   in each coordinate direction. A value of one for a coordinate
-     *   means that the interval is considered as one subinterval consisting
-     *   of the entire range. A value of two means that there are two subintervals
-     *   each with one half of the range, etc.
-     * @param data_values A dim-dimensional table of data at each of the
-     *   mesh points defined by the coordinate arrays above. Note that the
-     *   Table class has a number of conversion constructors that allow
-     *   converting other data types into a table where you specify this
-     *   argument.
+     * @param interval_endpoints The left and right end points of the
+     * (uniformly subdivided) intervals in each of the coordinate directions.
+     * @param n_subdivisions The number of subintervals of the subintervals in
+     * each coordinate direction. A value of one for a coordinate means that
+     * the interval is considered as one subinterval consisting of the entire
+     * range. A value of two means that there are two subintervals each with
+     * one half of the range, etc.
+     * @param data_values A dim-dimensional table of data at each of the mesh
+     * points defined by the coordinate arrays above. Note that the Table
+     * class has a number of conversion constructors that allow converting
+     * other data types into a table where you specify this argument.
      */
     InterpolatedUniformGridData (const std_cxx11::array<std::pair<double,double>,dim> &interval_endpoints,
                                  const std_cxx11::array<unsigned int,dim>             &n_subintervals,
@@ -1326,9 +1230,9 @@ namespace Functions
      *
      * @param p The point at which the function is to be evaluated.
      * @param component The vector component. Since this function is scalar,
-     *   only zero is a valid argument here.
-     * @return The interpolated value at this point. If the point lies outside
-     *   the set of coordinates, the function is extended by a constant.
+     * only zero is a valid argument here. @return The interpolated value at
+     * this point. If the point lies outside the set of coordinates, the
+     * function is extended by a constant.
      */
     virtual
     double
index 2a7417a1ed09efdd8192cc2e5b3cfd34af146dfb..eede26438e3c28000f2056e163bb8662d834a814 100644 (file)
@@ -181,11 +181,11 @@ class FunctionParser : public Function<dim>
 {
 public:
   /**
-   * Constructor for Parsed functions. Its arguments are the same of the
-   * base class Function. The only difference is that this object needs to
-   * be initialized with initialize() method before you can use it. If an
-   * attempt to use this function is made before the initialize() method has
-   * been called, then an exception is thrown.
+   * Constructor for Parsed functions. Its arguments are the same of the base
+   * class Function. The only difference is that this object needs to be
+   * initialized with initialize() method before you can use it. If an attempt
+   * to use this function is made before the initialize() method has been
+   * called, then an exception is thrown.
    */
   FunctionParser (const unsigned int n_components = 1,
                   const double       initial_time = 0.0);
@@ -207,8 +207,7 @@ public:
   typedef ConstMap::iterator ConstMapIterator;
 
   /**
-   * Initialize the function.  This methods accepts the following
-   * parameters:
+   * Initialize the function.  This methods accepts the following parameters:
    *
    * <b>vars</b>: a string with the variables that will be used by the
    * expressions to be evaluated. Note that the variables can have any name
@@ -217,31 +216,30 @@ public:
    * component of the point in which the function is evaluated, the second
    * variable to the second component and so forth. If this function is also
    * time dependent, then it is necessary to specify it by setting the
-   * <tt>time_dependent</tt> parameter to true.  An exception is thrown if
-   * the number of variables specified here is different from dim (if this
-   * function is not time-dependent) or from dim+1 (if it is time-
-   * dependent).
+   * <tt>time_dependent</tt> parameter to true.  An exception is thrown if the
+   * number of variables specified here is different from dim (if this
+   * function is not time-dependent) or from dim+1 (if it is time- dependent).
    *
    * <b>expressions</b>: a list of strings containing the expressions that
-   * will be byte compiled by the internal parser (FunctionParser). Note
-   * that the size of this vector must match exactly the number of
-   * components of the FunctionParser, as declared in the constructor. If
-   * this is not the case, an exception is thrown.
+   * will be byte compiled by the internal parser (FunctionParser). Note that
+   * the size of this vector must match exactly the number of components of
+   * the FunctionParser, as declared in the constructor. If this is not the
+   * case, an exception is thrown.
    *
    *
-   * <b>constants</b>: a map of constants used to pass any necessary
-   * constant that we want to specify in our expressions (in the example
-   * above the number pi). An expression is valid if and only if it contains
-   * only defined variables and defined constants (other than the functions
+   * <b>constants</b>: a map of constants used to pass any necessary constant
+   * that we want to specify in our expressions (in the example above the
+   * number pi). An expression is valid if and only if it contains only
+   * defined variables and defined constants (other than the functions
    * specified above). If a constant is given whose name is not valid (eg:
    * <tt>constants["sin"] = 1.5;</tt>) an exception is thrown.
    *
    * <b>time_dependent</b>. If this is a time dependent function, then the
-   * last variable declared in <b>vars</b> is assumed to be the time
-   * variable, and this->get_time() is used to initialize it when evaluating
-   * the function. Naturally the number of variables parsed by the
-   * initialize() method in this case is dim+1. The value of this parameter
-   * defaults to false, i.e. do not consider time.
+   * last variable declared in <b>vars</b> is assumed to be the time variable,
+   * and this->get_time() is used to initialize it when evaluating the
+   * function. Naturally the number of variables parsed by the initialize()
+   * method in this case is dim+1. The value of this parameter defaults to
+   * false, i.e. do not consider time.
    */
   void initialize (const std::string              &vars,
                    const std::vector<std::string> &expressions,
@@ -279,12 +277,11 @@ public:
                    const bool use_degrees = false) DEAL_II_DEPRECATED;
 
   /**
-   * Initialize the function. Same as above, but accepts a string rather
-   * than a vector of strings. If this is a vector valued function, its
-   * components are expected to be separated by a semicolon. An exception is
-   * thrown if this method is called and the number of components
-   * successfully parsed does not match the number of components of the base
-   * function.
+   * Initialize the function. Same as above, but accepts a string rather than
+   * a vector of strings. If this is a vector valued function, its components
+   * are expected to be separated by a semicolon. An exception is thrown if
+   * this method is called and the number of components successfully parsed
+   * does not match the number of components of the base function.
    */
   void initialize (const std::string &vars,
                    const std::string &expression,
@@ -318,18 +315,18 @@ public:
 
   /**
    * A function that returns default names for variables, to be used in the
-   * first argument of the initialize() functions: it returns "x" in 1d,
-   * "x,y" in 2d, and "x,y,z" in 3d.
+   * first argument of the initialize() functions: it returns "x" in 1d, "x,y"
+   * in 2d, and "x,y,z" in 3d.
    */
   static
   std::string
   default_variable_names ();
 
   /**
-   * Return the value of the function at the given point. Unless there is
-   * only one component (i.e. the function is scalar), you should state the
-   * component you want to have evaluated; it defaults to zero, i.e. the
-   * first component.
+   * Return the value of the function at the given point. Unless there is only
+   * one component (i.e. the function is scalar), you should state the
+   * component you want to have evaluated; it defaults to zero, i.e. the first
+   * component.
    */
   virtual double value (const Point<dim>   &p,
                         const unsigned int  component = 0) const;
@@ -338,8 +335,7 @@ public:
    * Return all components of a vector-valued function at the given point @p
    * p.
    *
-   * <tt>values</tt> shall have the right size beforehand, i.e.
-   * #n_components.
+   * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
    */
   virtual void vector_value (const Point<dim>   &p,
                              Vector<double>     &values) const;
@@ -374,14 +370,14 @@ private:
   mutable Threads::ThreadLocalStorage<std::vector<mu::Parser> > fp;
 
   /**
-   * An array to keep track of all the constants, required to
-   * initialize fp in each thread.
+   * An array to keep track of all the constants, required to initialize fp in
+   * each thread.
    */
   std::map<std::string, double> constants;
 
   /**
-   * An array for the variable names, required to initialize fp in
-   * each thread.
+   * An array for the variable names, required to initialize fp in each
+   * thread.
    */
   std::vector<std::string> var_names;
 
@@ -392,11 +388,10 @@ private:
   std::vector<std::string> expressions;
 
   /**
-   * Initialize fp and vars on the current thread. This function may
-   * only be called once per thread. A thread can test whether the
-   * function has already been called by testing whether
-   * 'fp.get().size()==0' (not initialized) or >0 (already
-   * initialized).
+   * Initialize fp and vars on the current thread. This function may only be
+   * called once per thread. A thread can test whether the function has
+   * already been called by testing whether 'fp.get().size()==0' (not
+   * initialized) or >0 (already initialized).
    */
   void init_muparser() const;
 #endif
@@ -408,11 +403,11 @@ private:
   bool initialized;
 
   /**
-   * Number of variables. If this is also a function of time, then the
-   * number of variables is dim+1, otherwise it is dim. In the case that
-   * this is a time dependent function, the time is supposed to be the last
-   * variable. If #n_vars is not identical to the number of the variables
-   * parsed by the initialize() method, then an exception is thrown.
+   * Number of variables. If this is also a function of time, then the number
+   * of variables is dim+1, otherwise it is dim. In the case that this is a
+   * time dependent function, the time is supposed to be the last variable. If
+   * #n_vars is not identical to the number of the variables parsed by the
+   * initialize() method, then an exception is thrown.
    */
   unsigned int n_vars;
 };
index bb4f9998690034eebfa6bbf98f858188ef3b48ee..46399c3229a37e3eb3e335451024e800202a6380 100644 (file)
 
 DEAL_II_NAMESPACE_OPEN
 /**
- *  Support for time dependent functions.
- *  The library was also designed for time dependent problems. For this
- *  purpose, the function objects also contain a field which stores the
- *  time, as well as functions manipulating them. Time independent problems
- *  should not access or even abuse them for other purposes, but since one
- *  normally does not create thousands of function objects, the gain in
- *  generality weighs out the fact that we need not store the time value
- *  for not time dependent problems. The second advantage is that the derived
- *  standard classes like <tt>ZeroFunction</tt>, <tt>ConstantFunction</tt> etc also work
- *  for time dependent problems.
+ * Support for time dependent functions. The library was also designed for
+ * time dependent problems. For this purpose, the function objects also
+ * contain a field which stores the time, as well as functions manipulating
+ * them. Time independent problems should not access or even abuse them for
+ * other purposes, but since one normally does not create thousands of
+ * function objects, the gain in generality weighs out the fact that we need
+ * not store the time value for not time dependent problems. The second
+ * advantage is that the derived standard classes like <tt>ZeroFunction</tt>,
+ * <tt>ConstantFunction</tt> etc also work for time dependent problems.
  *
- *  Access to the time goes through the following functions:
+ * Access to the time goes through the following functions:
  *  @verbatim
  *  <li> <tt>get_time</tt>: return the present value of the time variable.
  *  <li> <tt>set_time</tt>: set the time value to a specific value.
  *  <li> <tt>advance_time</tt>: increase the time by a certain time step.
  *  @endverbatim
- *  The latter two functions are virtual, so that derived classes can
- *  perform computations which need only be done once for every new time.
- *  For example, if a time dependent function had a factor <tt>sin(t)</tt>, then
- *  it may be a reasonable choice to calculate this factor in a derived
- *  version of <tt>set_time</tt>, store it in a member variable and use that one
- *  rather than computing it every time <tt>operator()</tt>, <tt>value_list</tt> or one
- *  of the other functions is called.
+ * The latter two functions are virtual, so that derived classes can perform
+ * computations which need only be done once for every new time. For example,
+ * if a time dependent function had a factor <tt>sin(t)</tt>, then it may be a
+ * reasonable choice to calculate this factor in a derived version of
+ * <tt>set_time</tt>, store it in a member variable and use that one rather
+ * than computing it every time <tt>operator()</tt>, <tt>value_list</tt> or
+ * one of the other functions is called.
  *
- *  By default, the <tt>advance_time</tt> function calls the <tt>set_time</tt> function
- *  with the new time, so it is sufficient in most cases to overload only
- *  <tt>set_time</tt> for computations as sketched out above.
+ * By default, the <tt>advance_time</tt> function calls the <tt>set_time</tt>
+ * function with the new time, so it is sufficient in most cases to overload
+ * only <tt>set_time</tt> for computations as sketched out above.
  *
- *  The constructor of this class takes an initial value for the time
- *  variable, which defaults to zero. Because a default value is given,
- *  none of the derived classes needs to take an initial value for the
- *  time variable if not needed.
+ * The constructor of this class takes an initial value for the time variable,
+ * which defaults to zero. Because a default value is given, none of the
+ * derived classes needs to take an initial value for the time variable if not
+ * needed.
  *
- *  Once again the warning: do not use the <tt>time</tt> variable for any other
- *  purpose than the intended one! This will inevitably lead to confusion.
+ * Once again the warning: do not use the <tt>time</tt> variable for any other
+ * purpose than the intended one! This will inevitably lead to confusion.
  *
  *
- *  @ingroup functions
- *  @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999
+ * @ingroup functions
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999
  */
 template <typename Number=double>
 class FunctionTime
 {
 public:
   /**
-   * Constructor. May take an initial vakue
-   * for the time variable, which defaults
-   * to zero.
+   * Constructor. May take an initial vakue for the time variable, which
+   * defaults to zero.
    */
   FunctionTime (const Number initial_time = Number(0.0));
 
@@ -85,14 +83,12 @@ public:
   Number get_time () const;
 
   /**
-   * Set the time to <tt>new_time</tt>, overwriting
-   * the old value.
+   * Set the time to <tt>new_time</tt>, overwriting the old value.
    */
   virtual void set_time (const Number new_time);
 
   /**
-   * Advance the time by the given
-   * time step <tt>delta_t</tt>.
+   * Advance the time by the given time step <tt>delta_t</tt>.
    */
   virtual void advance_time (const Number delta_t);
 
index 2694688cd6014379b3dfe985208aece74a02cfca..91ae7e878107bcf32847c6b414250ba92dd3e9c2 100644 (file)
@@ -25,20 +25,19 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * A class that can represent the kinds of objects a triangulation is
- * made up of: vertices, lines, quads and hexes.
+ * A class that can represent the kinds of objects a triangulation is made up
+ * of: vertices, lines, quads and hexes.
  *
- * The class is rather primitive: it only stores a single integer
- * that represents the dimensionality of the object represented.
- * In other words, this class is useful primarily as a way to
- * pass around an object whose data type explains what it does
- * (unlike just passing around an integer), and for providing
- * symbolic names for these objects such as GeometryPrimitive::vertex
- * instead of an integer zero.
+ * The class is rather primitive: it only stores a single integer that
+ * represents the dimensionality of the object represented. In other words,
+ * this class is useful primarily as a way to pass around an object whose data
+ * type explains what it does (unlike just passing around an integer), and for
+ * providing symbolic names for these objects such as
+ * GeometryPrimitive::vertex instead of an integer zero.
  *
- * Since the ability to identify such objects with the integral
- * dimension of the object represented, this class provides
- * conversion operators to and from unsigned integers.
+ * Since the ability to identify such objects with the integral dimension of
+ * the object represented, this class provides conversion operators to and
+ * from unsigned integers.
  *
  * @author Wolfgang Bangerth, 2014
  */
@@ -46,12 +45,10 @@ class GeometryPrimitive
 {
 public:
   /**
-   * An enumeration providing symbolic names for the
-   * objects that can be represented by this class.
-   * The numeric values of these symbolic names equal
-   * the geometric dimensionality of the represented
-   * objects to make conversion from and to integer
-   * variables simpler.
+   * An enumeration providing symbolic names for the objects that can be
+   * represented by this class. The numeric values of these symbolic names
+   * equal the geometric dimensionality of the represented objects to make
+   * conversion from and to integer variables simpler.
    */
   enum Object
   {
@@ -62,23 +59,21 @@ public:
   };
 
   /**
-   * Constructor. Initialize the object with the
-   * given argument representing a vertex, line, etc.
+   * Constructor. Initialize the object with the given argument representing a
+   * vertex, line, etc.
    */
   GeometryPrimitive (const Object object);
 
   /**
-   * Constructor. Initialize the object with an
-   * integer that should represent the dimensionality of
-   * the geometric object in question. This will usually be
-   * a number between zero (a vertex) and three (a hexahedron).
+   * Constructor. Initialize the object with an integer that should represent
+   * the dimensionality of the geometric object in question. This will usually
+   * be a number between zero (a vertex) and three (a hexahedron).
    */
   GeometryPrimitive (const unsigned int object_dimension);
 
   /**
-   * Return the integral dimension of the object
-   * currently represented, i.e. zero for a vertex,
-   * one for a line, etc.
+   * Return the integral dimension of the object currently represented, i.e.
+   * zero for a vertex, one for a line, etc.
    */
   operator unsigned int () const;
 
@@ -93,11 +88,11 @@ private:
 
 
 /**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
  *
- * This general template is unused except in some weird template
- * constructs. Actual is made, however, of the specializations
+ * This general template is unused except in some weird template constructs.
+ * Actual is made, however, of the specializations
  * <code>RefinementPossibilities@<1@></code>,
  * <code>RefinementPossibilities@<2@></code>, and
  * <code>RefinementPossibilities@<3@></code>.
@@ -109,20 +104,12 @@ template <int dim>
 struct RefinementPossibilities
 {
   /**
-   * Possible values for refinement
-   * cases in the current
-   * dimension.
-   *
-   * Note the construction of the
-   * values: the lowest bit
-   * describes a cut of the x-axis,
-   * the second to lowest bit
-   * corresponds to a cut of the
-   * y-axis and the third to lowest
-   * bit corresponds to a cut of
-   * the z-axis. Thus, the
-   * following relations hold
-   * (among others):
+   * Possible values for refinement cases in the current dimension.
+   *
+   * Note the construction of the values: the lowest bit describes a cut of
+   * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+   * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+   * following relations hold (among others):
    *
    * @code
    * cut_xy  == cut_x  | cut_y
@@ -130,17 +117,12 @@ struct RefinementPossibilities
    * cut_x   == cut_xy & cut_xz
    * @endcode
    *
-   * Only those cuts that are
-   * reasonable in a given space
-   * dimension are offered, of
-   * course.
+   * Only those cuts that are reasonable in a given space dimension are
+   * offered, of course.
    *
-   * In addition, the tag
-   * <code>isotropic_refinement</code>
-   * denotes isotropic refinement
-   * in the space dimension
-   * selected by the template
-   * argument of this class.
+   * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+   * refinement in the space dimension selected by the template argument of
+   * this class.
    */
   enum Possibilities
   {
@@ -153,8 +135,8 @@ struct RefinementPossibilities
 
 
 /**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
  *
  * This specialization is used for <code>dim=1</code>, where it offers
  * refinement in x-direction.
@@ -166,20 +148,12 @@ template <>
 struct RefinementPossibilities<1>
 {
   /**
-   * Possible values for refinement
-   * cases in the current
-   * dimension.
-   *
-   * Note the construction of the
-   * values: the lowest bit
-   * describes a cut of the x-axis,
-   * the second to lowest bit
-   * corresponds to a cut of the
-   * y-axis and the third to lowest
-   * bit corresponds to a cut of
-   * the z-axis. Thus, the
-   * following relations hold
-   * (among others):
+   * Possible values for refinement cases in the current dimension.
+   *
+   * Note the construction of the values: the lowest bit describes a cut of
+   * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+   * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+   * following relations hold (among others):
    *
    * @code
    * cut_xy  == cut_x  | cut_y
@@ -187,17 +161,12 @@ struct RefinementPossibilities<1>
    * cut_x   == cut_xy & cut_xz
    * @endcode
    *
-   * Only those cuts that are
-   * reasonable in a given space
-   * dimension are offered, of
-   * course.
+   * Only those cuts that are reasonable in a given space dimension are
+   * offered, of course.
    *
-   * In addition, the tag
-   * <code>isotropic_refinement</code>
-   * denotes isotropic refinement
-   * in the space dimension
-   * selected by the template
-   * argument of this class.
+   * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+   * refinement in the space dimension selected by the template argument of
+   * this class.
    */
   enum Possibilities
   {
@@ -211,8 +180,8 @@ struct RefinementPossibilities<1>
 
 
 /**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
  *
  * This specialization is used for <code>dim=2</code>, where it offers
  * refinement in x- and y-direction separately, as well as isotropic
@@ -225,20 +194,12 @@ template <>
 struct RefinementPossibilities<2>
 {
   /**
-   * Possible values for refinement
-   * cases in the current
-   * dimension.
-   *
-   * Note the construction of the
-   * values: the lowest bit
-   * describes a cut of the x-axis,
-   * the second to lowest bit
-   * corresponds to a cut of the
-   * y-axis and the third to lowest
-   * bit corresponds to a cut of
-   * the z-axis. Thus, the
-   * following relations hold
-   * (among others):
+   * Possible values for refinement cases in the current dimension.
+   *
+   * Note the construction of the values: the lowest bit describes a cut of
+   * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+   * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+   * following relations hold (among others):
    *
    * @code
    * cut_xy  == cut_x  | cut_y
@@ -246,17 +207,12 @@ struct RefinementPossibilities<2>
    * cut_x   == cut_xy & cut_xz
    * @endcode
    *
-   * Only those cuts that are
-   * reasonable in a given space
-   * dimension are offered, of
-   * course.
+   * Only those cuts that are reasonable in a given space dimension are
+   * offered, of course.
    *
-   * In addition, the tag
-   * <code>isotropic_refinement</code>
-   * denotes isotropic refinement
-   * in the space dimension
-   * selected by the template
-   * argument of this class.
+   * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+   * refinement in the space dimension selected by the template argument of
+   * this class.
    */
   enum Possibilities
   {
@@ -272,13 +228,12 @@ struct RefinementPossibilities<2>
 
 
 /**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
  *
  * This specialization is used for <code>dim=3</code>, where it offers
- * refinement in x-, y- and z-direction separately, as well as
- * combinations of these and isotropic refinement in all directions at
- * the same time.
+ * refinement in x-, y- and z-direction separately, as well as combinations of
+ * these and isotropic refinement in all directions at the same time.
  *
  * @ingroup aniso
  * @author Ralf Hartmann, 2005, Wolfgang Bangerth, 2007
@@ -287,20 +242,12 @@ template <>
 struct RefinementPossibilities<3>
 {
   /**
-   * Possible values for refinement
-   * cases in the current
-   * dimension.
-   *
-   * Note the construction of the
-   * values: the lowest bit
-   * describes a cut of the x-axis,
-   * the second to lowest bit
-   * corresponds to a cut of the
-   * y-axis and the third to lowest
-   * bit corresponds to a cut of
-   * the z-axis. Thus, the
-   * following relations hold
-   * (among others):
+   * Possible values for refinement cases in the current dimension.
+   *
+   * Note the construction of the values: the lowest bit describes a cut of
+   * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+   * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+   * following relations hold (among others):
    *
    * @code
    * cut_xy  == cut_x  | cut_y
@@ -308,17 +255,12 @@ struct RefinementPossibilities<3>
    * cut_x   == cut_xy & cut_xz
    * @endcode
    *
-   * Only those cuts that are
-   * reasonable in a given space
-   * dimension are offered, of
-   * course.
+   * Only those cuts that are reasonable in a given space dimension are
+   * offered, of course.
    *
-   * In addition, the tag
-   * <code>isotropic_refinement</code>
-   * denotes isotropic refinement
-   * in the space dimension
-   * selected by the template
-   * argument of this class.
+   * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+   * refinement in the space dimension selected by the template argument of
+   * this class.
    */
   enum Possibilities
   {
@@ -338,11 +280,11 @@ struct RefinementPossibilities<3>
 
 
 /**
- * A class storing the possible anisotropic and isotropic refinement
- * cases of an object with <code>dim</code> dimensions (for example,
- * for a line <code>dim=1</code> in whatever space dimension we are,
- * for a quad <code>dim=2</code>, etc.). Possible values of this class
- * are the ones listed in the enumeration declared within the class.
+ * A class storing the possible anisotropic and isotropic refinement cases of
+ * an object with <code>dim</code> dimensions (for example, for a line
+ * <code>dim=1</code> in whatever space dimension we are, for a quad
+ * <code>dim=2</code>, etc.). Possible values of this class are the ones
+ * listed in the enumeration declared within the class.
  *
  * @ingroup aniso
  * @author Ralf Hartmann, 2005, Wolfgang Bangerth, 2007
@@ -352,114 +294,74 @@ class RefinementCase : public RefinementPossibilities<dim>
 {
 public:
   /**
-   * Default constructor. Initialize the
-   * refinement case with no_refinement.
+   * Default constructor. Initialize the refinement case with no_refinement.
    */
   RefinementCase ();
 
   /**
-   * Constructor. Take and store a
-   * value indicating a particular
-   * refinement from the list of
-   * possible refinements specified
-   * in the base class.
+   * Constructor. Take and store a value indicating a particular refinement
+   * from the list of possible refinements specified in the base class.
    */
   RefinementCase (const typename RefinementPossibilities<dim>::Possibilities refinement_case);
 
   /**
-   * Constructor. Take and store a
-   * value indicating a particular
-   * refinement as a bit field. To
-   * avoid implicit conversions to
-   * and from integral values, this
-   * constructor is marked as
-   * explicit.
+   * Constructor. Take and store a value indicating a particular refinement as
+   * a bit field. To avoid implicit conversions to and from integral values,
+   * this constructor is marked as explicit.
    */
   explicit RefinementCase (const unsigned char refinement_case);
 
   /**
-   * Return the numeric value
-   * stored by this class. While
-   * the presence of this operator
-   * might seem dangerous, it is
-   * useful in cases where one
-   * would like to have code like
-   * <tt>switch
-   * (refinement_flag)... case
-   * RefinementCase<dim>::cut_x:
-   * ... </tt>, which can be
-   * written as <code>switch
-   * (static_cast@<unsigned
-   * char@>(refinement_flag)</code>. Another
-   * application is to use an
-   * object of the current type as
-   * an index into an array;
-   * however, this use is
-   * deprecated as it assumes a
-   * certain mapping from the
-   * symbolic flags defined in the
-   * RefinementPossibilities base
-   * class to actual numerical
-   * values (the array indices).
+   * Return the numeric value stored by this class. While the presence of this
+   * operator might seem dangerous, it is useful in cases where one would like
+   * to have code like <tt>switch (refinement_flag)... case
+   * RefinementCase<dim>::cut_x: ... </tt>, which can be written as
+   * <code>switch (static_cast@<unsigned char@>(refinement_flag)</code>.
+   * Another application is to use an object of the current type as an index
+   * into an array; however, this use is deprecated as it assumes a certain
+   * mapping from the symbolic flags defined in the RefinementPossibilities
+   * base class to actual numerical values (the array indices).
    */
   operator unsigned char () const;
 
   /**
-   * Return the union of the
-   * refinement flags represented
-   * by the current object and the
-   * one given as argument.
+   * Return the union of the refinement flags represented by the current
+   * object and the one given as argument.
    */
   RefinementCase operator | (const RefinementCase &r) const;
 
   /**
-   * Return the intersection of the
-   * refinement flags represented
-   * by the current object and the
-   * one given as argument.
+   * Return the intersection of the refinement flags represented by the
+   * current object and the one given as argument.
    */
   RefinementCase operator & (const RefinementCase &r) const;
 
   /**
-   * Return the negation of the
-   * refinement flags represented
-   * by the current object. For
-   * example, in 2d, if the current
-   * object holds the flag
-   * <code>cut_x</code>, then the
-   * returned value will be
-   * <code>cut_y</code>; if the
-   * current value is
-   * <code>isotropic_refinement</code>
-   * then the result will be
-   * <code>no_refinement</code>;
-   * etc.
+   * Return the negation of the refinement flags represented by the current
+   * object. For example, in 2d, if the current object holds the flag
+   * <code>cut_x</code>, then the returned value will be <code>cut_y</code>;
+   * if the current value is <code>isotropic_refinement</code> then the result
+   * will be <code>no_refinement</code>; etc.
    */
   RefinementCase operator ~ () const;
 
 
   /**
-   * Return the flag that
-   * corresponds to cutting a cell
-   * along the axis given as
-   * argument. For example, if
-   * <code>i=0</code> then the
-   * returned value is
+   * Return the flag that corresponds to cutting a cell along the axis given
+   * as argument. For example, if <code>i=0</code> then the returned value is
    * <tt>RefinementPossibilities<dim>::cut_x</tt>.
    */
   static
   RefinementCase cut_axis (const unsigned int i);
 
   /**
-   * Return the amount of memory
-   * occupied by an object of this
-   * type.
+   * Return the amount of memory occupied by an object of this type.
    */
   static std::size_t memory_consumption ();
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar,
@@ -475,10 +377,8 @@ public:
 
 private:
   /**
-   * Store the refinement case as a
-   * bit field with as many bits as
-   * are necessary in any given
-   * dimension.
+   * Store the refinement case as a bit field with as many bits as are
+   * necessary in any given dimension.
    */
 unsigned char value :
   (dim > 0 ? dim : 1);
@@ -490,19 +390,18 @@ namespace internal
 
 
   /**
-   * A class that provides all possible situations a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces. For <code>dim=1</code> and <code>dim=2</code> they
-   * correspond to the cases given in
-   * <code>RefinementPossibilities@<dim-1@></code>. However,
-   * <code>SubfacePossibilities@<3@></code> includes the refinement
-   * cases of <code>RefinementPossibilities@<2@></code>, but
-   * additionally some subface possibilities a face might be subdivided
-   * into which occur through repeated anisotropic refinement steps
-   * performed on one of two neighboring cells.
+   * A class that provides all possible situations a face (in the current
+   * space dimension @p dim) might be subdivided into subfaces. For
+   * <code>dim=1</code> and <code>dim=2</code> they correspond to the cases
+   * given in <code>RefinementPossibilities@<dim-1@></code>. However,
+   * <code>SubfacePossibilities@<3@></code> includes the refinement cases of
+   * <code>RefinementPossibilities@<2@></code>, but additionally some subface
+   * possibilities a face might be subdivided into which occur through
+   * repeated anisotropic refinement steps performed on one of two neighboring
+   * cells.
    *
-   * This general template is unused except in some weird template
-   * constructs. Actual is made, however, of the specializations
+   * This general template is unused except in some weird template constructs.
+   * Actual is made, however, of the specializations
    * <code>SubfacePossibilities@<1@></code>,
    * <code>SubfacePossibilities@<2@></code> and
    * <code>SubfacePossibilities@<3@></code>.
@@ -514,9 +413,7 @@ namespace internal
   struct SubfacePossibilities
   {
     /**
-     * Possible cases of faces
-     * being subdivided into
-     * subface.
+     * Possible cases of faces being subdivided into subface.
      */
     enum Possibilities
     {
@@ -528,9 +425,8 @@ namespace internal
 
 
   /**
-   * A class that provides all possible situations a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces.
+   * A class that provides all possible situations a face (in the current
+   * space dimension @p dim) might be subdivided into subfaces.
    *
    * For <code>dim=0</code> we provide a dummy implementation only.
    *
@@ -541,9 +437,7 @@ namespace internal
   struct SubfacePossibilities<0>
   {
     /**
-     * Possible cases of faces
-     * being subdivided into
-     * subface.
+     * Possible cases of faces being subdivided into subface.
      *
      * Dummy implementation.
      */
@@ -558,12 +452,11 @@ namespace internal
 
 
   /**
-   * A class that provides all possible situations a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces.
+   * A class that provides all possible situations a face (in the current
+   * space dimension @p dim) might be subdivided into subfaces.
    *
-   * For <code>dim=1</code> there are no faces. Thereby, there are no
-   * subface possibilities.
+   * For <code>dim=1</code> there are no faces. Thereby, there are no subface
+   * possibilities.
    *
    * @ingroup aniso
    * @author Ralf Hartmann, 2008
@@ -572,13 +465,9 @@ namespace internal
   struct SubfacePossibilities<1>
   {
     /**
-     * Possible cases of faces
-     * being subdivided into
-     * subface.
+     * Possible cases of faces being subdivided into subface.
      *
-     * In 1d there are no faces,
-     * thus no subface
-     * possibilities.
+     * In 1d there are no faces, thus no subface possibilities.
      */
     enum Possibilities
     {
@@ -591,12 +480,11 @@ namespace internal
 
 
   /**
-   * A class that provides all possible situations a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces.
+   * A class that provides all possible situations a face (in the current
+   * space dimension @p dim) might be subdivided into subfaces.
    *
-   * This specialization is used for <code>dim=2</code>, where it offers
-   * the following possibilities: a face (line) being refined
+   * This specialization is used for <code>dim=2</code>, where it offers the
+   * following possibilities: a face (line) being refined
    * (<code>case_x</code>) or not refined (<code>case_no</code>).
    *
    * @ingroup aniso
@@ -606,17 +494,11 @@ namespace internal
   struct SubfacePossibilities<2>
   {
     /**
-     * Possible cases of faces
-     * being subdivided into
-     * subface.
+     * Possible cases of faces being subdivided into subface.
      *
-     * In 2d there are following
-     * possibilities: a face (line)
-     * being refined *
-     * (<code>case_x</code>) or not
-     * refined
-     * (<code>case_no</code>).
-    */
+     * In 2d there are following possibilities: a face (line) being refined *
+     * (<code>case_x</code>) or not refined (<code>case_no</code>).
+     */
     enum Possibilities
     {
       case_none = 0,
@@ -629,95 +511,92 @@ namespace internal
 
 
   /**
-   * A class that provides all possible situations a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces.
+   * A class that provides all possible situations a face (in the current
+   * space dimension @p dim) might be subdivided into subfaces.
    *
    * This specialization is used for dim=3, where it offers following
-   * possibilities: a face (quad) being refined in x- or y-direction (in
-   * the face-intern coordinate system) separately, (<code>case_x</code>
-   * or (<code>case_y</code>), and in both directions
-   * (<code>case_x</code> which corresponds to
-   * (<code>case_isotropic</code>). Additionally, it offers the
-   * possibilities a face can have through repeated anisotropic
-   * refinement steps performed on one of the two neighboring cells.  It
-   * might be possible for example, that a face (quad) is refined with
-   * <code>cut_x</code> and afterwards the left child is again refined
-   * with <code>cut_y</code>, so that there are three active
-   * subfaces. Note, however, that only refinement cases are allowed
-   * such that each line on a face between two hexes has not more than
-   * one hanging node. Furthermore, it is not allowed that two
-   * neighboring hexes are refined such that one of the hexes refines
-   * the common face with <code>cut_x</code> and the other hex refines
-   * that face with <code>cut_y</code>. In fact,
+   * possibilities: a face (quad) being refined in x- or y-direction (in the
+   * face-intern coordinate system) separately, (<code>case_x</code> or
+   * (<code>case_y</code>), and in both directions (<code>case_x</code> which
+   * corresponds to (<code>case_isotropic</code>). Additionally, it offers the
+   * possibilities a face can have through repeated anisotropic refinement
+   * steps performed on one of the two neighboring cells.  It might be
+   * possible for example, that a face (quad) is refined with
+   * <code>cut_x</code> and afterwards the left child is again refined with
+   * <code>cut_y</code>, so that there are three active subfaces. Note,
+   * however, that only refinement cases are allowed such that each line on a
+   * face between two hexes has not more than one hanging node. Furthermore,
+   * it is not allowed that two neighboring hexes are refined such that one of
+   * the hexes refines the common face with <code>cut_x</code> and the other
+   * hex refines that face with <code>cut_y</code>. In fact,
    * Triangulation::prepare_coarsening_and_refinement takes care of this
-   * situation and ensures that each face of a refined cell is
-   * completely contained in a single face of neighboring cells.
+   * situation and ensures that each face of a refined cell is completely
+   * contained in a single face of neighboring cells.
    *
-   * The following drawings explain the SubfacePossibilities and give
-   * the corresponding subface numbers:
+   * The following drawings explain the SubfacePossibilities and give the
+   * corresponding subface numbers:
    * @code
-
-   *-------*
-   |       |
-   |   0   |    case_none
-   |       |
-   *-------*
-
-   *---*---*
-   |   |   |
-   | 0 | 1 |    case_x
-   |   |   |
-   *---*---*
-
-   *---*---*
-   | 1 |   |
-   *---* 2 |    case_x1y
-   | 0 |   |
-   *---*---*
-
-   *---*---*
-   |   | 2 |
-   | 0 *---*    case_x2y
-   |   | 1 |
-   *---*---*
-
-   *---*---*
-   | 1 | 3 |
-   *---*---*    case_x1y2y   (successive refinement: first cut_x, then cut_y for both children)
-   | 0 | 2 |
-   *---*---*
-
-   *-------*
-   |   1   |
-   *-------*    case_y
-   |   0   |
-   *-------*
-
-   *-------*
-   |   2   |
-   *---*---*    case_y1x
-   | 0 | 1 |
-   *---*---*
-
-   *---*---*
-   | 1 | 2 |
-   *---*---*    case_y2x
-   |   0   |
-   *-------*
-
-   *---*---*
-   | 2 | 3 |
-   *---*---*    case_y1x2x   (successive refinement: first cut_y, then cut_x for both children)
-   | 0 | 1 |
-   *---+---*
-
-   *---*---*
-   | 2 | 3 |
-   *---*---*    case_xy      (one isotropic refinement step)
-   | 0 | 1 |
-   *---*---*
-
+   *
+   * *-------*
+   |       |
+   |   0   |    case_none
+   |       |
+   * *-------*
+   *
+   * *---*---*
+   |   |   |
+   | 0 | 1 |    case_x
+   |   |   |
+   * *---*---*
+   *
+   * *---*---*
+   | 1 |   |
+   * *---* 2 |    case_x1y
+   | 0 |   |
+   * *---*---*
+   *
+   * *---*---*
+   |   | 2 |
+   | 0 *---*    case_x2y
+   |   | 1 |
+   * *---*---*
+   *
+   * *---*---*
+   | 1 | 3 |
+   * *---*---*    case_x1y2y   (successive refinement: first cut_x, then cut_y for both children)
+   | 0 | 2 |
+   * *---*---*
+   *
+   * *-------*
+   |   1   |
+   * *-------*    case_y
+   |   0   |
+   * *-------*
+   *
+   * *-------*
+   |   2   |
+   * *---*---*    case_y1x
+   | 0 | 1 |
+   * *---*---*
+   *
+   * *---*---*
+   | 1 | 2 |
+   * *---*---*    case_y2x
+   |   0   |
+   * *-------*
+   *
+   * *---*---*
+   | 2 | 3 |
+   * *---*---*    case_y1x2x   (successive refinement: first cut_y, then cut_x for both children)
+   | 0 | 1 |
+   * *---+---*
+   *
+   * *---*---*
+   | 2 | 3 |
+   * *---*---*    case_xy      (one isotropic refinement step)
+   | 0 | 1 |
+   * *---*---*
+   *
    * @endcode
    *
    * @ingroup aniso
@@ -727,14 +606,10 @@ namespace internal
   struct SubfacePossibilities<3>
   {
     /**
-     * Possible cases of faces
-     * being subdivided into
-     * subface.
+     * Possible cases of faces being subdivided into subface.
      *
-     * See documentation to the
-     * SubfacePossibilities<3> for
-     * more details on the subface
-     * possibilities.
+     * See documentation to the SubfacePossibilities<3> for more details on
+     * the subface possibilities.
      */
     enum Possibilities
     {
@@ -757,9 +632,8 @@ namespace internal
 
 
   /**
-   * A class that provides all possible cases a face (in the
-   * current space dimension @p dim) might be subdivided into
-   * subfaces.
+   * A class that provides all possible cases a face (in the current space
+   * dimension @p dim) might be subdivided into subfaces.
    *
    * @ingroup aniso
    * @author Ralf Hartmann, 2008
@@ -769,46 +643,27 @@ namespace internal
   {
   public:
     /**
-     * Constructor. Take and store
-     * a value indicating a
-     * particular subface
-     * possibility in the list of
-     * possible situations
-     * specified in the base class.
+     * Constructor. Take and store a value indicating a particular subface
+     * possibility in the list of possible situations specified in the base
+     * class.
      */
     SubfaceCase (const typename SubfacePossibilities<dim>::Possibilities subface_possibility);
 
     /**
-     * Return the numeric value
-     * stored by this class. While
-     * the presence of this operator
-     * might seem dangerous, it is
-     * useful in cases where one
-     * would like to have code like
-     * <code>switch
-     * (subface_case)... case
-     * SubfaceCase::case_x:
-     * ... </code>, which can be
-     * written as <code>switch
-     * (static_cast@<unsigned
-     * char@>(subface_case)</code>. Another
-     * application is to use an
-     * object of the current type as
-     * an index into an array;
-     * however, this use is
-     * deprecated as it assumes a
-     * certain mapping from the
-     * symbolic flags defined in the
-     * SubfacePossibilities
-     * base class to actual numerical
-     * values (the array indices).
+     * Return the numeric value stored by this class. While the presence of
+     * this operator might seem dangerous, it is useful in cases where one
+     * would like to have code like <code>switch (subface_case)... case
+     * SubfaceCase::case_x: ... </code>, which can be written as <code>switch
+     * (static_cast@<unsigned char@>(subface_case)</code>. Another application
+     * is to use an object of the current type as an index into an array;
+     * however, this use is deprecated as it assumes a certain mapping from
+     * the symbolic flags defined in the SubfacePossibilities base class to
+     * actual numerical values (the array indices).
      */
     operator unsigned char () const;
 
     /**
-     * Return the amount of memory
-     * occupied by an object of this
-     * type.
+     * Return the amount of memory occupied by an object of this type.
      */
     static std::size_t memory_consumption ();
 
@@ -822,10 +677,8 @@ namespace internal
 
   private:
     /**
-     * Store the refinement case as a
-     * bit field with as many bits as
-     * are necessary in any given
-     * dimension.
+     * Store the refinement case as a bit field with as many bits as are
+     * necessary in any given dimension.
      */
   unsigned char value :
     (dim == 3 ? 4 : 1);
@@ -841,21 +694,18 @@ template <int dim> struct GeometryInfo;
 
 
 /**
- * Topological description of zero dimensional cells,
- * i.e. points. This class might not look too useful but often is if
- * in a certain dimension we would like to enquire information about
- * objects with dimension one lower than the present, e.g. about
- * faces.
- *
- * This class contains as static members information on vertices and
- * faces of a @p dim-dimensional grid cell. The interface is the same
- * for all dimensions. If a value is of no use in a low dimensional
- * cell, it is (correctly) set to zero, e.g. #max_children_per_face in
- * 1d.
- *
- * This information should always replace hard-coded numbers of
- * vertices, neighbors and so on, since it can be used dimension
- * independently.
+ * Topological description of zero dimensional cells, i.e. points. This class
+ * might not look too useful but often is if in a certain dimension we would
+ * like to enquire information about objects with dimension one lower than the
+ * present, e.g. about faces.
+ *
+ * This class contains as static members information on vertices and faces of
+ * a @p dim-dimensional grid cell. The interface is the same for all
+ * dimensions. If a value is of no use in a low dimensional cell, it is
+ * (correctly) set to zero, e.g. #max_children_per_face in 1d.
+ *
+ * This information should always replace hard-coded numbers of vertices,
+ * neighbors and so on, since it can be used dimension independently.
  *
  * @ingroup grid geomprimitives aniso
  * @author Wolfgang Bangerth, 1998
@@ -865,15 +715,11 @@ struct GeometryInfo<0>
 {
 
   /**
-   * Maximum number of children of
-   * a cell, i.e. the number of
-   * children of an isotropically
-   * refined cell.
+   * Maximum number of children of a cell, i.e. the number of children of an
+   * isotropically refined cell.
    *
-   * If a cell is refined
-   * anisotropically, the actual
-   * number of children may be less
-   * than the value given here.
+   * If a cell is refined anisotropically, the actual number of children may
+   * be less than the value given here.
    */
   static const unsigned int max_children_per_cell = 1;
 
@@ -883,25 +729,18 @@ struct GeometryInfo<0>
   static const unsigned int faces_per_cell    = 0;
 
   /**
-   * Maximum number of children of
-   * a refined face, i.e. the
-   * number of children of an
-   * isotropically refined face.
+   * Maximum number of children of a refined face, i.e. the number of children
+   * of an isotropically refined face.
    *
-   * If a cell is refined
-   * anisotropically, the actual
-   * number of children may be less
-   * than the value given here.
+   * If a cell is refined anisotropically, the actual number of children may
+   * be less than the value given here.
    */
   static const unsigned int max_children_per_face = 0;
 
   /**
-   * Return the number of children
-   * of a cell (or face) refined
-   * with <tt>ref_case</tt>. Since
-   * we are concerned here with
-   * points, the number of children
-   * is equal to one.
+   * Return the number of children of a cell (or face) refined with
+   * <tt>ref_case</tt>. Since we are concerned here with points, the number of
+   * children is equal to one.
    */
   static unsigned int n_children(const RefinementCase<0> &refinement_case);
 
@@ -911,13 +750,10 @@ struct GeometryInfo<0>
   static const unsigned int vertices_per_cell = 1;
 
   /**
-   * Number of vertices each face has.
-   * Since this is not useful in one
-   * dimension, we provide a useless
-   * number (in the hope that a compiler
-   * may warn when it sees constructs like
-   * <tt>for (i=0; i<vertices_per_face; ++i)</tt>,
-   * at least if @p i is an <tt>unsigned int</tt>.
+   * Number of vertices each face has. Since this is not useful in one
+   * dimension, we provide a useless number (in the hope that a compiler may
+   * warn when it sees constructs like <tt>for (i=0; i<vertices_per_face;
+   * ++i)</tt>, at least if @p i is an <tt>unsigned int</tt>.
    */
   static const unsigned int vertices_per_face = 0;
 
@@ -937,14 +773,12 @@ struct GeometryInfo<0>
   static const unsigned int lines_per_cell    = 0;
 
   /**
-   * Number of quadrilaterals of a
-   * cell.
+   * Number of quadrilaterals of a cell.
    */
   static const unsigned int quads_per_cell    = 0;
 
   /**
-   * Number of hexahedra of a
-   * cell.
+   * Number of hexahedra of a cell.
    */
   static const unsigned int hexes_per_cell    = 0;
 };
@@ -955,16 +789,16 @@ struct GeometryInfo<0>
 
 /**
  * This class provides dimension independent information to all topological
- * structures that make up the unit, or
- * @ref GlossReferenceCell "reference cell".
+ * structures that make up the unit, or @ref GlossReferenceCell "reference
+ * cell".
  *
  * It is the one central point in the library where information about the
- * numbering of vertices, lines, or faces of the reference cell is
- * collected. Consequently, the information of this class is used extensively
- * in the geometric description of Triangulation objects, as well as in
- * various other parts of the code. In particular, it also serves as the focus
- * of writing code in a dimension independent way; for example, instead of
- * writing a loop over vertices 0<=v<4 in 2d, one would write it as
+ * numbering of vertices, lines, or faces of the reference cell is collected.
+ * Consequently, the information of this class is used extensively in the
+ * geometric description of Triangulation objects, as well as in various other
+ * parts of the code. In particular, it also serves as the focus of writing
+ * code in a dimension independent way; for example, instead of writing a loop
+ * over vertices 0<=v<4 in 2d, one would write it as
  * 0<=v<GeometryInfo<dim>::vertices_per_cell, thus allowing the code to work
  * in 3d as well without changes.
  *
@@ -977,31 +811,29 @@ struct GeometryInfo<0>
  *
  * <h3>Implementation conventions for two spatial dimensions</h3>
  *
- * From version 5.2 onwards deal.II is based on a numbering scheme
- * that uses a lexicographic ordering (with x running fastest)
- * wherever possible, hence trying to adopt a kind of 'canonical'
- * ordering.
+ * From version 5.2 onwards deal.II is based on a numbering scheme that uses a
+ * lexicographic ordering (with x running fastest) wherever possible, hence
+ * trying to adopt a kind of 'canonical' ordering.
  *
  * The ordering of vertices and faces (lines) in 2d is defined by
  *
  * - Vertices are numbered in lexicographic ordering
  *
- * - Faces (lines in 2d): first the two faces with normals in x-
- *   and then y-direction. For each two faces: first the face with
- *   normal in negative coordinate direction, then the one with normal
- *   in positive direction, i.e. the faces are ordered according to
- *   their normals pointing in -x, x, -y, y direction.
+ * - Faces (lines in 2d): first the two faces with normals in x- and then
+ * y-direction. For each two faces: first the face with normal in negative
+ * coordinate direction, then the one with normal in positive direction, i.e.
+ * the faces are ordered according to their normals pointing in -x, x, -y, y
+ * direction.
  *
- * - The direction of a line is represented by the direction of
- *   point 0 towards point 1 and is always in one of the coordinate
- *   directions
+ * - The direction of a line is represented by the direction of point 0
+ * towards point 1 and is always in one of the coordinate directions
  *
- * - Face lines in 3d are ordered, such that the induced 2d local
- *   coordinate system (x,y) implies (right hand rule) a normal in
- *   face normal direction, see N2/.
+ * - Face lines in 3d are ordered, such that the induced 2d local coordinate
+ * system (x,y) implies (right hand rule) a normal in face normal direction,
+ * see N2/.
  *
- * The resulting numbering of vertices and faces (lines) in 2d as
- * well as the directions of lines is shown in the following.
+ * The resulting numbering of vertices and faces (lines) in 2d as well as the
+ * directions of lines is shown in the following.
  * @verbatim
  *       3
  *    2-->--3
@@ -1024,9 +856,9 @@ struct GeometryInfo<0>
  * Similarly we define, that the four children of a quad are adjacent to the
  * vertex with the same number of the old quad.
  *
- * Note that information about several of these conventions can be
- * extracted at run- or compile-time from the member functions and
- * variables of the present class.
+ * Note that information about several of these conventions can be extracted
+ * at run- or compile-time from the member functions and variables of the
+ * present class.
  *
  *
  * <h4>Coordinate systems</h4>
@@ -1051,11 +883,10 @@ struct GeometryInfo<0>
  *
  * <h3>Implementation conventions for three spatial dimensions</h3>
  *
- * By convention, we will use the following numbering conventions
- * for vertices, lines and faces of hexahedra in three space
- * dimensions. Before giving these conventions we declare the
- * following sketch to be the standard way of drawing 3d pictures of
- * hexahedra:
+ * By convention, we will use the following numbering conventions for
+ * vertices, lines and faces of hexahedra in three space dimensions. Before
+ * giving these conventions we declare the following sketch to be the standard
+ * way of drawing 3d pictures of hexahedra:
  * @verbatim
  *                       *-------*        *-------*
  *                      /|       |       /       /|
@@ -1072,14 +903,14 @@ struct GeometryInfo<0>
  * cube, while the right one shall be the top, right and front face. You may
  * recover the whole cube by moving the two parts together into one.
  *
- * Note again that information about several of the following
- * conventions can be extracted at run- or compile-time from the
- * member functions and variables of the present class.
+ * Note again that information about several of the following conventions can
+ * be extracted at run- or compile-time from the member functions and
+ * variables of the present class.
  *
  * <h4>Vertices</h4>
  *
- * The ordering of vertices in 3d is defined by the same rules as in
- * the 2d case. In particular, the following is still true:
+ * The ordering of vertices in 3d is defined by the same rules as in the 2d
+ * case. In particular, the following is still true:
  *
  * - Vertices are numbered in lexicographic ordering.
  *
@@ -1109,11 +940,11 @@ struct GeometryInfo<0>
  * Here, the same holds as for the vertices:
  *
  * - Line ordering in 3d:
- *   <ul>
- *   <li>first the lines of face (z=0) in 2d line ordering,
- *   <li>then the lines of face (z=1) in 2d line ordering,
- *   <li>finally the lines in z direction in lexicographic ordering
- *   </ul>
+ * <ul>
+ * <li>first the lines of face (z=0) in 2d line ordering,
+ * <li>then the lines of face (z=1) in 2d line ordering,
+ * <li>finally the lines in z direction in lexicographic ordering
+ * </ul>
  * @verbatim
  *       *---7---*        *---7---*
  *      /|       |       /       /|
@@ -1140,31 +971,30 @@ struct GeometryInfo<0>
  *   *--->---*        *--->---*
  * @endverbatim
  *
- * The fact that edges (just as vertices and faces) are entities that
- * are stored in their own right rather than constructed from cells
- * each time they are needed, means that adjacent cells actually have
- * pointers to edges that are thus shared between them. This implies
- * that the convention that sets of parallel edges have parallel
- * directions is not only a local condition. Before a list of cells is
- * passed to an object of the Triangulation class for creation of a
- * triangulation, you therefore have to make sure that cells are
- * oriented in a compatible fashion, so that edge directions are
- * globally according to above convention. However, the GridReordering
- * class can do this for you, by reorienting cells and edges of an
- * arbitrary list of input cells that need not be already sorted.
+ * The fact that edges (just as vertices and faces) are entities that are
+ * stored in their own right rather than constructed from cells each time they
+ * are needed, means that adjacent cells actually have pointers to edges that
+ * are thus shared between them. This implies that the convention that sets of
+ * parallel edges have parallel directions is not only a local condition.
+ * Before a list of cells is passed to an object of the Triangulation class
+ * for creation of a triangulation, you therefore have to make sure that cells
+ * are oriented in a compatible fashion, so that edge directions are globally
+ * according to above convention. However, the GridReordering class can do
+ * this for you, by reorienting cells and edges of an arbitrary list of input
+ * cells that need not be already sorted.
  *
  * <h4>Faces</h4>
  *
  * The numbering of faces in 3d is defined by a rule analogous to 2d:
  *
- * - Faces (quads in 3d): first the two faces with normals in x-,
- * then y- and z-direction. For each two faces: first the face with
- * normal in negative coordinate direction, then the one with normal
- * in positive direction, i.e. the faces are ordered according to
- * their normals pointing in -x, x, -y, y, -z, z direction.
+ * - Faces (quads in 3d): first the two faces with normals in x-, then y- and
+ * z-direction. For each two faces: first the face with normal in negative
+ * coordinate direction, then the one with normal in positive direction, i.e.
+ * the faces are ordered according to their normals pointing in -x, x, -y, y,
+ * -z, z direction.
  *
- * Therefore, the faces are numbered in the ordering: left, right,
- * front, back, bottom and top face:
+ * Therefore, the faces are numbered in the ordering: left, right, front,
+ * back, bottom and top face:
  * @verbatim
  *       *-------*        *-------*
  *      /|       |       /       /|
@@ -1178,11 +1008,10 @@ struct GeometryInfo<0>
  *   *-------*        *-------*
  * @endverbatim
  *
- * The <em>standard</em> direction of the faces is such, that the
- * induced 2d local coordinate system (x,y) implies (right hand
- * rule) a normal in face normal direction, see N2a).  In the
- * following we show the local coordinate system and the numbering
- * of face lines:
+ * The <em>standard</em> direction of the faces is such, that the induced 2d
+ * local coordinate system (x,y) implies (right hand rule) a normal in face
+ * normal direction, see N2a).  In the following we show the local coordinate
+ * system and the numbering of face lines:
  * <ul>
  * <li> Faces 0 and 1:
  *  @verbatim
@@ -1230,8 +1059,7 @@ struct GeometryInfo<0>
  *  @endverbatim
  * </ul>
  *
- * The face line numbers (0,1,2,3) correspond to following cell line
- * numbers.
+ * The face line numbers (0,1,2,3) correspond to following cell line numbers.
  * <ul>
  * <li> Face 0: lines 8, 10, 0, 4;
  * <li> Face 1: lines 9, 11, 1, 5;
@@ -1240,25 +1068,23 @@ struct GeometryInfo<0>
  * <li> Face 4: lines 0, 1, 2, 3;
  * <li> Face 5: lines 4, 5, 6, 7;
  * </ul>
- * You can get these numbers using the
- * GeometryInfo<3>::face_to_cell_lines() function.
- *
- * The face normals can be deduced from the face orientation by
- * applying the right hand side rule (x,y -> normal).  We note, that
- * in the standard orientation of faces in 2d, faces 0 and 2 have
- * normals that point into the cell, and faces 1 and 3 have normals
- * pointing outward. In 3d, faces 0, 2, and 4
- * have normals that point into the cell, while the normals of faces
- * 1, 3, and 5 point outward. This information, again, can be queried from
+ * You can get these numbers using the GeometryInfo<3>::face_to_cell_lines()
+ * function.
+ *
+ * The face normals can be deduced from the face orientation by applying the
+ * right hand side rule (x,y -> normal).  We note, that in the standard
+ * orientation of faces in 2d, faces 0 and 2 have normals that point into the
+ * cell, and faces 1 and 3 have normals pointing outward. In 3d, faces 0, 2,
+ * and 4 have normals that point into the cell, while the normals of faces 1,
+ * 3, and 5 point outward. This information, again, can be queried from
  * GeometryInfo<dim>::unit_normal_orientation.
  *
- * However, it turns out that a significant number of 3d meshes cannot
- * satisfy this convention. This is due to the fact that the face
- * convention for one cell already implies something for the
- * neighbor, since they share a common face and fixing it for the
- * first cell also fixes the normal vectors of the opposite faces of
- * both cells. It is easy to construct cases of loops of cells for
- * which this leads to cases where we cannot find orientations for
+ * However, it turns out that a significant number of 3d meshes cannot satisfy
+ * this convention. This is due to the fact that the face convention for one
+ * cell already implies something for the neighbor, since they share a common
+ * face and fixing it for the first cell also fixes the normal vectors of the
+ * opposite faces of both cells. It is easy to construct cases of loops of
+ * cells for which this leads to cases where we cannot find orientations for
  * all faces that are consistent with this convention.
  *
  * For this reason, above convention is only what we call the <em>standard
@@ -1271,29 +1097,29 @@ struct GeometryInfo<0>
  * normal vector is pointing the other direction. There are not very many
  * places in application programs where you need this information actually,
  * but a few places in the library make use of this. Note that in 2d, the
- * result is always @p true. More information on the topic can be found in this
- * @ref GlossFaceOrientation "glossary" article.
+ * result is always @p true. More information on the topic can be found in
+ * this @ref GlossFaceOrientation "glossary" article.
  *
  * In order to allow all kinds of meshes in 3d, including
- * <em>Moebius</em>-loops, a face might even be rotated looking
- * from one cell, whereas it is according to the standard looking at it from the
- * neighboring cell sharing that particular face. In order to cope with this,
- * two flags <tt>face_flip</tt> and <tt>face_rotation</tt> are available, to
- * represent rotations by 180 and 90 degree, respectively. Setting both flags
- * amounts to a rotation of 270 degrees (all counterclockwise). You can ask
- * the cell for these flags like for the <tt>face_orientation</tt>. In order to
- * enable rotated faces, even lines can deviate from their standard direction in
- * 3d. This information is available as the <tt>line_orientation</tt> flag for
+ * <em>Moebius</em>-loops, a face might even be rotated looking from one cell,
+ * whereas it is according to the standard looking at it from the neighboring
+ * cell sharing that particular face. In order to cope with this, two flags
+ * <tt>face_flip</tt> and <tt>face_rotation</tt> are available, to represent
+ * rotations by 180 and 90 degree, respectively. Setting both flags amounts to
+ * a rotation of 270 degrees (all counterclockwise). You can ask the cell for
+ * these flags like for the <tt>face_orientation</tt>. In order to enable
+ * rotated faces, even lines can deviate from their standard direction in 3d.
+ * This information is available as the <tt>line_orientation</tt> flag for
  * cells and faces in 3d. Again, this is something that should be internal to
- * the library and application program will probably never have to bother about
- * it. For more information on this see also
- * @ref GlossFaceOrientation "this glossary entry" .
+ * the library and application program will probably never have to bother
+ * about it. For more information on this see also @ref GlossFaceOrientation
+ * "this glossary entry" .
  *
  *
  * <h4>Children</h4>
  *
- * The eight children of an isotropically refined cell are numbered according to
- * the vertices they are adjacent to:
+ * The eight children of an isotropically refined cell are numbered according
+ * to the vertices they are adjacent to:
  * @verbatim
  *       *----*----*        *----*----*
  *      /| 6  |  7 |       / 6  /  7 /|
@@ -1308,8 +1134,8 @@ struct GeometryInfo<0>
  *   *----*----*        *----*----*
  * @endverbatim
  *
- * Taking into account the orientation of the faces, the following
- * children are adjacent to the respective faces:
+ * Taking into account the orientation of the faces, the following children
+ * are adjacent to the respective faces:
  * <ul>
  * <li> Face 0: children 0, 2, 4, 6;
  * <li> Face 1: children 1, 3, 5, 7;
@@ -1318,35 +1144,32 @@ struct GeometryInfo<0>
  * <li> Face 4: children 0, 1, 2, 3;
  * <li> Face 5: children 4, 5, 6, 7.
  * </ul>
- * You can get these numbers using the
- * GeometryInfo<3>::child_cell_on_face() function. As each child is
- * adjacent to the vertex with the same number these numbers are
- * also given by the GeometryInfo<3>::face_to_cell_vertices()
- * function.
- *
- * Note that, again, the above list only holds for faces in their
- * standard orientation. If a face is not in standard orientation,
- * then the children at positions 1 and 2 (counting from 0 to 3)
- * would be swapped. In fact, this is what the child_cell_on_face
- * and the face_to_cell_vertices functions of GeometryInfo<3> do,
- * when invoked with a <tt>face_orientation=false</tt> argument.
- *
- * The information which child cell is at which position of which face
- * is most often used when computing jump terms across faces with
- * hanging nodes, using objects of type FESubfaceValues. Sitting on
- * one cell, you would look at a face and figure out which child of
- * the neighbor is sitting on a given subface between the present and
- * the neighboring cell. To avoid having to query the standard
- * orientation of the faces of the two cells every time in such cases,
- * you should use a function call like
- * <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>, which
- * returns the correct result both in 2d (where face orientations are
- * immaterial) and 3d (where it is necessary to use the face
- * orientation as additional argument to
- * <tt>GeometryInfo<3>::child_cell_on_face</tt>).
- *
- * For anisotropic refinement, the child cells can not be numbered according to
- * adjacent vertices, thus the following conventions are used:
+ * You can get these numbers using the GeometryInfo<3>::child_cell_on_face()
+ * function. As each child is adjacent to the vertex with the same number
+ * these numbers are also given by the
+ * GeometryInfo<3>::face_to_cell_vertices() function.
+ *
+ * Note that, again, the above list only holds for faces in their standard
+ * orientation. If a face is not in standard orientation, then the children at
+ * positions 1 and 2 (counting from 0 to 3) would be swapped. In fact, this is
+ * what the child_cell_on_face and the face_to_cell_vertices functions of
+ * GeometryInfo<3> do, when invoked with a <tt>face_orientation=false</tt>
+ * argument.
+ *
+ * The information which child cell is at which position of which face is most
+ * often used when computing jump terms across faces with hanging nodes, using
+ * objects of type FESubfaceValues. Sitting on one cell, you would look at a
+ * face and figure out which child of the neighbor is sitting on a given
+ * subface between the present and the neighboring cell. To avoid having to
+ * query the standard orientation of the faces of the two cells every time in
+ * such cases, you should use a function call like
+ * <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>, which returns
+ * the correct result both in 2d (where face orientations are immaterial) and
+ * 3d (where it is necessary to use the face orientation as additional
+ * argument to <tt>GeometryInfo<3>::child_cell_on_face</tt>).
+ *
+ * For anisotropic refinement, the child cells can not be numbered according
+ * to adjacent vertices, thus the following conventions are used:
  * @verbatim
  *            RefinementCase<3>::cut_x
  *
@@ -1466,14 +1289,14 @@ struct GeometryInfo<0>
  * By the convention laid down as above, the vertices have the following
  * coordinates (lexicographic, with x running fastest):
  * <ul>
- *    <li> Vertex 0: <tt>(0,0,0)</tt>;
- *    <li> Vertex 1: <tt>(1,0,0)</tt>;
- *    <li> Vertex 2: <tt>(0,1,0)</tt>;
- *    <li> Vertex 3: <tt>(1,1,0)</tt>;
- *    <li> Vertex 4: <tt>(0,0,1)</tt>;
- *    <li> Vertex 5: <tt>(1,0,1)</tt>;
- *    <li> Vertex 6: <tt>(0,1,1)</tt>;
- *    <li> Vertex 7: <tt>(1,1,1)</tt>.
+ * <li> Vertex 0: <tt>(0,0,0)</tt>;
+ * <li> Vertex 1: <tt>(1,0,0)</tt>;
+ * <li> Vertex 2: <tt>(0,1,0)</tt>;
+ * <li> Vertex 3: <tt>(1,1,0)</tt>;
+ * <li> Vertex 4: <tt>(0,0,1)</tt>;
+ * <li> Vertex 5: <tt>(1,0,1)</tt>;
+ * <li> Vertex 6: <tt>(0,1,1)</tt>;
+ * <li> Vertex 7: <tt>(1,1,1)</tt>.
  * </ul>
  *
  *
@@ -1490,15 +1313,11 @@ struct GeometryInfo
 {
 
   /**
-   * Maximum number of children of
-   * a refined cell, i.e. the
-   * number of children of an
-   * isotropically refined cell.
+   * Maximum number of children of a refined cell, i.e. the number of children
+   * of an isotropically refined cell.
    *
-   * If a cell is refined
-   * anisotropically, the actual
-   * number of children may be less
-   * than the value given here.
+   * If a cell is refined anisotropically, the actual number of children may
+   * be less than the value given here.
    */
   static const unsigned int max_children_per_cell = 1 << dim;
 
@@ -1508,15 +1327,11 @@ struct GeometryInfo
   static const unsigned int faces_per_cell = 2 * dim;
 
   /**
-   * Maximum number of children of
-   * a refined face, i.e. the
-   * number of children of an
-   * isotropically refined face.
+   * Maximum number of children of a refined face, i.e. the number of children
+   * of an isotropically refined face.
    *
-   * If a cell is refined
-   * anisotropically, the actual
-   * number of children may be less
-   * than the value given here.
+   * If a cell is refined anisotropically, the actual number of children may
+   * be less than the value given here.
    */
   static const unsigned int max_children_per_face = GeometryInfo<dim-1>::max_children_per_cell;
 
@@ -1526,8 +1341,7 @@ struct GeometryInfo
   static const unsigned int vertices_per_cell = 1 << dim;
 
   /**
-   * Number of vertices on each
-   * face.
+   * Number of vertices on each face.
    */
   static const unsigned int vertices_per_face = GeometryInfo<dim-1>::vertices_per_cell;
 
@@ -1546,27 +1360,21 @@ struct GeometryInfo
   /**
    * Number of lines of a cell.
    *
-   * The formula to compute this makes use
-   * of the fact that when going from one
-   * dimension to the next, the object of
-   * the lower dimension is copied once
-   * (thus twice the old number of lines)
-   * and then a new line is inserted
-   * between each vertex of the old object
-   * and the corresponding one in the copy.
+   * The formula to compute this makes use of the fact that when going from
+   * one dimension to the next, the object of the lower dimension is copied
+   * once (thus twice the old number of lines) and then a new line is inserted
+   * between each vertex of the old object and the corresponding one in the
+   * copy.
    */
   static const unsigned int lines_per_cell
     = (2*GeometryInfo<dim-1>::lines_per_cell +
        GeometryInfo<dim-1>::vertices_per_cell);
 
   /**
-   * Number of quadrilaterals of a
-   * cell.
+   * Number of quadrilaterals of a cell.
    *
-   * This number is computed recursively
-   * just as the previous one, with the
-   * exception that new quads result from
-   * connecting an original line and its
+   * This number is computed recursively just as the previous one, with the
+   * exception that new quads result from connecting an original line and its
    * copy.
    */
   static const unsigned int quads_per_cell
@@ -1574,54 +1382,38 @@ struct GeometryInfo
        GeometryInfo<dim-1>::lines_per_cell);
 
   /**
-   * Number of hexahedra of a
-   * cell.
+   * Number of hexahedra of a cell.
    */
   static const unsigned int hexes_per_cell
     = (2*GeometryInfo<dim-1>::hexes_per_cell +
        GeometryInfo<dim-1>::quads_per_cell);
 
   /**
-   * Rearrange vertices for UCD
-   * output.  For a cell being
-   * written in UCD format, each
-   * entry in this field contains
-   * the number of a vertex in
-   * <tt>deal.II</tt> that corresponds
-   * to the UCD numbering at this
-   * location.
+   * Rearrange vertices for UCD output.  For a cell being written in UCD
+   * format, each entry in this field contains the number of a vertex in
+   * <tt>deal.II</tt> that corresponds to the UCD numbering at this location.
    *
-   * Typical example: write a cell
-   * and arrange the vertices, such
-   * that UCD understands them.
+   * Typical example: write a cell and arrange the vertices, such that UCD
+   * understands them.
    *
    * @code
    * for (i=0; i< n_vertices; ++i)
    *   out << cell->vertex(ucd_to_deal[i]);
    * @endcode
    *
-   * As the vertex numbering in
-   * deal.II versions <= 5.1
-   * happened to coincide with the
-   * UCD numbering, this field can
-   * also be used like a
+   * As the vertex numbering in deal.II versions <= 5.1 happened to coincide
+   * with the UCD numbering, this field can also be used like a
    * old_to_lexicographic mapping.
    */
   static const unsigned int ucd_to_deal[vertices_per_cell];
 
   /**
-   * Rearrange vertices for OpenDX
-   * output.  For a cell being
-   * written in OpenDX format, each
-   * entry in this field contains
-   * the number of a vertex in
-   * <tt>deal.II</tt> that corresponds
-   * to the DX numbering at this
-   * location.
+   * Rearrange vertices for OpenDX output.  For a cell being written in OpenDX
+   * format, each entry in this field contains the number of a vertex in
+   * <tt>deal.II</tt> that corresponds to the DX numbering at this location.
    *
-   * Typical example: write a cell
-   * and arrange the vertices, such
-   * that OpenDX understands them.
+   * Typical example: write a cell and arrange the vertices, such that OpenDX
+   * understands them.
    *
    * @code
    * for (i=0; i< n_vertices; ++i)
@@ -1631,57 +1423,41 @@ struct GeometryInfo
   static const unsigned int dx_to_deal[vertices_per_cell];
 
   /**
-   * This field stores for each vertex
-   * to which faces it belongs. In any
-   * given dimension, the number of
-   * faces is equal to the dimension.
-   * The first index in this 2D-array
-   * runs over all vertices, the second
-   * index over @p dim faces to which
-   * the vertex belongs.
-  *
-  * The order of the faces for
-  * each vertex is such that the
-  * first listed face bounds the
-  * reference cell in <i>x</i>
-  * direction, the second in
-  * <i>y</i> direction, and so on.
+   * This field stores for each vertex to which faces it belongs. In any given
+   * dimension, the number of faces is equal to the dimension. The first index
+   * in this 2D-array runs over all vertices, the second index over @p dim
+   * faces to which the vertex belongs.
+   *
+   * The order of the faces for each vertex is such that the first listed face
+   * bounds the reference cell in <i>x</i> direction, the second in <i>y</i>
+   * direction, and so on.
    */
   static const unsigned int vertex_to_face[vertices_per_cell][dim];
 
   /**
-   * Return the number of children
-   * of a cell (or face) refined
-   * with <tt>ref_case</tt>.
+   * Return the number of children of a cell (or face) refined with
+   * <tt>ref_case</tt>.
    */
   static
   unsigned int
   n_children(const RefinementCase<dim> &refinement_case);
 
   /**
-   * Return the number of subfaces
-   * of a face refined according to
-   * internal::SubfaceCase
-   * @p face_ref_case.
+   * Return the number of subfaces of a face refined according to
+   * internal::SubfaceCase @p face_ref_case.
    */
   static
   unsigned int
   n_subfaces(const internal::SubfaceCase<dim> &subface_case);
 
   /**
-   * Given a face on the reference
-   * element with a
-   * <code>internal::SubfaceCase@<dim@></code>
-   * @p face_refinement_case this
-   * function returns the ratio
-   * between the area of the @p
-   * subface_no th subface and the
-   * area(=1) of the face.
+   * Given a face on the reference element with a
+   * <code>internal::SubfaceCase@<dim@></code> @p face_refinement_case this
+   * function returns the ratio between the area of the @p subface_no th
+   * subface and the area(=1) of the face.
    *
-   * E.g. for
-   * internal::SubfaceCase::cut_xy
-   * the ratio is 1/4 for each of
-   * the subfaces.
+   * E.g. for internal::SubfaceCase::cut_xy the ratio is 1/4 for each of the
+   * subfaces.
    */
   static
   double
@@ -1689,12 +1465,9 @@ struct GeometryInfo
                 const unsigned int subface_no);
 
   /**
-   * Given a cell refined with the
-   * <code>RefinementCase</code>
-   * @p cell_refinement_case
-   * return the
-   * <code>SubfaceCase</code> of
-   * the @p face_no th face.
+   * Given a cell refined with the <code>RefinementCase</code> @p
+   * cell_refinement_case return the <code>SubfaceCase</code> of the @p
+   * face_no th face.
    */
   static
   RefinementCase<dim-1>
@@ -1705,12 +1478,9 @@ struct GeometryInfo
                         const bool face_rotation    = false);
 
   /**
-   * Given the SubfaceCase @p
-   * face_refinement_case of the @p
-   * face_no th face, return the
-   * smallest RefinementCase of the
-   * cell, which corresponds to
-   * that refinement of the face.
+   * Given the SubfaceCase @p face_refinement_case of the @p face_no th face,
+   * return the smallest RefinementCase of the cell, which corresponds to that
+   * refinement of the face.
    */
   static
   RefinementCase<dim>
@@ -1722,11 +1492,8 @@ struct GeometryInfo
    const bool face_rotation    = false);
 
   /**
-   * Given a cell refined with the
-   * RefinementCase @p
-   * cell_refinement_case return
-   * the RefinementCase of the @p
-   * line_no th face.
+   * Given a cell refined with the RefinementCase @p cell_refinement_case
+   * return the RefinementCase of the @p line_no th face.
    */
   static
   RefinementCase<1>
@@ -1734,23 +1501,18 @@ struct GeometryInfo
                        const unsigned int line_no);
 
   /**
-   * Return the minimal / smallest
-   * RefinementCase of the cell, which
-   * ensures refinement of line
-   * @p line_no.
+   * Return the minimal / smallest RefinementCase of the cell, which ensures
+   * refinement of line @p line_no.
    */
   static
   RefinementCase<dim>
   min_cell_refinement_case_for_line_refinement(const unsigned int line_no);
 
   /**
-   * This field stores which child
-   * cells are adjacent to a
-   * certain face of the mother
-   * cell.
+   * This field stores which child cells are adjacent to a certain face of the
+   * mother cell.
    *
-   * For example, in 2D the layout of
-   * a cell is as follows:
+   * For example, in 2D the layout of a cell is as follows:
    * @verbatim
    * .      3
    * .   2-->--3
@@ -1760,12 +1522,10 @@ struct GeometryInfo
    * .   0-->--1
    * .      2
    * @endverbatim
-   * Vertices and faces are indicated
-   * with their numbers, faces also with
+   * Vertices and faces are indicated with their numbers, faces also with
    * their directions.
    *
-   * Now, when refined, the layout is
-   * like this:
+   * Now, when refined, the layout is like this:
    * @verbatim
    * *--*--*
    * | 2|3 |
@@ -1774,39 +1534,24 @@ struct GeometryInfo
    * *--*--*
    * @endverbatim
    *
-   * Thus, the child cells on face
-   * 0 are (ordered in the
-   * direction of the face) 0 and
-   * 2, on face 3 they are 2 and 3,
-   * etc.
+   * Thus, the child cells on face 0 are (ordered in the direction of the
+   * face) 0 and 2, on face 3 they are 2 and 3, etc.
    *
-   * For three spatial dimensions, the exact
-   * order of the children is laid down in
-   * the general documentation of this
-   * class.
+   * For three spatial dimensions, the exact order of the children is laid
+   * down in the general documentation of this class.
    *
-   * Through the <tt>face_orientation</tt>,
-   * <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> arguments this
-   * function handles faces oriented in the
-   * standard and non-standard orientation.
-   * <tt>face_orientation</tt> defaults to
-   * <tt>true</tt>, <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> default to
-   * <tt>false</tt> (standard orientation)
-   * and has no effect in 2d. The concept of
-   * face orientations is explained in this
-   * @ref GlossFaceOrientation "glossary"
-   * entry.
-   *
-   * In the case of anisotropically refined
-   * cells and faces, the @p RefinementCase of
-   * the face, <tt>face_ref_case</tt>,
-   * might have an influence on
-   * which child is behind which given
-   * subface, thus this is an additional
-   * argument, defaulting to isotropic
-   * refinement of the face.
+   * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+   * <tt>face_rotation</tt> arguments this function handles faces oriented in
+   * the standard and non-standard orientation. <tt>face_orientation</tt>
+   * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+   * default to <tt>false</tt> (standard orientation) and has no effect in 2d.
+   * The concept of face orientations is explained in this @ref
+   * GlossFaceOrientation "glossary" entry.
+   *
+   * In the case of anisotropically refined cells and faces, the @p
+   * RefinementCase of the face, <tt>face_ref_case</tt>, might have an
+   * influence on which child is behind which given subface, thus this is an
+   * additional argument, defaulting to isotropic refinement of the face.
    */
   static
   unsigned int
@@ -1820,25 +1565,17 @@ struct GeometryInfo
                       = RefinementCase<dim-1>::isotropic_refinement);
 
   /**
-   * Map line vertex number to cell
-   * vertex number, i.e. give the
-   * cell vertex number of the
-   * <tt>vertex</tt>th vertex of
-   * line <tt>line</tt>, e.g.
+   * Map line vertex number to cell vertex number, i.e. give the cell vertex
+   * number of the <tt>vertex</tt>th vertex of line <tt>line</tt>, e.g.
    * <tt>GeometryInfo<2>::line_to_cell_vertices(3,0)=2</tt>.
    *
-   * The order of the lines, as well as
-   * their direction (which in turn
-   * determines which is the first and
-   * which the second vertex on a line) is
-   * the canonical one in deal.II, as
-   * described in the general documentation
+   * The order of the lines, as well as their direction (which in turn
+   * determines which is the first and which the second vertex on a line) is
+   * the canonical one in deal.II, as described in the general documentation
    * of this class.
    *
-   * For <tt>dim=2</tt> this call
-   * is simply passed down to the
-   * face_to_cell_vertices()
-   * function.
+   * For <tt>dim=2</tt> this call is simply passed down to the
+   * face_to_cell_vertices() function.
    */
   static
   unsigned int
@@ -1846,37 +1583,22 @@ struct GeometryInfo
                          const unsigned int vertex);
 
   /**
-   * Map face vertex number to cell
-   * vertex number, i.e. give the
-   * cell vertex number of the
-   * <tt>vertex</tt>th vertex of
-   * face <tt>face</tt>, e.g.
-   * <tt>GeometryInfo<2>::face_to_cell_vertices(3,0)=2</tt>,
-   * see the image under point N4
-   * in the 2d section of this
-   * class's documentation.
-   *
-   * Through the <tt>face_orientation</tt>,
-   * <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> arguments this
-   * function handles faces oriented in the
-   * standard and non-standard orientation.
-   * <tt>face_orientation</tt> defaults to
-   * <tt>true</tt>, <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> default to
-   * <tt>false</tt> (standard orientation).
-   * In 2d only <tt>face_flip</tt> is considered.
-   * See this @ref GlossFaceOrientation "glossary"
-   * article for more information.
-   *
-   * As the children of a cell are
-   * ordered according to the
-   * vertices of the cell, this
-   * call is passed down to the
-   * child_cell_on_face() function.
-   * Hence this function is simply
-   * a wrapper of
-   * child_cell_on_face() giving it
+   * Map face vertex number to cell vertex number, i.e. give the cell vertex
+   * number of the <tt>vertex</tt>th vertex of face <tt>face</tt>, e.g.
+   * <tt>GeometryInfo<2>::face_to_cell_vertices(3,0)=2</tt>, see the image
+   * under point N4 in the 2d section of this class's documentation.
+   *
+   * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+   * <tt>face_rotation</tt> arguments this function handles faces oriented in
+   * the standard and non-standard orientation. <tt>face_orientation</tt>
+   * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+   * default to <tt>false</tt> (standard orientation). In 2d only
+   * <tt>face_flip</tt> is considered. See this @ref GlossFaceOrientation
+   * "glossary" article for more information.
+   *
+   * As the children of a cell are ordered according to the vertices of the
+   * cell, this call is passed down to the child_cell_on_face() function.
+   * Hence this function is simply a wrapper of child_cell_on_face() giving it
    * a suggestive name.
    */
   static
@@ -1888,23 +1610,15 @@ struct GeometryInfo
                          const bool face_rotation    = false);
 
   /**
-   * Map face line number to cell
-   * line number, i.e. give the
-   * cell line number of the
-   * <tt>line</tt>th line of face
-   * <tt>face</tt>, e.g.
+   * Map face line number to cell line number, i.e. give the cell line number
+   * of the <tt>line</tt>th line of face <tt>face</tt>, e.g.
    * <tt>GeometryInfo<3>::face_to_cell_lines(5,0)=4</tt>.
    *
-   * Through the <tt>face_orientation</tt>,
-   * <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> arguments this
-   * function handles faces oriented in the
-   * standard and non-standard orientation.
-   * <tt>face_orientation</tt> defaults to
-   * <tt>true</tt>, <tt>face_flip</tt> and
-   * <tt>face_rotation</tt> default to
-   * <tt>false</tt> (standard orientation)
-   * and has no effect in 2d.
+   * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+   * <tt>face_rotation</tt> arguments this function handles faces oriented in
+   * the standard and non-standard orientation. <tt>face_orientation</tt>
+   * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+   * default to <tt>false</tt> (standard orientation) and has no effect in 2d.
    */
   static
   unsigned int
@@ -1915,15 +1629,11 @@ struct GeometryInfo
                       const bool face_rotation    = false);
 
   /**
-   * Map the vertex index @p vertex of a face
-   * in standard orientation to one of a face
-   * with arbitrary @p face_orientation, @p
-   * face_flip and @p face_rotation. The
-   * values of these three flags default to
-   * <tt>true</tt>, <tt>false</tt> and
-   * <tt>false</tt>, respectively. this
-   * combination describes a face in standard
-   * orientation.
+   * Map the vertex index @p vertex of a face in standard orientation to one
+   * of a face with arbitrary @p face_orientation, @p face_flip and @p
+   * face_rotation. The values of these three flags default to <tt>true</tt>,
+   * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+   * describes a face in standard orientation.
    *
    * This function is only implemented in 3D.
    */
@@ -1935,15 +1645,11 @@ struct GeometryInfo
                                 const bool face_rotation    = false);
 
   /**
-   * Map the vertex index @p vertex of a face
-   * with arbitrary @p face_orientation, @p
-   * face_flip and @p face_rotation to a face
-   * in standard orientation. The values of
-   * these three flags default to
-   * <tt>true</tt>, <tt>false</tt> and
-   * <tt>false</tt>, respectively. this
-   * combination describes a face in standard
-   * orientation.
+   * Map the vertex index @p vertex of a face with arbitrary @p
+   * face_orientation, @p face_flip and @p face_rotation to a face in standard
+   * orientation. The values of these three flags default to <tt>true</tt>,
+   * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+   * describes a face in standard orientation.
    *
    * This function is only implemented in 3D.
    */
@@ -1955,15 +1661,11 @@ struct GeometryInfo
                                 const bool face_rotation    = false);
 
   /**
-   * Map the line index @p line of a face
-   * in standard orientation to one of a face
-   * with arbitrary @p face_orientation, @p
-   * face_flip and @p face_rotation. The
-   * values of these three flags default to
-   * <tt>true</tt>, <tt>false</tt> and
-   * <tt>false</tt>, respectively. this
-   * combination describes a face in standard
-   * orientation.
+   * Map the line index @p line of a face in standard orientation to one of a
+   * face with arbitrary @p face_orientation, @p face_flip and @p
+   * face_rotation. The values of these three flags default to <tt>true</tt>,
+   * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+   * describes a face in standard orientation.
    *
    * This function is only implemented in 3D.
    */
@@ -1975,15 +1677,11 @@ struct GeometryInfo
                               const bool face_rotation    = false);
 
   /**
-   * Map the line index @p line of a face
-   * with arbitrary @p face_orientation, @p
-   * face_flip and @p face_rotation to a face
-   * in standard orientation. The values of
-   * these three flags default to
-   * <tt>true</tt>, <tt>false</tt> and
-   * <tt>false</tt>, respectively. this
-   * combination describes a face in standard
-   * orientation.
+   * Map the line index @p line of a face with arbitrary @p face_orientation,
+   * @p face_flip and @p face_rotation to a face in standard orientation. The
+   * values of these three flags default to <tt>true</tt>, <tt>false</tt> and
+   * <tt>false</tt>, respectively. this combination describes a face in
+   * standard orientation.
    *
    * This function is only implemented in 3D.
    */
@@ -1995,10 +1693,8 @@ struct GeometryInfo
                               const bool face_rotation    = false);
 
   /**
-   * Return the position of the @p ith
-   * vertex on the unit cell. The order of
-   * vertices is the canonical one in
-   * deal.II, as described in the general
+   * Return the position of the @p ith vertex on the unit cell. The order of
+   * vertices is the canonical one in deal.II, as described in the general
    * documentation of this class.
    */
   static
@@ -2006,18 +1702,12 @@ struct GeometryInfo
   unit_cell_vertex (const unsigned int vertex);
 
   /**
-   * Given a point @p p in unit
-   * coordinates, return the number
-   * of the child cell in which it
-   * would lie in. If the point
-   * lies on the interface of two
-   * children, return any one of
-   * their indices. The result is
-   * always less than
+   * Given a point @p p in unit coordinates, return the number of the child
+   * cell in which it would lie in. If the point lies on the interface of two
+   * children, return any one of their indices. The result is always less than
    * GeometryInfo<dimension>::max_children_per_cell.
    *
-   * The order of child cells is described
-   * the general documentation of this
+   * The order of child cells is described the general documentation of this
    * class.
    */
   static
@@ -2025,18 +1715,11 @@ struct GeometryInfo
   child_cell_from_point (const Point<dim> &p);
 
   /**
-   * Given coordinates @p p on the
-   * unit cell, return the values
-   * of the coordinates of this
-   * point in the coordinate system
-   * of the given child. Neither
-   * original nor returned
-   * coordinates need actually be
-   * inside the cell, we simply
-   * perform a scale-and-shift
-   * operation with a shift that
-   * depends on the number of the
-   * child.
+   * Given coordinates @p p on the unit cell, return the values of the
+   * coordinates of this point in the coordinate system of the given child.
+   * Neither original nor returned coordinates need actually be inside the
+   * cell, we simply perform a scale-and-shift operation with a shift that
+   * depends on the number of the child.
    */
   static
   Point<dim>
@@ -2046,11 +1729,8 @@ struct GeometryInfo
                              = RefinementCase<dim>::isotropic_refinement);
 
   /**
-   * The reverse function to the
-   * one above: take a point in the
-   * coordinate system of the
-   * child, and transform it to the
-   * coordinate system of the
+   * The reverse function to the one above: take a point in the coordinate
+   * system of the child, and transform it to the coordinate system of the
    * mother cell.
    */
   static
@@ -2061,35 +1741,23 @@ struct GeometryInfo
                              = RefinementCase<dim>::isotropic_refinement);
 
   /**
-   * Return true if the given point
-   * is inside the unit cell of the
-   * present space dimension.
+   * Return true if the given point is inside the unit cell of the present
+   * space dimension.
    */
   static
   bool
   is_inside_unit_cell (const Point<dim> &p);
 
   /**
-   * Return true if the given point
-   * is inside the unit cell of the
-   * present space dimension. This
-   * * function accepts an
-   * additional * parameter which
-   * specifies how * much the point
-   * position may * actually be
-   * outside the true * unit
-   * cell. This is useful because
-   * in practice we may often not
-   * be able to compute the
-   * coordinates of a point in
-   * reference coordinates exactly,
-   * but only up to numerical
-   * roundoff.
-   *
-   * The tolerance parameter may be
-   * less than zero, indicating
-   * that the point should be
-   * safely inside the cell.
+   * Return true if the given point is inside the unit cell of the present
+   * space dimension. This * function accepts an additional * parameter which
+   * specifies how * much the point position may * actually be outside the
+   * true * unit cell. This is useful because in practice we may often not be
+   * able to compute the coordinates of a point in reference coordinates
+   * exactly, but only up to numerical roundoff.
+   *
+   * The tolerance parameter may be less than zero, indicating that the point
+   * should be safely inside the cell.
    */
   static
   bool
@@ -2097,31 +1765,25 @@ struct GeometryInfo
                        const double eps);
 
   /**
-   * Projects a given point onto the
-   * unit cell, i.e. each coordinate
-   * outside [0..1] is modified
-   * to lie within that interval.
+   * Projects a given point onto the unit cell, i.e. each coordinate outside
+   * [0..1] is modified to lie within that interval.
    */
   static
   Point<dim>
   project_to_unit_cell (const Point<dim> &p);
 
   /**
-   * Returns the infinity norm of
-   * the vector between a given point @p p
-   * outside the unit cell to the closest
-   * unit cell boundary.
-   * For points inside the cell, this is
-   * defined as zero.
+   * Returns the infinity norm of the vector between a given point @p p
+   * outside the unit cell to the closest unit cell boundary. For points
+   * inside the cell, this is defined as zero.
    */
   static
   double
   distance_to_unit_cell (const Point<dim> &p);
 
   /**
-   * Compute the value of the $i$-th
-   * $d$-linear (i.e. (bi-,tri-)linear)
-   * shape function at location $\xi$.
+   * Compute the value of the $i$-th $d$-linear (i.e. (bi-,tri-)linear) shape
+   * function at location $\xi$.
    */
   static
   double
@@ -2129,8 +1791,7 @@ struct GeometryInfo
                            const unsigned int i);
 
   /**
-   * Compute the gradient of the $i$-th
-   * $d$-linear (i.e. (bi-,tri-)linear)
+   * Compute the gradient of the $i$-th $d$-linear (i.e. (bi-,tri-)linear)
    * shape function at location $\xi$.
    */
   static
@@ -2139,100 +1800,53 @@ struct GeometryInfo
                                     const unsigned int i);
 
   /**
-   * For a (bi-, tri-)linear
-   * mapping from the reference
-   * cell, face, or edge to the
-   * object specified by the given
-   * vertices, compute the
-   * alternating form of the
-   * transformed unit vectors
-   * vertices. For an object of
-   * dimensionality @p dim, there
-   * are @p dim vectors with @p
-   * spacedim components each, and
-   * the alternating form is a
-   * tensor of rank spacedim-dim
-   * that corresponds to the wedge
-   * product of the @p dim unit
-   * vectors, and it corresponds to
-   * the volume and normal vectors
-   * of the mapping from reference
-   * element to the element
-   * described by the vertices.
-   *
-   * For example, if dim==spacedim==2, then
-   * the alternating form is a scalar
-   * (because spacedim-dim=0) and its value
-   * equals $\mathbf v_1\wedge \mathbf
-   * v_2=\mathbf v_1^\perp \cdot\mathbf
-   * v_2$, where $\mathbf v_1^\perp$ is a
-   * vector that is rotated to the right by
-   * 90 degrees from $\mathbf v_1$. If
-   * dim==spacedim==3, then the result is
-   * again a scalar with value $\mathbf
-   * v_1\wedge \mathbf v_2 \wedge \mathbf
-   * v_3 = (\mathbf v_1\times \mathbf
-   * v_2)\cdot \mathbf v_3$, where $\mathbf
-   * v_1, \mathbf v_2, \mathbf v_3$ are the
-   * images of the unit vectors at a vertex
-   * of the unit dim-dimensional cell under
-   * transformation to the dim-dimensional
-   * cell in spacedim-dimensional space. In
-   * both cases, i.e. for dim==2 or 3, the
-   * result happens to equal the
-   * determinant of the Jacobian of the
-   * mapping from reference cell to cell in
-   * real space. Note that it is the actual
-   * determinant, not its absolute value as
-   * often used in transforming integrals
-   * from one coordinate system to
-   * another. In particular, if the object
-   * specified by the vertices is a
-   * parallelogram (i.e. a linear
-   * transformation of the reference cell)
-   * then the computed values are the same
-   * at all vertices and equal the (signed)
-   * area of the cell; similarly, for
-   * parallel-epipeds, it is the volume of
-   * the cell.
-   *
-   * Likewise, if we have dim==spacedim-1
-   * (e.g. we have a quad in 3d space, or a
-   * line in 2d), then the alternating
-   * product denotes the normal vector
-   * (i.e. a rank-1 tensor, since
-   * spacedim-dim=1) to the object at each
-   * vertex, where the normal vector's
-   * magnitude denotes the area element of
-   * the transformation from the reference
-   * object to the object given by the
-   * vertices. In particular, if again the
-   * mapping from reference object to the
-   * object under consideration here is
-   * linear (not bi- or trilinear), then
-   * the returned vectors are all
-   * %parallel, perpendicular to the mapped
-   * object described by the vertices, and
-   * have a magnitude equal to the
-   * area/volume of the mapped object. If
-   * dim=1, spacedim=2, then the returned
-   * value is $\mathbf v_1^\perp$, where
-   * $\mathbf v_1$ is the image of the sole
-   * unit vector of a line mapped to the
-   * line in 2d given by the vertices; if
-   * dim=2, spacedim=3, then the returned
-   * values are $\mathbf v_1 \wedge \mathbf
-   * v_2=\mathbf v_1 \times \mathbf v_2$
-   * where $\mathbf v_1,\mathbf v_2$ are
-   * the two three-dimensional vectors that
-   * are tangential to the quad mapped into
-   * three-dimensional space.
-   *
-   * This function is used in order to
-   * determine how distorted a cell is (see
-   * the entry on
-   * @ref GlossDistorted "distorted cells"
-   * in the glossary).
+   * For a (bi-, tri-)linear mapping from the reference cell, face, or edge to
+   * the object specified by the given vertices, compute the alternating form
+   * of the transformed unit vectors vertices. For an object of dimensionality
+   * @p dim, there are @p dim vectors with @p spacedim components each, and
+   * the alternating form is a tensor of rank spacedim-dim that corresponds to
+   * the wedge product of the @p dim unit vectors, and it corresponds to the
+   * volume and normal vectors of the mapping from reference element to the
+   * element described by the vertices.
+   *
+   * For example, if dim==spacedim==2, then the alternating form is a scalar
+   * (because spacedim-dim=0) and its value equals $\mathbf v_1\wedge \mathbf
+   * v_2=\mathbf v_1^\perp \cdot\mathbf v_2$, where $\mathbf v_1^\perp$ is a
+   * vector that is rotated to the right by 90 degrees from $\mathbf v_1$. If
+   * dim==spacedim==3, then the result is again a scalar with value $\mathbf
+   * v_1\wedge \mathbf v_2 \wedge \mathbf v_3 = (\mathbf v_1\times \mathbf
+   * v_2)\cdot \mathbf v_3$, where $\mathbf v_1, \mathbf v_2, \mathbf v_3$ are
+   * the images of the unit vectors at a vertex of the unit dim-dimensional
+   * cell under transformation to the dim-dimensional cell in spacedim-
+   * dimensional space. In both cases, i.e. for dim==2 or 3, the result
+   * happens to equal the determinant of the Jacobian of the mapping from
+   * reference cell to cell in real space. Note that it is the actual
+   * determinant, not its absolute value as often used in transforming
+   * integrals from one coordinate system to another. In particular, if the
+   * object specified by the vertices is a parallelogram (i.e. a linear
+   * transformation of the reference cell) then the computed values are the
+   * same at all vertices and equal the (signed) area of the cell; similarly,
+   * for parallel-epipeds, it is the volume of the cell.
+   *
+   * Likewise, if we have dim==spacedim-1 (e.g. we have a quad in 3d space, or
+   * a line in 2d), then the alternating product denotes the normal vector
+   * (i.e. a rank-1 tensor, since spacedim-dim=1) to the object at each
+   * vertex, where the normal vector's magnitude denotes the area element of
+   * the transformation from the reference object to the object given by the
+   * vertices. In particular, if again the mapping from reference object to
+   * the object under consideration here is linear (not bi- or trilinear),
+   * then the returned vectors are all %parallel, perpendicular to the mapped
+   * object described by the vertices, and have a magnitude equal to the
+   * area/volume of the mapped object. If dim=1, spacedim=2, then the returned
+   * value is $\mathbf v_1^\perp$, where $\mathbf v_1$ is the image of the
+   * sole unit vector of a line mapped to the line in 2d given by the
+   * vertices; if dim=2, spacedim=3, then the returned values are $\mathbf v_1
+   * \wedge \mathbf v_2=\mathbf v_1 \times \mathbf v_2$ where $\mathbf
+   * v_1,\mathbf v_2$ are the two three-dimensional vectors that are
+   * tangential to the quad mapped into three-dimensional space.
+   *
+   * This function is used in order to determine how distorted a cell is (see
+   * the entry on @ref GlossDistorted "distorted cells" in the glossary).
    */
   template <int spacedim>
   static void
@@ -2246,63 +1860,37 @@ struct GeometryInfo
 #endif
 
   /**
-   * For each face of the reference
-   * cell, this field stores the
-   * coordinate direction in which
-   * its normal vector points. In
-   * <tt>dim</tt> dimension these
-   * are the <tt>2*dim</tt> first
-   * entries of
-   * <tt>{0,0,1,1,2,2,3,3}</tt>.
+   * For each face of the reference cell, this field stores the coordinate
+   * direction in which its normal vector points. In <tt>dim</tt> dimension
+   * these are the <tt>2*dim</tt> first entries of <tt>{0,0,1,1,2,2,3,3}</tt>.
    *
-   * Note that this is only the
-   * coordinate number. The actual
-   * direction of the normal vector
-   * is obtained by multiplying the
-   * unit vector in this direction
-   * with #unit_normal_orientation.
+   * Note that this is only the coordinate number. The actual direction of the
+   * normal vector is obtained by multiplying the unit vector in this
+   * direction with #unit_normal_orientation.
    */
   static const unsigned int unit_normal_direction[faces_per_cell];
 
   /**
-   * Orientation of the unit normal
-   * vector of a face of the
-   * reference cell. In
-   * <tt>dim</tt> dimension these
-   * are the <tt>2*dim</tt> first
-   * entries of
+   * Orientation of the unit normal vector of a face of the reference cell. In
+   * <tt>dim</tt> dimension these are the <tt>2*dim</tt> first entries of
    * <tt>{-1,1,-1,1,-1,1,-1,1}</tt>.
    *
-   * Each value is either
-   * <tt>1</tt> or <tt>-1</tt>,
-   * corresponding to a normal
-   * vector pointing in the
-   * positive or negative
-   * coordinate direction,
+   * Each value is either <tt>1</tt> or <tt>-1</tt>, corresponding to a normal
+   * vector pointing in the positive or negative coordinate direction,
    * respectively.
    *
-   * Note that this is only the
-   * <em>standard orientation</em>
-   * of faces. At least in 3d,
-   * actual faces of cells in a
-   * triangulation can also have
-   * the opposite orientation,
-   * depending on a flag that one
-   * can query from the cell it
-   * belongs to. For more
-   * information, see the
-   * @ref GlossFaceOrientation "glossary"
-   * entry on
-   * face orientation.
+   * Note that this is only the <em>standard orientation</em> of faces. At
+   * least in 3d, actual faces of cells in a triangulation can also have the
+   * opposite orientation, depending on a flag that one can query from the
+   * cell it belongs to. For more information, see the @ref
+   * GlossFaceOrientation "glossary" entry on face orientation.
    */
   static const int unit_normal_orientation[faces_per_cell];
 
   /**
-   * List of numbers which denotes which
-   * face is opposite to a given face. Its
-   * entries are the first <tt>2*dim</tt>
-   * entries of
-   * <tt>{ 1, 0, 3, 2, 5, 4, 7, 6}</tt>.
+   * List of numbers which denotes which face is opposite to a given face. Its
+   * entries are the first <tt>2*dim</tt> entries of <tt>{ 1, 0, 3, 2, 5, 4,
+   * 7, 6}</tt>.
    */
   static const unsigned int opposite_face[faces_per_cell];
 
index 124dff011567395a72c012631390f7e42b3dae8c..fa68060fc0c888428ee6de7aaf8b6fcf7e0f362c 100644 (file)
@@ -39,11 +39,11 @@ namespace GraphColoring
   {
     /**
      * Given two sets of indices that are assumed to be sorted, determine
-     * whether they will have a nonempty intersection. The actual intersection is
-     * not computed.
+     * whether they will have a nonempty intersection. The actual intersection
+     * is not computed.
      * @param indices1 A set of indices, assumed sorted.
-     * @param indices2 A set of indices, assumed sorted.
-     * @return Whether the two sets of indices do have a nonempty intersection.
+     * @param indices2 A set of indices, assumed sorted. @return Whether the
+     * two sets of indices do have a nonempty intersection.
      */
     inline
     bool
@@ -74,32 +74,32 @@ namespace GraphColoring
 
 
     /**
-     * Create a partitioning of the given range of iterators using a simplified
-     * version of the Cuthill-McKee algorithm (Breadth First Search algorithm).
-     * The function creates partitions that contain "zones" of iterators
-     * where the first partition contains the first iterator, the second
-     * zone contains all those iterators that have conflicts with the single
-     * element in the first zone, the third zone contains those iterators that
-     * have conflicts with the iterators of the second zone and have not previously
-     * been assigned to a zone, etc. If the iterators represent cells, then this
-     * generates partitions that are like onion shells around the very first
-     * cell. Note that elements in each zone may conflict with other elements in
-     * the same zone.
+     * Create a partitioning of the given range of iterators using a
+     * simplified version of the Cuthill-McKee algorithm (Breadth First Search
+     * algorithm). The function creates partitions that contain "zones" of
+     * iterators where the first partition contains the first iterator, the
+     * second zone contains all those iterators that have conflicts with the
+     * single element in the first zone, the third zone contains those
+     * iterators that have conflicts with the iterators of the second zone and
+     * have not previously been assigned to a zone, etc. If the iterators
+     * represent cells, then this generates partitions that are like onion
+     * shells around the very first cell. Note that elements in each zone may
+     * conflict with other elements in the same zone.
      *
-     * The question whether two iterators conflict is determined by a user-provided
-     * function. The meaning of this function is discussed in the documentation of
-     * the GraphColoring::make_graph_coloring() function.
+     * The question whether two iterators conflict is determined by a user-
+     * provided function. The meaning of this function is discussed in the
+     * documentation of the GraphColoring::make_graph_coloring() function.
      *
      * @param[in] begin The first element of a range of iterators for which a
-     *      partitioning is sought.
+     * partitioning is sought.
      * @param[in] end The element past the end of the range of iterators.
-     * @param[in] get_conflict_indices A user defined function object returning
-     *      a set of indicators that are descriptive of what represents a
-     *      conflict. See above for a more thorough discussion.
-     * @return A set of sets of iterators (where sets are represented by
-     *      std::vector for efficiency). Each element of the outermost set
-     *      corresponds to the iterators pointing to objects that are in the
-     *      same partition (i.e., the same zone).
+     * @param[in] get_conflict_indices A user defined function object
+     * returning a set of indicators that are descriptive of what represents a
+     * conflict. See above for a more thorough discussion. @return A set of
+     * sets of iterators (where sets are represented by std::vector for
+     * efficiency). Each element of the outermost set corresponds to the
+     * iterators pointing to objects that are in the same partition (i.e., the
+     * same zone).
      *
      * @author Martin Kronbichler, Bruno Turcksin
      */
@@ -189,23 +189,22 @@ namespace GraphColoring
 
     /**
      * This function uses DSATUR (Degree SATURation) to color the elements of
-     * a set. DSATUR works as follows:
-     *   -# Arrange the vertices by decreasing order of degrees.
-     *   -# Color a vertex of maximal degree with color 1.
-     *   -# Choose a vertex with a maximal saturation degree. If there is equality,
-     *      choose any vertex of maximal degree in the uncolored subgraph.
-     *   -# Color the chosen vertex with the least possible (lowest numbered) color.
-     *   -# If all the vertices are colored, stop. Otherwise, return to 3.
+     * a set. DSATUR works as follows: -# Arrange the vertices by decreasing
+     * order of degrees. -# Color a vertex of maximal degree with color 1. -#
+     * Choose a vertex with a maximal saturation degree. If there is equality,
+     * choose any vertex of maximal degree in the uncolored subgraph. -# Color
+     * the chosen vertex with the least possible (lowest numbered) color. -#
+     * If all the vertices are colored, stop. Otherwise, return to 3.
      *
      * @param[in] partition The set of iterators that should be colored.
-     * @param[in] get_conflict_indices A user defined function object returning
-     *      a set of indicators that are descriptive of what represents a
-     *      conflict. See above for a more thorough discussion.
-     * @param[out] partition_coloring A set of sets of iterators (where sets are represented by
-     *      std::vector for efficiency). Each element of the outermost set
-     *      corresponds to the iterators pointing to objects that are in the
-     *      same partition (have the same color) and consequently do not
-     *      conflict. The elements of different sets may conflict.
+     * @param[in] get_conflict_indices A user defined function object
+     * returning a set of indicators that are descriptive of what represents a
+     * conflict. See above for a more thorough discussion.
+     * @param[out] partition_coloring A set of sets of iterators (where sets
+     * are represented by std::vector for efficiency). Each element of the
+     * outermost set corresponds to the iterators pointing to objects that are
+     * in the same partition (have the same color) and consequently do not
+     * conflict. The elements of different sets may conflict.
      */
     template <typename Iterator>
     void
@@ -299,12 +298,13 @@ namespace GraphColoring
 
 
     /**
-     * Given a partition-coloring graph, i.e., a set of zones (partitions) each
-     * of which is colored, produce a combined coloring for the entire set of
-     * iterators. This is possible because any color on an
-     * even (resp. odd) zone does not conflict with any color of any other even
-     * (resp. odd) zone. Consequently, we can combine colors from all even and all
-     * odd zones. This function tries to create colors of similar number of elements.
+     * Given a partition-coloring graph, i.e., a set of zones (partitions)
+     * each of which is colored, produce a combined coloring for the entire
+     * set of iterators. This is possible because any color on an even (resp.
+     * odd) zone does not conflict with any color of any other even (resp.
+     * odd) zone. Consequently, we can combine colors from all even and all
+     * odd zones. This function tries to create colors of similar number of
+     * elements.
      */
     template <typename Iterator>
     std::vector<std::vector<Iterator> >
@@ -431,57 +431,59 @@ namespace GraphColoring
 
 
   /**
-   * Create a partitioning of the given range of iterators so that
-   * iterators that point to conflicting objects will be placed
-   * into different partitions, where the question whether two objects conflict
-   * is determined by a user-provided function.
+   * Create a partitioning of the given range of iterators so that iterators
+   * that point to conflicting objects will be placed into different
+   * partitions, where the question whether two objects conflict is determined
+   * by a user-provided function.
    *
    * This function can also be considered as a graph coloring: each object
-   * pointed to by an iterator is considered to be a node and there is an
-   * edge between each two nodes that conflict. The graph coloring algorithm
-   * then assigns a color to each node in such a way that two nodes connected
-   * by an edge do not have the same color.
+   * pointed to by an iterator is considered to be a node and there is an edge
+   * between each two nodes that conflict. The graph coloring algorithm then
+   * assigns a color to each node in such a way that two nodes connected by an
+   * edge do not have the same color.
    *
-   * A typical use case for this function is in assembling a matrix in parallel.
-   * There, one would like to assemble local contributions on different cells
-   * at the same time (an operation that is purely local and so requires
-   * no synchronization) but then we need to add these local contributions
-   * to the global matrix. In general, the contributions from different cells
-   * may be to the same matrix entries if the cells share degrees of freedom
-   * and, consequently, can not happen at the same time unless we want to
-   * risk a race condition (see http://en.wikipedia.org/wiki/Race_condition ).
-   * Thus, we call these two cells in conflict, and we can only allow operations
-   * in parallel from cells that do not conflict. In other words, two cells
-   * are in conflict if the set of matrix entries (for example characterized
-   * by the rows) have a nonempty intersection.
+   * A typical use case for this function is in assembling a matrix in
+   * parallel. There, one would like to assemble local contributions on
+   * different cells at the same time (an operation that is purely local and
+   * so requires no synchronization) but then we need to add these local
+   * contributions to the global matrix. In general, the contributions from
+   * different cells may be to the same matrix entries if the cells share
+   * degrees of freedom and, consequently, can not happen at the same time
+   * unless we want to risk a race condition (see
+   * http://en.wikipedia.org/wiki/Race_condition ). Thus, we call these two
+   * cells in conflict, and we can only allow operations in parallel from
+   * cells that do not conflict. In other words, two cells are in conflict if
+   * the set of matrix entries (for example characterized by the rows) have a
+   * nonempty intersection.
    *
-   * In this generality, computing the graph of conflicts would require calling
-   * a function that determines whether two iterators (or the two objects they
-   * represent) conflict, and calling it for every pair of iterators, i.e.,
-   * $\frac 12 N (N-1)$ times. This is too expensive in general. A better
-   * approach is to require a user-defined function that returns for every
-   * iterator it is called for a set of indicators of some kind that characterize
-   * a conflict; two iterators are in conflict if their conflict indicator sets
-   * have a nonempty intersection. In the example of assembling a matrix,
-   * the conflict indicator set would contain the indices of all degrees of
-   * freedom on the cell pointed to (in the case of continuous Galerkin methods)
-   * or the union of indices of degree of freedom on the current cell and all
-   * cells adjacent to the faces of the current cell (in the case of
-   * discontinuous Galerkin methods, because there one computes face integrals
-   * coupling the degrees of freedom connected by a common face -- see step-12).
+   * In this generality, computing the graph of conflicts would require
+   * calling a function that determines whether two iterators (or the two
+   * objects they represent) conflict, and calling it for every pair of
+   * iterators, i.e., $\frac 12 N (N-1)$ times. This is too expensive in
+   * general. A better approach is to require a user-defined function that
+   * returns for every iterator it is called for a set of indicators of some
+   * kind that characterize a conflict; two iterators are in conflict if their
+   * conflict indicator sets have a nonempty intersection. In the example of
+   * assembling a matrix, the conflict indicator set would contain the indices
+   * of all degrees of freedom on the cell pointed to (in the case of
+   * continuous Galerkin methods) or the union of indices of degree of freedom
+   * on the current cell and all cells adjacent to the faces of the current
+   * cell (in the case of discontinuous Galerkin methods, because there one
+   * computes face integrals coupling the degrees of freedom connected by a
+   * common face -- see step-12).
    *
    * @note The conflict set returned by the user defined function passed as
-   * third argument needs to accurately describe <i>all</i> degrees of
-   * freedom for which anything is written into the matrix or right hand side.
-   * In other words, if the writing happens through a function like
-   * ConstraintMatrix::copy_local_to_global(), then the set of conflict indices
-   * must actually contain not only the degrees of freedom on the current
-   * cell, but also those they are linked to by constraints such as hanging
-   * nodes.
+   * third argument needs to accurately describe <i>all</i> degrees of freedom
+   * for which anything is written into the matrix or right hand side. In
+   * other words, if the writing happens through a function like
+   * ConstraintMatrix::copy_local_to_global(), then the set of conflict
+   * indices must actually contain not only the degrees of freedom on the
+   * current cell, but also those they are linked to by constraints such as
+   * hanging nodes.
    *
-   * In other situations, the conflict indicator sets may represent
-   * something different altogether -- it is up to the caller of this function
-   * to describe what it means for two iterators to conflict. Given this,
+   * In other situations, the conflict indicator sets may represent something
+   * different altogether -- it is up to the caller of this function to
+   * describe what it means for two iterators to conflict. Given this,
    * computing conflict graph edges can be done significantly more cheaply
    * than with ${\cal O}(N^2)$ operations.
    *
@@ -493,16 +495,16 @@ namespace GraphColoring
    * Turcksin, Kronbichler and Bangerth, see @ref workstream_paper .
    *
    * @param[in] begin The first element of a range of iterators for which a
-   *      coloring is sought.
+   * coloring is sought.
    * @param[in] end The element past the end of the range of iterators.
    * @param[in] get_conflict_indices A user defined function object returning
-   *      a set of indicators that are descriptive of what represents a
-   *      conflict. See above for a more thorough discussion.
-   * @return A set of sets of iterators (where sets are represented by
-   *      std::vector for efficiency). Each element of the outermost set
-   *      corresponds to the iterators pointing to objects that are in the
-   *      same partition (have the same color) and consequently do not
-   *      conflict. The elements of different sets may conflict.
+   * a set of indicators that are descriptive of what represents a conflict.
+   * See above for a more thorough discussion. @return A set of sets of
+   * iterators (where sets are represented by std::vector for efficiency).
+   * Each element of the outermost set corresponds to the iterators pointing
+   * to objects that are in the same partition (have the same color) and
+   * consequently do not conflict. The elements of different sets may
+   * conflict.
    *
    * @author Martin Kronbichler, Bruno Turcksin
    */
index c34e79a37c35cc6ccf42ae3201f64e3e318382de..cab8e7081d0bbc3b3f48eb8a0b108c8196a0bad5 100644 (file)
@@ -39,17 +39,16 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * A class that represents a subset of indices among a larger set. For
- * example, it can be used to denote the set of degrees of freedom
- * within the range $[0,\text{dof\_handler.n\_dofs})$ that belongs to
- * a particular subdomain, or those among all degrees of freedom that
- * are stored on a particular processor in a distributed parallel
- * computation.
+ * example, it can be used to denote the set of degrees of freedom within the
+ * range $[0,\text{dof\_handler.n\_dofs})$ that belongs to a particular
+ * subdomain, or those among all degrees of freedom that are stored on a
+ * particular processor in a distributed parallel computation.
  *
- * This class can represent a collection of half-open ranges of
- * indices as well as individual elements. For practical purposes it
- * also stores the overall range these indices can assume. In other
- * words, you need to specify the size of the index space
- * $[0,\text{size})$ of which objects of this class are a subset.
+ * This class can represent a collection of half-open ranges of indices as
+ * well as individual elements. For practical purposes it also stores the
+ * overall range these indices can assume. In other words, you need to specify
+ * the size of the index space $[0,\text{size})$ of which objects of this
+ * class are a subset.
  *
  * The data structures used in this class along with a rationale can be found
  * in the @ref distributed_paper "Distributed Computing paper".
@@ -319,8 +318,8 @@ public:
                   << " is not an element of this set.");
 
   /**
-   * Write or read the data of this object to or
-   * from a stream for the purpose of serialization
+   * Write or read the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize (Archive &ar, const unsigned int version);
@@ -342,22 +341,22 @@ private:
     types::global_dof_index nth_index_in_set;
 
     /**
-     * Default constructor. Since there is no useful choice for
-     * a default constructed interval, this constructor simply
-     * creates something that resembles an invalid range. We
-     * need this constructor for serialization purposes, but the
-     * invalid range should be filled with something read from
-     * the archive before it is used, so we should hopefully
-     * never get to see an invalid range in the wild.
-     **/
+     * Default constructor. Since there is no useful choice for a default
+     * constructed interval, this constructor simply creates something that
+     * resembles an invalid range. We need this constructor for serialization
+     * purposes, but the invalid range should be filled with something read
+     * from the archive before it is used, so we should hopefully never get to
+     * see an invalid range in the wild.
+     */
     Range ();
 
     /**
      * Constructor. Create a half-open interval with the given indices.
      *
      * @param i1 Left end point of the interval.
-     * @param i2 First index greater than the last index of the indicated range.
-     **/
+     * @param i2 First index greater than the last index of the indicated
+     * range.
+     */
     Range (const types::global_dof_index i1,
            const types::global_dof_index i2);
 
@@ -436,10 +435,10 @@ private:
    * This integer caches the index of the largest range in @p ranges. This
    * gives <tt>O(1)</tt> access to the range with most elements, while general
    * access costs <tt>O(log(n_ranges))</tt>. The largest range is needed for
-   * the methods @p is_element(), @p index_within_set(), @p
-   * nth_index_in_set. In many applications, the largest range contains most
-   * elements (the locally owned range), whereas there are only a few other
-   * elements (ghosts).
+   * the methods @p is_element(), @p index_within_set(), @p nth_index_in_set.
+   * In many applications, the largest range contains most elements (the
+   * locally owned range), whereas there are only a few other elements
+   * (ghosts).
    */
   mutable types::global_dof_index largest_range;
 
@@ -451,16 +450,15 @@ private:
 
 
 /**
- * Create and return an index set of size $N$ that contains every
- * single index within this range. In essence, this function
- * returns an index set created by
+ * Create and return an index set of size $N$ that contains every single index
+ * within this range. In essence, this function returns an index set created
+ * by
  * @code
  *  IndexSet is (N);
  *  is.add_range(0, N);
  * @endcode
- * This function exists so that one can create and initialize
- * index sets that are complete in one step, or so one can write
- * code like
+ * This function exists so that one can create and initialize index sets that
+ * are complete in one step, or so one can write code like
  * @code
  *   if (my_index_set == complete_index_set(my_index_set.size())
  *     ...
index 3c335843252d3f4f02a601b3bf03be7b51bb8c68..bad89e2038b2754915b06d318663e33069524726 100644 (file)
@@ -26,11 +26,10 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * A class that is used to denote a collection of iterators that can
- * be expressed in terms of a range of iterators characterized by a begin
- * and an end iterator. As is common in C++, these ranges are specified as
- * half open intervals defined by a begin iterator and a one-past-the-end
- * iterator.
+ * A class that is used to denote a collection of iterators that can be
+ * expressed in terms of a range of iterators characterized by a begin and an
+ * end iterator. As is common in C++, these ranges are specified as half open
+ * intervals defined by a begin iterator and a one-past-the-end iterator.
  *
  * The purpose of this class is so that classes such as Triangulation and
  * DoFHandler can return ranges of cell iterators using an object of the
@@ -38,35 +37,35 @@ DEAL_II_NAMESPACE_OPEN
  * object can then be used in a range-based for loop as supported by C++11,
  * see also @ref CPP11 "C++11 standard".
  *
- * For example, such a loop could look like this if the goal is to set
- * the user flag on every active cell:
+ * For example, such a loop could look like this if the goal is to set the
+ * user flag on every active cell:
  * @code
  *   Triangulation<dim> triangulation;
  *   ...
  *   for (auto cell : triangulation.active_cell_iterators())
  *     cell->set_user_flag();
  * @endcode
- * In other words, the <code>cell</code> objects are iterators, and the
- * range object returned by Triangulation::active_cell_iterators() and
- * similar functions are conceptually thought of as <i>collections of
- * iterators</i>.
+ * In other words, the <code>cell</code> objects are iterators, and the range
+ * object returned by Triangulation::active_cell_iterators() and similar
+ * functions are conceptually thought of as <i>collections of iterators</i>.
  *
- * Of course, the class may also be used to denote other iterator
- * ranges using different kinds of iterators into other containers.
+ * Of course, the class may also be used to denote other iterator ranges using
+ * different kinds of iterators into other containers.
  *
  *
  * <h3>Class design: Motivation</h3>
  *
- * Informally, the way the C++11 standard describes
- * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">range-based
- * for loops</a> works as follows: A <i>range-based for loop</i> of the form
+ * Informally, the way the C++11 standard describes <a
+ * href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">range-
+ * based for loops</a> works as follows: A <i>range-based for loop</i> of the
+ * form
  * @code
  *   Container c;
  *   for (auto v : c)
  *     statement;
  * @endcode
- * where <code>c</code> is a container or collection, is equivalent to the following
- * loop:
+ * where <code>c</code> is a container or collection, is equivalent to the
+ * following loop:
  * @code
  *   Container c;
  *   for (auto tmp=c.begin(); tmp!=c.end(); ++tmp)
@@ -75,38 +74,37 @@ DEAL_II_NAMESPACE_OPEN
  *       statement;
  *     }
  * @endcode
- * In other words, the compiler introduces a temporary variable that <i>iterates</i>
- * over the elements of the container or collection, and the original variable
- * <code>v</code> that appeared in the range-based for loop represents the
- * <i>dereferenced</i> state of these iterators -- in other words, the
- * <i>elements</i> of the collection.
+ * In other words, the compiler introduces a temporary variable that
+ * <i>iterates</i> over the elements of the container or collection, and the
+ * original variable <code>v</code> that appeared in the range-based for loop
+ * represents the <i>dereferenced</i> state of these iterators -- in other
+ * words, the <i>elements</i> of the collection.
  *
- * In the context of loops over cells, we typically want to retain the fact that
- * the loop variable is an iterator, not a value. This is because in deal.II,
- * we never actually use the <i>dereferenced state</i> of a cell iterator:
- * conceptually, it would represent a cell, and technically it is implemented
- * by classes such as CellAccessor and DoFCellAccessor, but these classes are
- * never used explicitly. Consequently, what we would like is that a call
- * such as Triangulation::active_cell_iterators() returns an object that
- * represents a <i>collection of iterators</i> of the kind
- * <code>{begin, begin+1, ..., end-1}</code>. This is conveniently expressed
- * as the half open interval <code>[begin,end)</code>. The loop variable in the
- * range-based for loop would then take on each of these iterators in turn.
+ * In the context of loops over cells, we typically want to retain the fact
+ * that the loop variable is an iterator, not a value. This is because in
+ * deal.II, we never actually use the <i>dereferenced state</i> of a cell
+ * iterator: conceptually, it would represent a cell, and technically it is
+ * implemented by classes such as CellAccessor and DoFCellAccessor, but these
+ * classes are never used explicitly. Consequently, what we would like is that
+ * a call such as Triangulation::active_cell_iterators() returns an object
+ * that represents a <i>collection of iterators</i> of the kind <code>{begin,
+ * begin+1, ..., end-1}</code>. This is conveniently expressed as the half
+ * open interval <code>[begin,end)</code>. The loop variable in the range-
+ * based for loop would then take on each of these iterators in turn.
  *
  *
  * <h3>Class design: Implementation</h3>
  *
- * To represent the desired semantics as outlined above, this class
- * stores a half-open range of iterators <code>[b,e)</code> of
- * the given template type. Secondly, the class needs to provide begin()
- * and end() functions in such a way that if you <i>dereference</i> the
- * result of IteratorRange::begin(), you get the <code>b</code> iterator.
- * Furthermore, you must be able to increment the object returned by
- * IteratorRange::begin() so that <code>*(++begin()) == b+1</code>.
- * In other words, IteratorRange::begin() must return an iterator that
- * when dereferenced returns an iterator of the template type
- * <code>Iterator</code>: It is an iterator over iterators in the same
- * sense as if you had a pointer into an array of pointers.
+ * To represent the desired semantics as outlined above, this class stores a
+ * half-open range of iterators <code>[b,e)</code> of the given template type.
+ * Secondly, the class needs to provide begin() and end() functions in such a
+ * way that if you <i>dereference</i> the result of IteratorRange::begin(),
+ * you get the <code>b</code> iterator. Furthermore, you must be able to
+ * increment the object returned by IteratorRange::begin() so that
+ * <code>*(++begin()) == b+1</code>. In other words, IteratorRange::begin()
+ * must return an iterator that when dereferenced returns an iterator of the
+ * template type <code>Iterator</code>: It is an iterator over iterators in
+ * the same sense as if you had a pointer into an array of pointers.
  *
  * This is implemented in the form of the IteratorRange::IteratorOverIterators
  * class.
@@ -119,37 +117,36 @@ class IteratorRange
 {
 public:
   /**
-   * A class that implements the semantics of iterators over iterators
-   * as discussed in the design sections of the IteratorRange class.
+   * A class that implements the semantics of iterators over iterators as
+   * discussed in the design sections of the IteratorRange class.
    */
   class IteratorOverIterators : public std::iterator<std::forward_iterator_tag, Iterator,
     typename Iterator::difference_type>
   {
   public:
     /**
-     * Typedef the elements of the collection to give them a name that is
-     * more distinct.
+     * Typedef the elements of the collection to give them a name that is more
+     * distinct.
      */
     typedef Iterator BaseIterator;
 
     /**
-     * Constructor. Initialize this iterator-over-iterator in
-     * such a way that it points to the given argument.
+     * Constructor. Initialize this iterator-over-iterator in such a way that
+     * it points to the given argument.
      *
-     * @param iterator An iterator to which this object
-     *   is supposed to point.
+     * @param iterator An iterator to which this object is supposed to point.
      */
     IteratorOverIterators (const BaseIterator &iterator);
 
     /**
-     * Dereferencing operator.
-     * @return The iterator within the collection currently pointed to.
+     * Dereferencing operator. @return The iterator within the collection
+     * currently pointed to.
      */
     BaseIterator operator* () const;
 
     /**
-     * Dereferencing operator.
-     * @return The iterator within the collection currently pointed to.
+     * Dereferencing operator. @return The iterator within the collection
+     * currently pointed to.
      */
     const BaseIterator *operator-> () const;
 
@@ -168,10 +165,9 @@ public:
 
     /**
      * Comparison operator
-     * @param i_o_i Another iterator over iterators.
-     * @return Returns whether the current iterator points to a
-     *   different object than the iterator represented by the
-     *   argument.
+     * @param i_o_i Another iterator over iterators. @return Returns whether
+     * the current iterator points to a different object than the iterator
+     * represented by the argument.
      */
     bool operator != (const IteratorOverIterators &i_o_i);
 
@@ -189,9 +185,9 @@ public:
   typedef Iterator iterator;
 
   /**
-   * Default constructor. Create a range represented by two
-   * default constructed iterators. This range is likely (depending
-   * on the type of the iterators) empty.
+   * Default constructor. Create a range represented by two default
+   * constructed iterators. This range is likely (depending on the type of the
+   * iterators) empty.
    */
   IteratorRange();
 
@@ -200,7 +196,7 @@ public:
    *
    * @param[in] begin An iterator pointing to the first element of the range
    * @param[in] end   An iterator pointing past the last element represented
-   *   by this range.
+   * by this range.
    */
   IteratorRange (const iterator begin,
                  const iterator end);
@@ -211,8 +207,8 @@ public:
   IteratorOverIterators begin();
 
   /**
-   * Return the iterator pointing to the element past the last
-   * element of this range.
+   * Return the iterator pointing to the element past the last element of this
+   * range.
    */
   IteratorOverIterators end();
 
index 6160c79259abdfb38e98a4b0c32dcd4b3bdd39ed..48a3aad0d410b01514a6b5b7c9bee3ed857b04dd 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 /**
  * Identification of a program run. <tt>JobIdentifier</tt> determines the
- * start time of a program run and stores it as a program
- * identifier. There exists a library object <tt>dealjobid</tt> of this
- * class. This object can be accessed by all output functions to
- * provide an id for the current job.
+ * start time of a program run and stores it as a program identifier. There
+ * exists a library object <tt>dealjobid</tt> of this class. This object can
+ * be accessed by all output functions to provide an id for the current job.
  *
  * @ingroup utilities
  */
@@ -34,41 +33,26 @@ class JobIdentifier
 {
 public:
   /**
-   * Constructor. Set program
-   * identifier to value of
-   * <tt>program_id</tt> concatenated
-   * with the present time.
+   * Constructor. Set program identifier to value of <tt>program_id</tt>
+   * concatenated with the present time.
    */
   JobIdentifier();
 
   /**
-   * This function returns an
-   * identifier for the running
-   * program. Currently, the
-   * library provides a function
-   * returning "JobID".
+   * This function returns an identifier for the running program. Currently,
+   * the library provides a function returning "JobID".
    *
-   * The user may define a
-   * replacement of this function
-   * in his source code and avoid
-   * linking the library
-   * version. Unfortunately, this
-   * mechanism does not work with
-   * shared libraries.
+   * The user may define a replacement of this function in his source code and
+   * avoid linking the library version. Unfortunately, this mechanism does not
+   * work with shared libraries.
    */
   static const char *program_id();
 
   /**
-   * Obtain the base name of the
-   * file currently being
-   * compiled. That is, if the file
-   * is <tt>mypath/file.cc</tt>
-   * return just
-   * <tt>file</tt>. Typically, this
-   * can be called from a program
-   * with the argument
-   * <tt>__FILE__</tt> and is used
-   * in the deal.II test suite.
+   * Obtain the base name of the file currently being compiled. That is, if
+   * the file is <tt>mypath/file.cc</tt> return just <tt>file</tt>. Typically,
+   * this can be called from a program with the argument <tt>__FILE__</tt> and
+   * is used in the deal.II test suite.
    */
   static std::string base_name(const char *filename);
 
@@ -79,9 +63,7 @@ public:
 
 private:
   /**
-   * String holding the identifier
-   * of the presently running
-   * program.
+   * String holding the identifier of the presently running program.
    */
   std::string id;
 };
index 3388f6b1c1630be1df8797906713878f16e554ee..f3fabdc4bd83c04b7059780655b809ece6fb7cef 100644 (file)
@@ -45,70 +45,67 @@ DEAL_II_NAMESPACE_OPEN
  * providing
  * <ul>
  * <li> a push and pop mechanism for prefixes, and
- * <li> the possibility of distributing information to files and the
- *   console.
+ * <li> the possibility of distributing information to files and the console.
  * </ul>
  *
  * The usual usage of this class is through the pregenerated object
  * <tt>deallog</tt>. Typical setup steps are:
  * <ul>
- * <li> <tt>deallog.depth_console(n)</tt>: restrict output on screen to outer loops.
- * <li> <tt>deallog.attach(std::ostream)</tt>: write logging information into a file.
- * <li> <tt>deallog.depth_file(n)</tt>: restrict output to file to outer loops.
+ * <li> <tt>deallog.depth_console(n)</tt>: restrict output on screen to outer
+ * loops.
+ * <li> <tt>deallog.attach(std::ostream)</tt>: write logging information into
+ * a file.
+ * <li> <tt>deallog.depth_file(n)</tt>: restrict output to file to outer
+ * loops.
  * </ul>
  *
- * Before entering a new phase of your program, e.g. a new loop,
- * a new prefix can be set via <tt>LogStream::Prefix p("loopname");</tt>.
- * The destructor of the prefix will pop the prefix text from the stack.
+ * Before entering a new phase of your program, e.g. a new loop, a new prefix
+ * can be set via <tt>LogStream::Prefix p("loopname");</tt>. The destructor of
+ * the prefix will pop the prefix text from the stack.
  *
- * Writes via the <tt>&lt;&lt;</tt> operator,
- * <tt> deallog << "This is a log notice";</tt> will be buffered thread
- * locally until a <tt>std::flush</tt> or <tt>std::endl</tt> is
- * encountered, which will trigger a writeout to the console and, if set
- * up, the log file.
+ * Writes via the <tt>&lt;&lt;</tt> operator, <tt> deallog << "This is a log
+ * notice";</tt> will be buffered thread locally until a <tt>std::flush</tt>
+ * or <tt>std::endl</tt> is encountered, which will trigger a writeout to the
+ * console and, if set up, the log file.
  *
  * <h3>LogStream and thread safety</h3>
  *
- * In the vicinity of concurrent threads, LogStream behaves in the
- * following manner:
+ * In the vicinity of concurrent threads, LogStream behaves in the following
+ * manner:
  * <ul>
  * <li> Every write to a Logstream with operator <tt>&lt;&lt;</tt> (or with
- * one of the special member functions) is buffered in a thread-local
- * storage.
- * <li> An <tt>std::flush</tt> or <tt>std::endl</tt> will trigger a
- * writeout to the console and (if attached) to the file stream. This
- * writeout is sequentialized so that output from concurrent threads don't
- * interleave.
+ * one of the special member functions) is buffered in a thread-local storage.
+ * <li> An <tt>std::flush</tt> or <tt>std::endl</tt> will trigger a writeout
+ * to the console and (if attached) to the file stream. This writeout is
+ * sequentialized so that output from concurrent threads don't interleave.
  * <li> On a new thread, invoking a writeout, as well as a call to #push or
- * #pop will copy the current prefix of the "blessed" thread that created
- * the LogStream instance to a thread-local storage. After that prefixes
- * are thread-local.
+ * #pop will copy the current prefix of the "blessed" thread that created the
+ * LogStream instance to a thread-local storage. After that prefixes are
+ * thread-local.
  * </ul>
  *
  * <h3>LogStream and reproducible regression test output</h3>
  *
- * Generating reproducible floating point output for regression tests
- * is mildly put a nightmare. In order to make life a little easier,
- * LogStream implements a few features that try to achieve such a
- * goal. These features are turned on by calling test_mode(), and it
- * is not recommended to use them in any other environment. Right now,
- * LogStream implements the following:
+ * Generating reproducible floating point output for regression tests is
+ * mildly put a nightmare. In order to make life a little easier, LogStream
+ * implements a few features that try to achieve such a goal. These features
+ * are turned on by calling test_mode(), and it is not recommended to use them
+ * in any other environment. Right now, LogStream implements the following:
  *
  * <ol>
  * <li> A double number very close to zero will end up being output in
- * exponential format, although it has no significant digits. The
- * parameter #double_threshold determines which numbers are too close
- * to zero to be considered nonzero.
+ * exponential format, although it has no significant digits. The parameter
+ * #double_threshold determines which numbers are too close to zero to be
+ * considered nonzero.
  * <li> For float numbers holds the same, but with a typically larger
  * #float_threshold.
- * <li> Rounded numbers become unreliable with inexact
- * arithmetics. Therefore, adding a small number before rounding makes
- * results more reproducible, assuming that numbers like 0.5 are more
- * likely than 0.49997.
+ * <li> Rounded numbers become unreliable with inexact arithmetics. Therefore,
+ * adding a small number before rounding makes results more reproducible,
+ * assuming that numbers like 0.5 are more likely than 0.49997.
  * </ol>
- * It should be pointed out that all of these measures distort the
- * output and make it less accurate. Therefore, they are only
- * recommended if the output needs to be reproducible.
+ * It should be pointed out that all of these measures distort the output and
+ * make it less accurate. Therefore, they are only recommended if the output
+ * needs to be reproducible.
  *
  * @ingroup textoutput
  * @author Guido Kanschat, Wolfgang Bangerth, 1999, 2003, 2011
@@ -119,19 +116,19 @@ public:
   /**
    * A subclass allowing for the safe generation and removal of prefices.
    *
-   * Somewhere at the beginning of a block, create one of these objects,
-   * and it will appear as a prefix in LogStream output like @p deallog. At
-   * the end of the block, the prefix will automatically be removed, when
-   * this object is destroyed.
+   * Somewhere at the beginning of a block, create one of these objects, and
+   * it will appear as a prefix in LogStream output like @p deallog. At the
+   * end of the block, the prefix will automatically be removed, when this
+   * object is destroyed.
    *
    * In other words, the scope of the object so created determines the
-   * lifetime of the prefix. The advantage of using such an object is that
-   * the prefix is removed whichever way you exit the scope -- by
+   * lifetime of the prefix. The advantage of using such an object is that the
+   * prefix is removed whichever way you exit the scope -- by
    * <code>continue</code>, <code>break</code>, <code>return</code>,
    * <code>throw</code>, or by simply reaching the closing brace. In all of
-   * these cases, it is not necessary to remember to pop the prefix
-   * manually using LogStream::pop. In this, it works just like the better
-   * known Threads::Mutex::ScopedLock class.
+   * these cases, it is not necessary to remember to pop the prefix manually
+   * using LogStream::pop. In this, it works just like the better known
+   * Threads::Mutex::ScopedLock class.
    */
   class Prefix
   {
@@ -143,8 +140,8 @@ public:
     Prefix(const std::string &text);
 
     /**
-     * Set a new prefix for the given stream, which will be removed when
-     * the variable is destroyed.
+     * Set a new prefix for the given stream, which will be removed when the
+     * variable is destroyed.
      */
     Prefix(const std::string &text,
            LogStream &stream);
@@ -183,9 +180,8 @@ public:
 
 
   /**
-   * Disable output to the second stream. You may want to call
-   * <tt>close</tt> on the stream that was previously attached to this
-   * object.
+   * Disable output to the second stream. You may want to call <tt>close</tt>
+   * on the stream that was previously attached to this object.
    */
   void detach ();
 
@@ -193,12 +189,12 @@ public:
   /**
    * Setup the logstream for regression test mode.
    *
-   * This sets the parameters #double_threshold, #float_threshold, and
-   * #offset to nonzero values. The exact values being used have been
-   * determined experimentally and can be found in the source code.
+   * This sets the parameters #double_threshold, #float_threshold, and #offset
+   * to nonzero values. The exact values being used have been determined
+   * experimentally and can be found in the source code.
    *
-   * Called with an argument <tt>false</tt>, switches off test mode and
-   * sets all involved parameters to zero.
+   * Called with an argument <tt>false</tt>, switches off test mode and sets
+   * all involved parameters to zero.
    */
   void test_mode (bool on=true);
 
@@ -235,8 +231,8 @@ public:
 
 
   /**
-   * Push another prefix on the stack. Prefixes are automatically separated
-   * by a colon and there is a double colon after the last prefix.
+   * Push another prefix on the stack. Prefixes are automatically separated by
+   * a colon and there is a double colon after the last prefix.
    *
    * A simpler way to add a prefix (without the manual need to add the
    * corresponding pop()) is to use the Prefix class.
@@ -262,10 +258,9 @@ public:
 
 
   /**
-   * Maximum number of levels to be written to the log file. The
-   * functionality is the same as <tt>depth_console</tt>, nevertheless,
-   * this function should be used with care, since it may spoile the value
-   * of a log file.
+   * Maximum number of levels to be written to the log file. The functionality
+   * is the same as <tt>depth_console</tt>, nevertheless, this function should
+   * be used with care, since it may spoile the value of a log file.
    *
    * The previous value of this parameter is returned.
    */
@@ -283,10 +278,10 @@ public:
 
   /**
    * Output time differences between consecutive logs. If this function is
-   * invoked with <tt>true</tt>, the time difference between the previous
-   * log line and the recent one is printed. If it is invoked with
-   * <tt>false</tt>, the accumulated time since start of the program is
-   * printed (default behavior).
+   * invoked with <tt>true</tt>, the time difference between the previous log
+   * line and the recent one is printed. If it is invoked with <tt>false</tt>,
+   * the accumulated time since start of the program is printed (default
+   * behavior).
    *
    * The measurement of times is not changed by this function, just the
    * output.
@@ -315,17 +310,16 @@ public:
    * The default value for this threshold is zero, i.e. numbers are printed
    * according to their real value.
    *
-   * This feature is mostly useful for automated tests: there, one would
-   * like to reproduce the exact same solution in each run of a testsuite.
-   * However, subtle difference in processor, operating system, or compiler
-   * version can lead to differences in the last few digits of numbers, due
-   * to different rounding. While one can avoid trouble for most numbers
-   * when comparing with stored results by simply limiting the accuracy of
-   * output, this does not hold for numbers very close to zero, i.e. zero
-   * plus accumulated round-off. For these numbers, already the first digit
-   * is tainted by round-off. Using the present function, it is possible to
-   * eliminate this source of problems, by simply writing zero to the
-   * output in this case.
+   * This feature is mostly useful for automated tests: there, one would like
+   * to reproduce the exact same solution in each run of a testsuite. However,
+   * subtle difference in processor, operating system, or compiler version can
+   * lead to differences in the last few digits of numbers, due to different
+   * rounding. While one can avoid trouble for most numbers when comparing
+   * with stored results by simply limiting the accuracy of output, this does
+   * not hold for numbers very close to zero, i.e. zero plus accumulated
+   * round-off. For these numbers, already the first digit is tainted by
+   * round-off. Using the present function, it is possible to eliminate this
+   * source of problems, by simply writing zero to the output in this case.
    */
   void threshold_double(const double t);
 
@@ -337,24 +331,24 @@ public:
 
 
   /**
-   * set the precision for the underlying stream and returns the
-   * previous stream precision. This fuction mimics
+   * set the precision for the underlying stream and returns the previous
+   * stream precision. This fuction mimics
    * http://www.cplusplus.com/reference/ios/ios_base/precision/
    */
   std::streamsize precision (const std::streamsize prec);
 
 
   /**
-   * set the width for the underlying stream and returns the
-   * previous stream width. This fuction mimics
+   * set the width for the underlying stream and returns the previous stream
+   * width. This fuction mimics
    * http://www.cplusplus.com/reference/ios/ios_base/width/
    */
   std::streamsize width (const std::streamsize wide);
 
 
   /**
-   * set the flags for the underlying stream and returns the
-   * previous stream flags. This fuction mimics
+   * set the flags for the underlying stream and returns the previous stream
+   * flags. This fuction mimics
    * http://www.cplusplus.com/reference/ios/ios_base/flags/
    */
   std::ios::fmtflags flags(const std::ios::fmtflags f);
@@ -381,27 +375,26 @@ public:
   /**
    * Treat ostream manipulators. This passes on the whole thing to the
    * template function with the exception of the <tt>std::endl</tt>
-   * manipulator, for which special action is performed: write the
-   * temporary stream buffer including a header to the file and
-   * <tt>std::cout</tt> and empty the buffer.
+   * manipulator, for which special action is performed: write the temporary
+   * stream buffer including a header to the file and <tt>std::cout</tt> and
+   * empty the buffer.
    *
-   * An overload of this function is needed anyway, since the compiler
-   * can't bind manipulators like @p std::endl directly to template
-   * arguments @p T like in the previous general template. This is due to
-   * the fact that @p std::endl is actually an overloaded set of functions
-   * for @p std::ostream, @p std::wostream, and potentially more of this
-   * kind. This function is therefore necessary to pick one element from
-   * this overload set.
+   * An overload of this function is needed anyway, since the compiler can't
+   * bind manipulators like @p std::endl directly to template arguments @p T
+   * like in the previous general template. This is due to the fact that @p
+   * std::endl is actually an overloaded set of functions for @p std::ostream,
+   * @p std::wostream, and potentially more of this kind. This function is
+   * therefore necessary to pick one element from this overload set.
    */
   LogStream &operator<< (std::ostream& (*p) (std::ostream &));
 
 
   /**
    * Determine an estimate for the memory consumption (in bytes) of this
-   * object. Since sometimes the size of objects can not be determined
-   * exactly (for example: what is the memory consumption of an STL
-   * <tt>std::map</tt> type with a certain number of elements?), this is
-   * only an estimate. however often quite close to the true value.
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   std::size_t memory_consumption () const;
 
@@ -415,17 +408,17 @@ private:
 
 
   /**
-   * Internal wrapper around thread-local prefixes. This private
-   * function will return the correct internal prefix stack. More
-   * important, a new thread-local stack will be copied from the current
-   * stack of the "blessed" thread that created this LogStream instance
-   * (usually, in the case of deallog, the "main" thread).
+   * Internal wrapper around thread-local prefixes. This private function will
+   * return the correct internal prefix stack. More important, a new thread-
+   * local stack will be copied from the current stack of the "blessed" thread
+   * that created this LogStream instance (usually, in the case of deallog,
+   * the "main" thread).
    */
   std::stack<std::string> &get_prefixes() const;
 
   /**
-   * Stack of strings which are printed at the beginning of each line to
-   * allow identification where the output was generated.
+   * Stack of strings which are printed at the beginning of each line to allow
+   * identification where the output was generated.
    */
   mutable Threads::ThreadLocalStorage<std::stack<std::string> > prefixes;
 
@@ -446,9 +439,9 @@ private:
 
   /**
    * Value denoting the number of prefixes to be printed to the standard
-   * output. If more than this number of prefixes is pushed to the stack,
-   * then no output will be generated until the number of prefixes shrinks
-   * back below this number.
+   * output. If more than this number of prefixes is pushed to the stack, then
+   * no output will be generated until the number of prefixes shrinks back
+   * below this number.
    */
   unsigned int std_depth;
 
@@ -485,19 +478,19 @@ private:
   float float_threshold;
 
   /**
-   * An offset added to every float or double number upon output. This is
-   * done after the number is compared to #double_threshold or
-   * #float_threshold, but before rounding.
+   * An offset added to every float or double number upon output. This is done
+   * after the number is compared to #double_threshold or #float_threshold,
+   * but before rounding.
    *
-   * This functionality was introduced to produce more reproducible
-   * floating point output for regression tests. The rationale is, that an
-   * exact output value is much more likely to be 1/8 than 0.124997. If we
-   * round to two digits though, 1/8 becomes unreliably either .12 or .13
-   * due to machine accuracy. On the other hand, if we add a something
-   * above machine accuracy first, we will always get .13.
+   * This functionality was introduced to produce more reproducible floating
+   * point output for regression tests. The rationale is, that an exact output
+   * value is much more likely to be 1/8 than 0.124997. If we round to two
+   * digits though, 1/8 becomes unreliably either .12 or .13 due to machine
+   * accuracy. On the other hand, if we add a something above machine accuracy
+   * first, we will always get .13.
    *
-   * It is safe to leave this value equal to zero. For regression tests,
-   * the function test_mode() sets it to a reasonable value.
+   * It is safe to leave this value equal to zero. For regression tests, the
+   * function test_mode() sets it to a reasonable value.
    *
    * The offset is relative to the magnitude of the number.
    */
@@ -520,9 +513,8 @@ private:
 
   /**
    * Original buffer of <tt>std::cerr</tt>. We store the address of that
-   * buffer when #log_cerr is called, and reset it to this value if
-   * #log_cerr is called a second time, or when the destructor of this
-   * class is run.
+   * buffer when #log_cerr is called, and reset it to this value if #log_cerr
+   * is called a second time, or when the destructor of this class is run.
    */
   std::streambuf *old_cerr;
 
@@ -538,15 +530,14 @@ private:
   void print_line_head ();
 
   /**
-   * Internal wrapper around "thread local" outstreams. This private
-   * function will return the correct internal ostringstream buffer for
-   * operater<<.
+   * Internal wrapper around "thread local" outstreams. This private function
+   * will return the correct internal ostringstream buffer for operater<<.
    */
   std::ostringstream &get_stream();
 
   /**
-   * We use tbb's thread local storage facility to generate a stringstream
-   * for every thread that sends log messages.
+   * We use tbb's thread local storage facility to generate a stringstream for
+   * every thread that sends log messages.
    */
   Threads::ThreadLocalStorage<std_cxx11::shared_ptr<std::ostringstream> > outstreams;
 
index 76f71ad92df49bd76396a719cd35e4ac3a5d4260..9fc7eeb371639c58d978edcba8e3e5dc79968810 100644 (file)
@@ -33,56 +33,53 @@ template <typename T> class VectorizedArray;
 
 
 /**
- * This namespace provides functions helping to determine the amount
- * of memory used by objects. The goal is not necessarily to give the
- * amount of memory used up to the last bit (what is the memory used
- * by an STL <tt>std::map<></tt> object?), but rather to aid in the search for
- * memory bottlenecks.
+ * This namespace provides functions helping to determine the amount of memory
+ * used by objects. The goal is not necessarily to give the amount of memory
+ * used up to the last bit (what is the memory used by an STL
+ * <tt>std::map<></tt> object?), but rather to aid in the search for memory
+ * bottlenecks.
  *
- * This namespace has a single member function memory_consumption()
- * and a lot of specializations. Depending on the argument type of the
- * function, there are several modes of operation:
+ * This namespace has a single member function memory_consumption() and a lot
+ * of specializations. Depending on the argument type of the function, there
+ * are several modes of operation:
  *
  * <ol>
- * <li> The argument is a standard C++ data type, namely,
- * <tt>bool</tt>, <tt>float</tt>, <tt>double</tt> or any of the
- * integer types. In that case, memory_consumption() simple returns
- * <tt>sizeof</tt> of its argument. The library also provides an
- * estimate for the amount of memory occupied by a
+ * <li> The argument is a standard C++ data type, namely, <tt>bool</tt>,
+ * <tt>float</tt>, <tt>double</tt> or any of the integer types. In that case,
+ * memory_consumption() simple returns <tt>sizeof</tt> of its argument. The
+ * library also provides an estimate for the amount of memory occupied by a
  * <tt>std::string</tt> this way.
  *
  * <li> For objects, which are neither standard types, nor vectors,
- * memory_consumption() will simply call the member function of same
- * name. It is up to the implementation of the data type to provide a
- * good estimate of the amount of memory used. Inside this function,
- * the use of MemoryConsumpton::memory_consumption() for compounds of
- * the class helps to obtain this estimate. Most classes in the
- * deal.II library have such a member function.
+ * memory_consumption() will simply call the member function of same name. It
+ * is up to the implementation of the data type to provide a good estimate of
+ * the amount of memory used. Inside this function, the use of
+ * MemoryConsumpton::memory_consumption() for compounds of the class helps to
+ * obtain this estimate. Most classes in the deal.II library have such a
+ * member function.
  *
  * <li> For vectors and C++ arrays of objects, memory_consumption()
- * recursively calls itself for all entries and adds the results to
- * the size of the object itself. Some optimized specializations for
- * standard data types exist.
+ * recursively calls itself for all entries and adds the results to the size
+ * of the object itself. Some optimized specializations for standard data
+ * types exist.
  *
- * <li> For vectors of regular pointers, memory_consumption(T*)
- * returns the size of the vector of pointers, ignoring the size of
- * the objects.
+ * <li> For vectors of regular pointers, memory_consumption(T*) returns the
+ * size of the vector of pointers, ignoring the size of the objects.
  *
  * </ol>
  *
  * <h3>Extending this namespace</h3>
  *
- * The function in this namespace and the functionality provided by
- * it relies on the assumption that there is either a specialized function
- * <tt>memory_consumption(T)</tt> in this namespace determining the amount
- * of memory used by objects of type <tt>T</tt>, or that the class <tt>T</tt> has
- * a  member function of that name. While the latter is
- * true for almost all classes in deal.II, we have only implemented the
- * first kind of functions for the most common data types, such as
- * atomic types, strings, C++ vectors, C-style arrays, and C++
- * pairs. These functions therefore do not cover, for example, C++
- * maps, lists, etc. If you need such functions feel free to implement
- * them and send them to us for inclusion.
+ * The function in this namespace and the functionality provided by it relies
+ * on the assumption that there is either a specialized function
+ * <tt>memory_consumption(T)</tt> in this namespace determining the amount of
+ * memory used by objects of type <tt>T</tt>, or that the class <tt>T</tt> has
+ * a  member function of that name. While the latter is true for almost all
+ * classes in deal.II, we have only implemented the first kind of functions
+ * for the most common data types, such as atomic types, strings, C++ vectors,
+ * C-style arrays, and C++ pairs. These functions therefore do not cover, for
+ * example, C++ maps, lists, etc. If you need such functions feel free to
+ * implement them and send them to us for inclusion.
  *
  * @ingroup memory
  * @author Wolfgang Bangerth, documentation updated by Guido Kanschat
@@ -92,110 +89,91 @@ namespace MemoryConsumption
 {
 
   /**
-   * This function is the generic
-   * interface for determining the
-   * memory used by an object. If no
-   * specialization for the type
-   * <tt>T</tt> is specified, it will
-   * call the member function
-   * <tt>t.memory_consumption()</tt>.
+   * This function is the generic interface for determining the memory used by
+   * an object. If no specialization for the type <tt>T</tt> is specified, it
+   * will call the member function <tt>t.memory_consumption()</tt>.
    *
-   * The library provides
-   * specializations for all basic
-   * C++ data types. Every additional
-   * type needs to have a member
-   * function memory_consumption()
-   * callable for constant objects to
-   * be used in this framework.
+   * The library provides specializations for all basic C++ data types. Every
+   * additional type needs to have a member function memory_consumption()
+   * callable for constant objects to be used in this framework.
    */
   template <typename T>
   inline
   std::size_t memory_consumption (const T &t);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>bool</tt>
+   * Determine the amount of memory in bytes consumed by a <tt>bool</tt>
    * variable.
    */
   inline
   std::size_t memory_consumption (const bool);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>char</tt>
+   * Determine the amount of memory in bytes consumed by a <tt>char</tt>
    * variable.
    */
   inline
   std::size_t memory_consumption (const char);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a
-   * <tt>short int</tt> variable.
+   * Determine the amount of memory in bytes consumed by a <tt>short int</tt>
+   * variable.
    */
   inline
   std::size_t memory_consumption (const short int);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a
-   * <tt>short unsigned int</tt> variable.
+   * Determine the amount of memory in bytes consumed by a <tt>short unsigned
+   * int</tt> variable.
    */
   inline
   std::size_t memory_consumption (const short unsigned int);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>int</tt>
+   * Determine the amount of memory in bytes consumed by a <tt>int</tt>
    * variable.
    */
   inline
   std::size_t memory_consumption (const int);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>unsigned int</tt>
-   * variable.
+   * Determine the amount of memory in bytes consumed by a <tt>unsigned
+   * int</tt> variable.
    */
   inline
   std::size_t memory_consumption (const unsigned int);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>unsigned long long int</tt>
-   * variable.
+   * Determine the amount of memory in bytes consumed by a <tt>unsigned long
+   * long int</tt> variable.
    */
   inline
   std::size_t memory_consumption (const unsigned long long int);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>float</tt>
+   * Determine the amount of memory in bytes consumed by a <tt>float</tt>
    * variable.
    */
   inline
   std::size_t memory_consumption (const float);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>double</tt>
+   * Determine the amount of memory in bytes consumed by a <tt>double</tt>
    * variable.
    */
   inline
   std::size_t memory_consumption (const double);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>long double</tt>
-   * variable.
+   * Determine the amount of memory in bytes consumed by a <tt>long
+   * double</tt> variable.
    */
   inline
   std::size_t memory_consumption (const long double);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a <tt>std::complex</tt>
-   * variable.
+   * Determine the amount of memory in bytes consumed by a
+   * <tt>std::complex</tt> variable.
    */
   template <typename T>
   inline
@@ -210,230 +188,160 @@ namespace MemoryConsumption
   std::size_t memory_consumption (const VectorizedArray<T> &);
 
   /**
-   * Determine an estimate of the
-   * amount of memory in bytes
-   * consumed by a <tt>std::string</tt>
-   * variable.
+   * Determine an estimate of the amount of memory in bytes consumed by a
+   * <tt>std::string</tt> variable.
    */
   inline
   std::size_t memory_consumption (const std::string &s);
 
   /**
-   * Determine the amount of memory
-   * in bytes consumed by a
-   * <tt>std::vector</tt> of elements
-   * of type <tt>T</tt> by
-   * recursively calling
-   * memory_consumption() for each entry.
+   * Determine the amount of memory in bytes consumed by a
+   * <tt>std::vector</tt> of elements of type <tt>T</tt> by recursively
+   * calling memory_consumption() for each entry.
    *
-   * This function loops over all
-   * entries of the vector and
-   * determines their sizes using
-   * memory_consumption() for each
-   * <tt>v[i]</tt>. If the entries
-   * are of constant size, there
-   * might be another global function
-   * memory_consumption() for this
-   * data type or if there is a
-   * member function of that class of
-   * that names that returns a
-   * constant value and the compiler
-   * will unroll this loop so that
-   * the operation is fast. If the
-   * size of the data elements is
-   * variable, for example if they do
-   * memory allocation themselves,
-   * then the operation will
-   * necessarily be more expensive.
+   * This function loops over all entries of the vector and determines their
+   * sizes using memory_consumption() for each <tt>v[i]</tt>. If the entries
+   * are of constant size, there might be another global function
+   * memory_consumption() for this data type or if there is a member function
+   * of that class of that names that returns a constant value and the
+   * compiler will unroll this loop so that the operation is fast. If the size
+   * of the data elements is variable, for example if they do memory
+   * allocation themselves, then the operation will necessarily be more
+   * expensive.
    *
-   * Using the algorithm, in
-   * particular the loop over all
-   * elements, it is possible to also
-   * compute the memory consumption
-   * of vectors of vectors, vectors
-   * of strings, etc, where the
-   * individual elements may have
-   * vastly different sizes.
+   * Using the algorithm, in particular the loop over all elements, it is
+   * possible to also compute the memory consumption of vectors of vectors,
+   * vectors of strings, etc, where the individual elements may have vastly
+   * different sizes.
    *
-   * Note that this algorithm also
-   * takes into account the size of
-   * elements that are allocated by
-   * this vector but not currently
-   * used.
+   * Note that this algorithm also takes into account the size of elements
+   * that are allocated by this vector but not currently used.
    *
-   * For the most commonly used
-   * vectors, there are special
-   * functions that compute the size
-   * without a loop. This also
-   * applies for the special case of
-   * vectors of bools.
+   * For the most commonly used vectors, there are special functions that
+   * compute the size without a loop. This also applies for the special case
+   * of vectors of bools.
    */
   template <typename T>
   inline
   std::size_t memory_consumption (const std::vector<T> &v);
 
   /**
-   * Estimate the amount of memory
-   * (in bytes) occupied by a
-   * C-style array. Since in this
-   * library we do not usually
-   * store simple data elements
-   * like <tt>double</tt>s in such
-   * arrays (but rather use STL
-   * <tt>std::vector</tt>s or deal.II
-   * <tt>Vector</tt> objects), we do not
-   * provide specializations like
-   * for the <tt>std::vector</tt> arrays, but
-   * always use the loop over all
-   * elements.
+   * Estimate the amount of memory (in bytes) occupied by a C-style array.
+   * Since in this library we do not usually store simple data elements like
+   * <tt>double</tt>s in such arrays (but rather use STL <tt>std::vector</tt>s
+   * or deal.II <tt>Vector</tt> objects), we do not provide specializations
+   * like for the <tt>std::vector</tt> arrays, but always use the loop over
+   * all elements.
    */
   template <typename T, int N>
   inline
   std::size_t memory_consumption (const T (&v)[N]);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>bool</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>bool</tt>s.
    *
-   * This is a special case, as the
-   * bools are not stored
-   * one-by-one, but as a bit
-   * field.
+   * This is a special case, as the bools are not stored one-by-one, but as a
+   * bit field.
    */
   inline
   std::size_t memory_consumption (const std::vector<bool> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>int</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>int</tt>s.
    */
   inline
   std::size_t memory_consumption (const std::vector<int> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>double</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>double</tt>s.
    */
   inline
   std::size_t memory_consumption (const std::vector<double> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>float</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>float</tt>s.
    */
   inline
   std::size_t memory_consumption (const std::vector<float> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>char</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>char</tt>s.
    */
   inline
   std::size_t memory_consumption (const std::vector<char> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of <tt>unsigned char</tt>s.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of <tt>unsigned char</tt>s.
    */
   inline
   std::size_t memory_consumption (const std::vector<unsigned char> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of pointers.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of pointers.
    */
   template <typename T>
   inline
   std::size_t memory_consumption (const std::vector<T *> &v);
 
   /**
-   * Specialization of the
-   * determination of the memory
-   * consumption of a vector, here
-   * for a vector of strings. This
-   * function is not necessary from a
-   * strict C++ viewpoint, since it
-   * could be generated, but is
-   * necessary for compatibility with
-   * IBM's xlC 5.0 compiler, and
-   * doesn't harm for other compilers
-   * as well.
+   * Specialization of the determination of the memory consumption of a
+   * vector, here for a vector of strings. This function is not necessary from
+   * a strict C++ viewpoint, since it could be generated, but is necessary for
+   * compatibility with IBM's xlC 5.0 compiler, and doesn't harm for other
+   * compilers as well.
    */
   std::size_t memory_consumption (const std::vector<std::string> &v);
 
 
   /**
-   * Determine an estimate of the
-   * amount of memory in bytes
-   * consumed by a pair of values.
+   * Determine an estimate of the amount of memory in bytes consumed by a pair
+   * of values.
    */
   template <typename A, typename B>
   inline
   std::size_t memory_consumption (const std::pair<A,B> &p);
 
   /**
-   * Return the amount of memory
-   * used by a pointer.
+   * Return the amount of memory used by a pointer.
    *
-   * @note This returns the size of
-   * the pointer, not of the object
-   * pointed to.
+   * @note This returns the size of the pointer, not of the object pointed to.
    */
   template <typename T>
   inline
   std::size_t memory_consumption (const T *const);
 
   /**
-   * Return the amount of memory
-   * used by a pointer.
+   * Return the amount of memory used by a pointer.
    *
-   * @note This returns the size of
-   * the pointer, not of the object
-   * pointed to.
+   * @note This returns the size of the pointer, not of the object pointed to.
    */
   template <typename T>
   inline
   std::size_t memory_consumption (T *const);
 
   /**
-   * Return the amount of memory
-   * used by a void pointer.
+   * Return the amount of memory used by a void pointer.
    *
-   * Note that we needed this
-   * function since <tt>void</tt> is no
-   * type and a <tt>void*</tt> is thus
-   * not caught by the general
-   * <tt>T*</tt> template function
-   * above.
+   * Note that we needed this function since <tt>void</tt> is no type and a
+   * <tt>void*</tt> is thus not caught by the general <tt>T*</tt> template
+   * function above.
    *
-   * @note This returns the size of
-   * the pointer, not of the object
-   * pointed to.
+   * @note This returns the size of the pointer, not of the object pointed to.
    */
   inline
   std::size_t memory_consumption (void *const);
 
   /**
-   * Return the amount of memory used
-   * by a shared pointer.
+   * Return the amount of memory used by a shared pointer.
    *
-   * @note This returns the size of
-   * the pointer, not of the object
-   * pointed to.
+   * @note This returns the size of the pointer, not of the object pointed to.
    */
   template <typename T>
   inline
index 700cec9207d7ce6fe740420830cb0fdba8baacb3..3b13118cce6a8bf6aff5227762d5d1e9dea13a51 100644 (file)
@@ -25,14 +25,13 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * An array with an object for each level.  The purpose of this class
- * is mostly to store objects and allow access by level number, even
- * if the lower levels are not used and therefore have no object at
- * all; this is done by simply shifting the given index by the minimum
- * level we have stored.
+ * An array with an object for each level.  The purpose of this class is
+ * mostly to store objects and allow access by level number, even if the lower
+ * levels are not used and therefore have no object at all; this is done by
+ * simply shifting the given index by the minimum level we have stored.
  *
- * In most cases, the objects which are stored on each levels, are
- * either matrices or vectors.
+ * In most cases, the objects which are stored on each levels, are either
+ * matrices or vectors.
  *
  * @ingroup mg
  * @ingroup data
@@ -43,10 +42,8 @@ class MGLevelObject : public Subscriptor
 {
 public:
   /**
-   * Constructor allowing to
-   * initialize the number of
-   * levels. By default, the object
-   * is created empty.
+   * Constructor allowing to initialize the number of levels. By default, the
+   * object is created empty.
    */
   MGLevelObject (const unsigned int minlevel = 0,
                  const unsigned int maxlevel = 0);
@@ -57,37 +54,27 @@ public:
   Object &operator[] (const unsigned int level);
 
   /**
-   * Access object on level
-   * @p level. Constant version.
+   * Access object on level @p level. Constant version.
    */
   const Object &operator[] (const unsigned int level) const;
 
   /**
-   * Delete all previous contents
-   * of this object and reset its
-   * size according to the values
-   * of @p new_minlevel and
-   * @p new_maxlevel.
+   * Delete all previous contents of this object and reset its size according
+   * to the values of @p new_minlevel and @p new_maxlevel.
    */
   void resize (const unsigned int new_minlevel,
                const unsigned int new_maxlevel);
 
   /**
-   * Call <tt>operator = (s)</tt>
-   * on all objects stored by this
-   * object.  This is particularly
-   * useful for
-   * e.g. <tt>Object==Vector@<T@></tt>
+   * Call <tt>operator = (s)</tt> on all objects stored by this object.  This
+   * is particularly useful for e.g. <tt>Object==Vector@<T@></tt>
    */
   MGLevelObject<Object> &operator = (const double d);
 
   /**
-   * Call @p clear on all objects
-   * stored by this object. This
-   * function is only implemented
-   * for some @p Object classes,
-   * e.g. the PreconditionBlockSOR
-   * and similar classes.
+   * Call @p clear on all objects stored by this object. This function is only
+   * implemented for some @p Object classes, e.g. the PreconditionBlockSOR and
+   * similar classes.
    */
   void clear();
 
index 45da4aa613ea0b1cdf0d5cb5ceac5c9ebf143bac..ecd58f2f1fcc1aaa47afaebca9af84db9546b1d1 100644 (file)
@@ -281,41 +281,42 @@ namespace Utilities
                         char ** &argv) /*DEAL_II_DEPRECATED*/;
 
       /**
-       * Initialize MPI (and, if deal.II was configured to use it, PETSc)
-       * and set the number of threads used by deal.II (via the underlying
+       * Initialize MPI (and, if deal.II was configured to use it, PETSc) and
+       * set the number of threads used by deal.II (via the underlying
        * Threading Building Blocks library) to the given parameter.
        *
-       * @param[in,out] argc A reference to the 'argc' argument passed to main. This
-       *   argument is used to initialize MPI (and, possibly, PETSc) as they
-       *   read arguments from the command line.
-       * @param[in,out] argv A reference to the 'argv' argument passed to main.
-       * @param[in] max_num_threads The maximal number of threads this MPI process
-       *   should utilize. If this argument is set to
-       *   numbers::invalid_unsigned_int, the number of threads is determined by
-       *   automatically in the following way: the number of
-       *   threads to run on this MPI process is set in such a way that all of
-       *   the cores in your node are spoken for. In other words, if you
-       *   have started one MPI process per node, setting this argument is
-       *   equivalent to setting it to the number of cores present in the node
-       *   this MPI process runs on. If you have started as many MPI
-       *   processes per node as there are cores on each node, then
-       *   this is equivalent to passing 1 as the argument. On the
-       *   other hand, if, for example, you start 4 MPI processes
-       *   on each 16-core node, then this option will start 4 worker
-       *   threads for each node. If you start 3 processes on an 8 core
-       *   node, then they will start 3, 3 and 2 threads, respectively.
+       * @param[in,out] argc A reference to the 'argc' argument passed to
+       * main. This argument is used to initialize MPI (and, possibly, PETSc)
+       * as they read arguments from the command line.
+       * @param[in,out] argv A reference to the 'argv' argument passed to
+       * main.
+       * @param[in] max_num_threads The maximal number of threads this MPI
+       * process should utilize. If this argument is set to
+       * numbers::invalid_unsigned_int, the number of threads is determined by
+       * automatically in the following way: the number of threads to run on
+       * this MPI process is set in such a way that all of the cores in your
+       * node are spoken for. In other words, if you have started one MPI
+       * process per node, setting this argument is equivalent to setting it
+       * to the number of cores present in the node this MPI process runs on.
+       * If you have started as many MPI processes per node as there are cores
+       * on each node, then this is equivalent to passing 1 as the argument.
+       * On the other hand, if, for example, you start 4 MPI processes on each
+       * 16-core node, then this option will start 4 worker threads for each
+       * node. If you start 3 processes on an 8 core node, then they will
+       * start 3, 3 and 2 threads, respectively.
        *
-       * @note This function calls MultithreadInfo::set_thread_limit()
-       * with either @p max_num_threads or, following the discussion above, a
-       * number of threads equal to the number of cores allocated to this
-       * MPI process. However, MultithreadInfo::set_thread_limit() in turn also
-       * evaluates the environment variable DEAL_II_NUM_THREADS. Finally, the worker
-       * threads can only be created on cores to which the current MPI process has
-       * access to; some MPI implementations limit the number of cores each process
-       * has access to to one or a subset of cores in order to ensure better cache
-       * behavior. Consequently, the number of threads that will really be created
-       * will be the minimum of the argument passed here, the environment variable
-       * (if set), and the number of cores accessible to the thread.
+       * @note This function calls MultithreadInfo::set_thread_limit() with
+       * either @p max_num_threads or, following the discussion above, a
+       * number of threads equal to the number of cores allocated to this MPI
+       * process. However, MultithreadInfo::set_thread_limit() in turn also
+       * evaluates the environment variable DEAL_II_NUM_THREADS. Finally, the
+       * worker threads can only be created on cores to which the current MPI
+       * process has access to; some MPI implementations limit the number of
+       * cores each process has access to to one or a subset of cores in order
+       * to ensure better cache behavior. Consequently, the number of threads
+       * that will really be created will be the minimum of the argument
+       * passed here, the environment variable (if set), and the number of
+       * cores accessible to the thread.
        */
       MPI_InitFinalize (int    &argc,
                         char ** &argv,
index 00b6a05c53d9d06356813b7ccb1579b0421a7715..165e63f27734867d984228f173de0c38f79a7e07 100644 (file)
@@ -34,15 +34,10 @@ DEAL_II_NAMESPACE_OPEN
  * parallel methods is selected automatically by the Threading Building Blocks
  * library. See @ref threads for more information on this.  Thread-based
  * parallel methods need to explicitly created threads and may want to use a
- * number of threads that is related to the number of CPUs in your
- * system. This can be queried using the variable
- * <code>
- * multithread_info.n_cpus;
- * </code>
- * of a global variable <code>multithread_info</code> of this class that, or using
- * <code>
- * multithread_info.n_threads();
- * </code>
+ * number of threads that is related to the number of CPUs in your system.
+ * This can be queried using the variable <code> multithread_info.n_cpus;
+ * </code> of a global variable <code>multithread_info</code> of this class
+ * that, or using <code> multithread_info.n_threads(); </code>
  *
  * @ingroup threads
  * @author Thomas Richter, Wolfgang Bangerth, 2000
@@ -51,31 +46,20 @@ class MultithreadInfo
 {
 public:
   /**
-   * The constructor determines the
-   * number of CPUs in the system.
-   * At the moment detection of
-   * CPUs is only implemented on
-   * Linux computers with the /proc
-   * filesystem and on Sun
-   * machines.  The number of CPUs
-   * present is set to one if
-   * detection failed or if
-   * detection is not supported.
+   * The constructor determines the number of CPUs in the system. At the
+   * moment detection of CPUs is only implemented on Linux computers with the
+   * /proc filesystem and on Sun machines.  The number of CPUs present is set
+   * to one if detection failed or if detection is not supported.
    */
   MultithreadInfo ();
 
   /**
-   * The number of CPUs in the
-   * system.  It is one if
-   * detection is not implemented
-   * or failed.
+   * The number of CPUs in the system.  It is one if detection is not
+   * implemented or failed.
    *
-   * If it is one, although you
-   * are on a multi-processor
-   * machine, please refer to the
-   * documentation in
-   * <tt>multithread_info.cc</tt>
-   * near to the <tt>error</tt> directive.
+   * If it is one, although you are on a multi-processor machine, please refer
+   * to the documentation in <tt>multithread_info.cc</tt> near to the
+   * <tt>error</tt> directive.
    */
   const unsigned int n_cpus;
 
@@ -88,12 +72,12 @@ public:
    * determined how many threads to use, for example when assembling matrices
    * in MatrixCreator or generating output in DataOut. To this end,
    * n_default_threads is set to n_cpus at the start of the program, but used
-   * programs could set it to a different value in their main()
-   * function. However, since almost all of deal.II has now been converted to
-   * a task-based parallelism model, this variable is no longer used in the
-   * library. Instead, the task scheduling methods use the n_threads()
-   * function as a guide to how many threads to use, and the current variable
-   * is now deprecated.
+   * programs could set it to a different value in their main() function.
+   * However, since almost all of deal.II has now been converted to a task-
+   * based parallelism model, this variable is no longer used in the library.
+   * Instead, the task scheduling methods use the n_threads() function as a
+   * guide to how many threads to use, and the current variable is now
+   * deprecated.
    *
    * @deprecated: Use n_threads() to query the number of threads to use (if
    * you wanted to read this variable), and set_thread_limit() to limit it (if
@@ -109,43 +93,34 @@ public:
   unsigned int n_threads() const;
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
-   * object. Since sometimes
-   * the size of objects can
-   * not be determined exactly
-   * (for example: what is the
-   * memory consumption of an
-   * STL <tt>std::map</tt> type with a
-   * certain number of
-   * elements?), this is only
-   * an estimate. however often
-   * quite close to the true
-   * value.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. Since sometimes the size of objects can not be determined exactly
+   * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+   * type with a certain number of elements?), this is only an estimate.
+   * however often quite close to the true value.
    */
   static std::size_t memory_consumption ();
 
   /**
-   * Sets the maximum number of threads to be used
-   * to the minimum of the environment variable DEAL_II_NUM_THREADS
-   * and the given parameter (if not the default value). This
-   * affects the initialization of the TBB. If neither is given, the
-   * default from TBB is used (based on the number of cores in the system).
+   * Sets the maximum number of threads to be used to the minimum of the
+   * environment variable DEAL_II_NUM_THREADS and the given parameter (if not
+   * the default value). This affects the initialization of the TBB. If
+   * neither is given, the default from TBB is used (based on the number of
+   * cores in the system).
    *
    * This routine is called automatically by MPI_InitFinalize. Due to
    * limitations in the way TBB can be controlled, only the first call to this
-   * method will have any effect. Use the parameter of the MPI_InitFinalize
-   * if you have an MPI based code.
+   * method will have any effect. Use the parameter of the MPI_InitFinalize if
+   * you have an MPI based code.
    */
   void set_thread_limit(const unsigned int max_threads = numbers::invalid_unsigned_int);
 
 
   /**
-   * Returns if the TBB is running using a single thread either
-   * because of thread affinity or because it is set via a call
-   * to set_thread_limit. This is used in the PETScWrappers to
-   * avoid using the interface that is not thread-safe.
+   * Returns if the TBB is running using a single thread either because of
+   * thread affinity or because it is set via a call to set_thread_limit. This
+   * is used in the PETScWrappers to avoid using the interface that is not
+   * thread-safe.
    */
   bool is_running_single_threaded();
   /**
@@ -156,14 +131,9 @@ public:
 private:
 
   /**
-   * Private function to determine
-   * the number of CPUs.
-   * Implementation for Linux, OSF,
-   * SGI, and Sun machines; if no
-   * detection of the number of CPUs is
-   * supported, or if detection
-   * fails, this function returns
-   * one.
+   * Private function to determine the number of CPUs. Implementation for
+   * Linux, OSF, SGI, and Sun machines; if no detection of the number of CPUs
+   * is supported, or if detection fails, this function returns one.
    */
   static unsigned int get_n_cpus();
 
@@ -177,8 +147,8 @@ private:
 
 /**
  * Global variable of type <tt>MultithreadInfo</tt> which you may ask for the
- * number of CPUs in your system, as well as for the default number of
- * threads that multithreaded functions shall use.
+ * number of CPUs in your system, as well as for the default number of threads
+ * that multithreaded functions shall use.
  *
  * @ingroup threads
  */
index ad629db5b20912d877a1385bc8e9f862fe45221f..a516a965a70c6712492550b946ecf3ce0226f69d 100644 (file)
@@ -28,24 +28,24 @@ DEAL_II_NAMESPACE_OPEN
 class AnyData;
 
 /**
- * @deprecated The use of this class is deprecated and AnyData should
- * be used instead. It is not only more flexible, the way constness
- * was assured in this class never worked the way it was
- * intended. Therefore, the according checks have been disabled.
+ * @deprecated The use of this class is deprecated and AnyData should be used
+ * instead. It is not only more flexible, the way constness was assured in
+ * this class never worked the way it was intended. Therefore, the according
+ * checks have been disabled.
  *
- * This class is a collection of DATA objects. Each of the pointers
- * has a name associated, enabling identification by this name rather
- * than the index in the vector only.
+ * This class is a collection of DATA objects. Each of the pointers has a name
+ * associated, enabling identification by this name rather than the index in
+ * the vector only.
  *
- * Note that it is the actual data stored in this object. Therefore,
- * for storing vectors and other large objects, it should be
- * considered to use SmartPointer or boost::shared_ptr for DATA.
+ * Note that it is the actual data stored in this object. Therefore, for
+ * storing vectors and other large objects, it should be considered to use
+ * SmartPointer or boost::shared_ptr for DATA.
  *
- * Objects of this kind have a smart way of treating constness: if a
- * const data object is added or a const NamedData is supplied with
- * merge(), the object will henceforth consider itself as const
- * (#is_constant will be true). Thus, any subsequent modification will
- * be illegal and ExcConstantObject will be raised in debug mode.
+ * Objects of this kind have a smart way of treating constness: if a const
+ * data object is added or a const NamedData is supplied with merge(), the
+ * object will henceforth consider itself as const (#is_constant will be
+ * true). Thus, any subsequent modification will be illegal and
+ * ExcConstantObject will be raised in debug mode.
  *
  * @author Guido Kanschat, 2007, 2008, 2009
  */
@@ -53,15 +53,13 @@ template <typename DATA>
 class NamedData : public Subscriptor
 {
 public:
-  /** Standard constructor creating
-   * an empty object.
+  /**
+   * Standard constructor creating an empty object.
    */
   NamedData();
 
   /**
-   * Assignment operator, copying
-   * conversible data from another
-   * object.
+   * Assignment operator, copying conversible data from another object.
    */
   template <typename DATA2>
   NamedData<DATA> &operator = (const NamedData<DATA2> &other);
@@ -71,61 +69,45 @@ public:
    */
 //@{
   /**
-   * Add a new data item to the end
-   * of the collection.
+   * Add a new data item to the end of the collection.
    */
   void add(DATA &v, const std::string &name);
 
   /**
-   * Add a new constant data item
-   * to the end of the collection
-   * and make the collection
-   * constant.
+   * Add a new constant data item to the end of the collection and make the
+   * collection constant.
    */
   void add(const DATA &v, const std::string &name);
 
   /**
-   * Merge the data of another
-   * NamedData to the end of this
-   * object.
+   * Merge the data of another NamedData to the end of this object.
    *
-   * If the other object had
-   * #is_constant set, so will have
-   * this object after merge.
+   * If the other object had #is_constant set, so will have this object after
+   * merge.
    */
   template <typename DATA2>
   void merge(NamedData<DATA2> &);
   /**
-   * Merge the data of another
-   * NamedData to the end of this
-   * object.
+   * Merge the data of another NamedData to the end of this object.
    *
-   * After this operation, all
-   * data in this object will be
-   * treated as const.
+   * After this operation, all data in this object will be treated as const.
    */
   template <typename DATA2>
   void merge(const NamedData<DATA2> &);
 //@}
   /**
-   * \name Accessing and querying
-   * contents
+   * \name Accessing and querying contents
    */
 //@{
 /// Number of stored data objects.
   unsigned int size() const;
 
   /**
-   * @brief Access to stored data
-   * object by index.
+   * @brief Access to stored data object by index.
    *
-   * @note This function throws an
-   * exception, if is_const()
-   * returns <tt>true</tt>. In such
-   * a case, either cast the
-   * NamedData object to a const
-   * reference, or use the function
-   * read() instead of this operator.
+   * @note This function throws an exception, if is_const() returns
+   * <tt>true</tt>. In such a case, either cast the NamedData object to a
+   * const reference, or use the function read() instead of this operator.
    */
   DATA &operator() (unsigned int i);
 
@@ -149,22 +131,16 @@ public:
   void print(OUT &o) const;
 //@}
   /**
-   * Exception indicating that a
-   * function expected a vector
-   * to have a certain name, but
-   * NamedData had a different
-   * name in that position.
+   * Exception indicating that a function expected a vector to have a certain
+   * name, but NamedData had a different name in that position.
    */
   DeclException2(ExcNameMismatch, int, std::string,
                  << "Name at position " << arg1 << " is not equal to " << arg2);
 
   /**
-   * Exception indicating that read
-   * access to stored data was
-   * attempted although the
-   * NamedData object contains
-   * const data and #is_constant
-   * was true.
+   * Exception indicating that read access to stored data was attempted
+   * although the NamedData object contains const data and #is_constant was
+   * true.
    */
   DeclException0(ExcConstantObject);
 
@@ -182,8 +158,8 @@ private:
 /**
  * Select data from NamedData corresponding to the attached name.
  *
- * Given a list of names to search for (provided by add()), objects of
- * this class provide an index list of the selected data.
+ * Given a list of names to search for (provided by add()), objects of this
+ * class provide an index list of the selected data.
  *
  * @author Guido Kanschat, 2009
  */
@@ -191,47 +167,35 @@ class NamedSelection
 {
 public:
   /**
-   * Add a new name to be searched
-   * for in NamedData.
+   * Add a new name to be searched for in NamedData.
    *
-   * @note Names will be added to
-   * the end of the current list.
+   * @note Names will be added to the end of the current list.
    */
   void add (const std::string &name);
 
   /**
-   * Create the index vector
-   * pointing into the NamedData
-   * object.
+   * Create the index vector pointing into the NamedData object.
    */
   template <typename DATA>
   void initialize(const NamedData<DATA> &data);
 
   /**
-   * Create the index vector
-   * pointing into the AnyData
-   * object.
+   * Create the index vector pointing into the AnyData object.
    */
   void initialize(const AnyData &data);
 
   /**
-   * The number of names in this
-   * object. This function may be
-   * used whether initialize() was
-   * called before or not.
+   * The number of names in this object. This function may be used whether
+   * initialize() was called before or not.
    */
   unsigned int size() const;
 
   /**
-   * Return the corresponding index
-   * in the NamedData object
-   * supplied to the last
-   * initialize(). It is an error
-   * if initialize() has not been
-   * called before.
+   * Return the corresponding index in the NamedData object supplied to the
+   * last initialize(). It is an error if initialize() has not been called
+   * before.
    *
-   * Indices are in the same order
-   * as the calls to add().
+   * Indices are in the same order as the calls to add().
    */
   unsigned int operator() (unsigned int i) const;
 
@@ -241,9 +205,7 @@ private:
    */
   std::vector<std::string> names;
   /**
-   * The index map generated by
-   * initialize() and accessed by
-   * operator().
+   * The index map generated by initialize() and accessed by operator().
    */
   std::vector<unsigned int> indices;
 };
index 45288e92b6cfd4ff98369452cc4cafddbfd44067..fca7d0ab0c8fc663e37850d97bcb6b93937c10a4 100644 (file)
@@ -25,18 +25,18 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * Namespace for the declaration of universal constants. Since the
- * availability in <tt>math.h</tt> is not always guaranteed, we put
- * them here. Since this file is included by <tt>base/config.h</tt>,
- * they are available to the whole library.
+ * availability in <tt>math.h</tt> is not always guaranteed, we put them here.
+ * Since this file is included by <tt>base/config.h</tt>, they are available
+ * to the whole library.
  *
  * The constants defined here are a subset of the <tt>M_XXX</tt> constants
  * sometimes declared in the system include file <tt>math.h</tt>, but without
  * the prefix <tt>M_</tt>.
  *
  * In addition to that, we declare  <tt>invalid_unsigned_int</tt> to be the
- * largest unsigned integer representable; this value is widely used in
- * the library as a marker for an invalid index, an invalid size of an
- * array, and similar purposes.
+ * largest unsigned integer representable; this value is widely used in the
+ * library as a marker for an invalid index, an invalid size of an array, and
+ * similar purposes.
  */
 namespace numbers
 {
@@ -91,68 +91,45 @@ namespace numbers
   static const double  SQRT1_2 = 0.70710678118654752440;
 
   /**
-   * Return @p true if the given
-   * value is a finite floating
-   * point number, i.e. is neither
-   * plus or minus infinity nor NaN
-   * (not a number).
+   * Return @p true if the given value is a finite floating point number, i.e.
+   * is neither plus or minus infinity nor NaN (not a number).
    *
-   * Note that the argument type of
-   * this function is
-   * <code>double</code>. In other
-   * words, if you give a very
-   * large number of type
-   * <code>long double</code>, this
-   * function may return
-   * <code>false</code> even if the
-   * number is finite with respect
-   * to type <code>long
-   * double</code>.
+   * Note that the argument type of this function is <code>double</code>. In
+   * other words, if you give a very large number of type <code>long
+   * double</code>, this function may return <code>false</code> even if the
+   * number is finite with respect to type <code>long double</code>.
    */
   bool is_finite (const double x);
 
   /**
-   * Return @p true if real and
-   * imaginary parts of the given
-   * complex number are finite.
+   * Return @p true if real and imaginary parts of the given complex number
+   * are finite.
    */
   bool is_finite (const std::complex<double> &x);
 
   /**
-   * Return @p true if real and
-   * imaginary parts of the given
-   * complex number are finite.
+   * Return @p true if real and imaginary parts of the given complex number
+   * are finite.
    */
   bool is_finite (const std::complex<float> &x);
 
   /**
-   * Return @p true if real and
-   * imaginary parts of the given
-   * complex number are finite.
+   * Return @p true if real and imaginary parts of the given complex number
+   * are finite.
    *
-   * Again may not work correctly if
-   * real or imaginary parts are very
-   * large numbers that are infinite in
-   * terms of <code>double</code>, but
-   * finite with respect to
-   * <code>long double</code>.
+   * Again may not work correctly if real or imaginary parts are very large
+   * numbers that are infinite in terms of <code>double</code>, but finite
+   * with respect to <code>long double</code>.
    */
   bool is_finite (const std::complex<long double> &x);
 
   /**
-   * A structure that, together with
-   * its partial specializations
-   * NumberTraits<std::complex<number> >,
-   * provides traits and member
-   * functions that make it possible
-   * to write templates that work on
-   * both real number types and
-   * complex number types. This
-   * template is mostly used to
-   * implement linear algebra classes
-   * such as vectors and matrices
-   * that work for both real and
-   * complex numbers.
+   * A structure that, together with its partial specializations
+   * NumberTraits<std::complex<number> >, provides traits and member functions
+   * that make it possible to write templates that work on both real number
+   * types and complex number types. This template is mostly used to implement
+   * linear algebra classes such as vectors and matrices that work for both
+   * real and complex numbers.
    *
    * @author Wolfgang Bangerth, 2007
    */
@@ -160,52 +137,38 @@ namespace numbers
   struct NumberTraits
   {
     /**
-     * A flag that specifies whether the
-     * template type given to this class is
-     * complex or real. Since the general
-     * template is selected for non-complex
-     * types, the answer is
-     * <code>false</code>.
+     * A flag that specifies whether the template type given to this class is
+     * complex or real. Since the general template is selected for non-complex
+     * types, the answer is <code>false</code>.
      */
     static const bool is_complex = false;
 
     /**
-     * For this data type, typedef the
-     * corresponding real type. Since the
-     * general template is selected for all
-     * data types that are not
-     * specializations of std::complex<T>,
-     * the underlying type must be
-     * real-values, so the real_type is
-     * equal to the underlying type.
+     * For this data type, typedef the corresponding real type. Since the
+     * general template is selected for all data types that are not
+     * specializations of std::complex<T>, the underlying type must be real-
+     * values, so the real_type is equal to the underlying type.
      */
     typedef number real_type;
 
     /**
-     * Return the complex-conjugate of the
-     * given number. Since the general
-     * template is selected if number is
-     * not a complex data type, this
-     * function simply returns the given
-     * number.
+     * Return the complex-conjugate of the given number. Since the general
+     * template is selected if number is not a complex data type, this
+     * function simply returns the given number.
      */
     static
     const number &conjugate (const number &x);
 
     /**
-     * Return the square of the absolute
-     * value of the given number. Since the
-     * general template is chosen for types
-     * not equal to std::complex, this
-     * function simply returns the square
-     * of the given number.
+     * Return the square of the absolute value of the given number. Since the
+     * general template is chosen for types not equal to std::complex, this
+     * function simply returns the square of the given number.
      */
     static
     real_type abs_square (const number &x);
 
     /**
-     * Return the absolute value of a
-     * number.
+     * Return the absolute value of a number.
      */
     static
     real_type abs (const number &x);
@@ -213,10 +176,8 @@ namespace numbers
 
 
   /**
-   * Specialization of the general
-   * NumberTraits class that provides the
-   * relevant information if the underlying
-   * data type is std::complex<T>.
+   * Specialization of the general NumberTraits class that provides the
+   * relevant information if the underlying data type is std::complex<T>.
    *
    * @author Wolfgang Bangerth, 2007
    */
@@ -224,51 +185,38 @@ namespace numbers
   struct NumberTraits<std::complex<number> >
   {
     /**
-     * A flag that specifies whether the
-     * template type given to this class is
-     * complex or real. Since this
-     * specialization of the general
-     * template is selected for complex
-     * types, the answer is
-     * <code>true</code>.
+     * A flag that specifies whether the template type given to this class is
+     * complex or real. Since this specialization of the general template is
+     * selected for complex types, the answer is <code>true</code>.
      */
     static const bool is_complex = true;
 
     /**
-     * For this data type, typedef the
-     * corresponding real type. Since this
-     * specialization of the template is
-     * selected for number types
-     * std::complex<T>, the real type is
-     * equal to the type used to store the
-     * two components of the complex
-     * number.
+     * For this data type, typedef the corresponding real type. Since this
+     * specialization of the template is selected for number types
+     * std::complex<T>, the real type is equal to the type used to store the
+     * two components of the complex number.
      */
     typedef number real_type;
 
     /**
-     * Return the complex-conjugate of the
-     * given number.
+     * Return the complex-conjugate of the given number.
      */
     static
     std::complex<number> conjugate (const std::complex<number> &x);
 
     /**
-     * Return the square of the absolute
-     * value of the given number. Since
-     * this specialization of the general
-     * template is chosen for types equal
-     * to std::complex, this function
-     * returns the product of a number and
-     * its complex conjugate.
+     * Return the square of the absolute value of the given number. Since this
+     * specialization of the general template is chosen for types equal to
+     * std::complex, this function returns the product of a number and its
+     * complex conjugate.
      */
     static
     real_type abs_square (const std::complex<number> &x);
 
 
     /**
-     * Return the absolute value of a
-     * complex number.
+     * Return the absolute value of a complex number.
      */
     static
     real_type abs (const std::complex<number> &x);
index 6b03c09d7d507f1f0c85b1051601b2c2b2307933..b512888fe4396baf518728b3972b12ba66a7b805 100644 (file)
@@ -45,17 +45,14 @@ namespace parallel
   namespace internal
   {
     /**
-     * Convert a function object of type F
-     * into an object that can be applied to
-     * all elements of a range of synchronous
-     * iterators.
+     * Convert a function object of type F into an object that can be applied
+     * to all elements of a range of synchronous iterators.
      */
     template <typename F>
     struct Body
     {
       /**
-       * Constructor. Take and package the
-       * given function object.
+       * Constructor. Take and package the given function object.
        */
       Body (const F &f)
         :
@@ -78,8 +75,7 @@ namespace parallel
       const F f;
 
       /**
-       * Apply F to a set of iterators with
-       * two elements.
+       * Apply F to a set of iterators with two elements.
        */
       template <typename I1, typename I2>
       static
@@ -91,8 +87,7 @@ namespace parallel
       }
 
       /**
-       * Apply F to a set of iterators with
-       * three elements.
+       * Apply F to a set of iterators with three elements.
        */
       template <typename I1, typename I2, typename I3>
       static
@@ -105,8 +100,7 @@ namespace parallel
       }
 
       /**
-       * Apply F to a set of iterators with
-       * three elements.
+       * Apply F to a set of iterators with three elements.
        */
       template <typename I1, typename I2,
                 typename I3, typename I4>
@@ -123,12 +117,9 @@ namespace parallel
 
 
     /**
-     * Take a function object and create a
-     * Body object from it. We do this in
-     * this helper function since
-     * alternatively we would have to specify
-     * the actual data type of F -- which for
-     * function objects is often
+     * Take a function object and create a Body object from it. We do this in
+     * this helper function since alternatively we would have to specify the
+     * actual data type of F -- which for function objects is often
      * extraordinarily complicated.
      */
     template <typename F>
@@ -139,37 +130,26 @@ namespace parallel
   }
 
   /**
-   * An algorithm that performs the action
-   * <code>*out++ = predicate(*in++)</code>
-   * where the <code>in</code> iterator
-   * ranges over the given input range.
+   * An algorithm that performs the action <code>*out++ =
+   * predicate(*in++)</code> where the <code>in</code> iterator ranges over
+   * the given input range.
    *
-   * This algorithm does pretty much what
-   * std::transform does. The difference is
-   * that the function can run in parallel
-   * when deal.II is configured to use
-   * multiple threads.
+   * This algorithm does pretty much what std::transform does. The difference
+   * is that the function can run in parallel when deal.II is configured to
+   * use multiple threads.
    *
-   * If running in parallel, the iterator range
-   * is split into several chunks that are
-   * each packaged up as a task and given to
-   * the Threading Building Blocks scheduler
-   * to work on as compute resources are
-   * available. The function returns once all
-   * chunks have been worked on. The last
-   * argument denotes the minimum number of
-   * elements of the iterator range per
-   * task; the number must be
-   * large enough to amortize the startup
-   * cost of new tasks, and small enough to
-   * ensure that tasks can be
-   * reasonably load balanced.
+   * If running in parallel, the iterator range is split into several chunks
+   * that are each packaged up as a task and given to the Threading Building
+   * Blocks scheduler to work on as compute resources are available. The
+   * function returns once all chunks have been worked on. The last argument
+   * denotes the minimum number of elements of the iterator range per task;
+   * the number must be large enough to amortize the startup cost of new
+   * tasks, and small enough to ensure that tasks can be reasonably load
+   * balanced.
    *
-   * For a discussion of the kind of
-   * problems to which this function
-   * is applicable, see the
-   * @ref threads "Parallel computing with multiple processors"
-   * module.
+   * For a discussion of the kind of problems to which this function is
+   * applicable, see the @ref threads "Parallel computing with multiple
+   * processors" module.
    */
   template <typename InputIterator,
             typename OutputIterator,
@@ -203,39 +183,26 @@ namespace parallel
 
 
   /**
-   * An algorithm that performs the action
-   * <code>*out++ = predicate(*in1++, *in2++)</code>
-   * where the <code>in1</code> iterator
-   * ranges over the given input
-   * range, using the parallel for
-   * operator of tbb.
+   * An algorithm that performs the action <code>*out++ = predicate(*in1++,
+   * *in2++)</code> where the <code>in1</code> iterator ranges over the given
+   * input range, using the parallel for operator of tbb.
    *
-   * This algorithm does pretty much what
-   * std::transform does. The difference is
-   * that the function can run in parallel
-   * when deal.II is configured to use
-   * multiple threads.
+   * This algorithm does pretty much what std::transform does. The difference
+   * is that the function can run in parallel when deal.II is configured to
+   * use multiple threads.
    *
-   * If running in parallel, the iterator range
-   * is split into several chunks that are
-   * each packaged up as a task and given to
-   * the Threading Building Blocks scheduler
-   * to work on as compute resources are
-   * available. The function returns once all
-   * chunks have been worked on. The last
-   * argument denotes the minimum number of
-   * elements of the iterator range per
-   * task; the number must be
-   * large enough to amortize the startup
-   * cost of new tasks, and small enough to
-   * ensure that tasks can be
-   * reasonably load balanced.
+   * If running in parallel, the iterator range is split into several chunks
+   * that are each packaged up as a task and given to the Threading Building
+   * Blocks scheduler to work on as compute resources are available. The
+   * function returns once all chunks have been worked on. The last argument
+   * denotes the minimum number of elements of the iterator range per task;
+   * the number must be large enough to amortize the startup cost of new
+   * tasks, and small enough to ensure that tasks can be reasonably load
+   * balanced.
    *
-   * For a discussion of the kind of
-   * problems to which this function
-   * is applicable, see the
-   * @ref threads "Parallel computing with multiple processors"
-   * module.
+   * For a discussion of the kind of problems to which this function is
+   * applicable, see the @ref threads "Parallel computing with multiple
+   * processors" module.
    */
   template <typename InputIterator1,
             typename InputIterator2,
@@ -273,37 +240,26 @@ namespace parallel
 
 
   /**
-   * An algorithm that performs the action
-   * <code>*out++ = predicate(*in1++, *in2++, *in3++)</code>
-   * where the <code>in1</code> iterator
-   * ranges over the given input range.
+   * An algorithm that performs the action <code>*out++ = predicate(*in1++,
+   * *in2++, *in3++)</code> where the <code>in1</code> iterator ranges over
+   * the given input range.
    *
-   * This algorithm does pretty much what
-   * std::transform does. The difference is
-   * that the function can run in parallel
-   * when deal.II is configured to use
-   * multiple threads.
+   * This algorithm does pretty much what std::transform does. The difference
+   * is that the function can run in parallel when deal.II is configured to
+   * use multiple threads.
    *
-   * If running in parallel, the iterator range
-   * is split into several chunks that are
-   * each packaged up as a task and given to
-   * the Threading Building Blocks scheduler
-   * to work on as compute resources are
-   * available. The function returns once all
-   * chunks have been worked on. The last
-   * argument denotes the minimum number of
-   * elements of the iterator range per
-   * task; the number must be
-   * large enough to amortize the startup
-   * cost of new tasks, and small enough to
-   * ensure that tasks can be
-   * reasonably load balanced.
+   * If running in parallel, the iterator range is split into several chunks
+   * that are each packaged up as a task and given to the Threading Building
+   * Blocks scheduler to work on as compute resources are available. The
+   * function returns once all chunks have been worked on. The last argument
+   * denotes the minimum number of elements of the iterator range per task;
+   * the number must be large enough to amortize the startup cost of new
+   * tasks, and small enough to ensure that tasks can be reasonably load
+   * balanced.
    *
-   * For a discussion of the kind of
-   * problems to which this function
-   * is applicable, see the
-   * @ref threads "Parallel computing with multiple processors"
-   * module.
+   * For a discussion of the kind of problems to which this function is
+   * applicable, see the @ref threads "Parallel computing with multiple
+   * processors" module.
    */
   template <typename InputIterator1,
             typename InputIterator2,
@@ -346,8 +302,8 @@ namespace parallel
   {
 #ifdef DEAL_II_WITH_THREADS
     /**
-     * Take a range argument and call the
-     * given function with its begin and end.
+     * Take a range argument and call the given function with its begin and
+     * end.
      */
     template <typename RangeType, typename Function>
     void apply_to_subranges (const tbb::blocked_range<RangeType> &range,
@@ -360,39 +316,25 @@ namespace parallel
 
 
   /**
-   * This function applies the given function
-   * argument @p f to all elements in the range
-   * <code>[begin,end)</code> and may do so
-   * in parallel.
+   * This function applies the given function argument @p f to all elements in
+   * the range <code>[begin,end)</code> and may do so in parallel.
    *
-   * However, in many cases it is not
-   * efficient to call a function on each
-   * element, so this function calls the
-   * given function object on sub-ranges. In
-   * other words: if the given range
-   * <code>[begin,end)</code> is smaller than
-   * grainsize or if multithreading is not
-   * enabled, then we call
-   * <code>f(begin,end)</code>; otherwise, we
-   * may execute, possibly in %parallel, a
-   * sequence of calls <code>f(b,e)</code>
-   * where <code>[b,e)</code> are
-   * subintervals of <code>[begin,end)</code>
-   * and the collection of calls we do to
-   * <code>f(.,.)</code> will happen on
-   * disjoint subintervals that collectively
-   * cover the original interval
+   * However, in many cases it is not efficient to call a function on each
+   * element, so this function calls the given function object on sub-ranges.
+   * In other words: if the given range <code>[begin,end)</code> is smaller
+   * than grainsize or if multithreading is not enabled, then we call
+   * <code>f(begin,end)</code>; otherwise, we may execute, possibly in
+   * %parallel, a sequence of calls <code>f(b,e)</code> where
+   * <code>[b,e)</code> are subintervals of <code>[begin,end)</code> and the
+   * collection of calls we do to <code>f(.,.)</code> will happen on disjoint
+   * subintervals that collectively cover the original interval
    * <code>[begin,end)</code>.
    *
-   * Oftentimes, the called function will of
-   * course have to get additional
-   * information, such as the object to work
-   * on for a given value of the iterator
-   * argument. This can be achieved by
-   * <i>binding</i> certain arguments. For
-   * example, here is an implementation of a
-   * matrix-vector multiplication $y=Ax$ for
-   * a full matrix $A$ and vectors $x,y$:
+   * Oftentimes, the called function will of course have to get additional
+   * information, such as the object to work on for a given value of the
+   * iterator argument. This can be achieved by <i>binding</i> certain
+   * arguments. For example, here is an implementation of a matrix-vector
+   * multiplication $y=Ax$ for a full matrix $A$ and vectors $x,y$:
    * @code
    *   void matrix_vector_product (const FullMatrix &A,
    *                               const Vector     &x,
@@ -420,44 +362,28 @@ namespace parallel
    *   }
    * @endcode
    *
-   * Note how we use the
-   * <code>std_cxx11::bind</code> function to
-   * convert
-   * <code>mat_vec_on_subranged</code> from a
-   * function that takes 5 arguments to one
-   * taking 2 by binding the remaining
-   * arguments (the modifiers
-   * <code>std_cxx11::ref</code> and
-   * <code>std_cxx11::cref</code> make sure
-   * that the enclosed variables are actually
-   * passed by reference and constant
-   * reference, rather than by value). The
-   * resulting function object requires only
-   * two arguments, begin_row and end_row,
-   * with all other arguments fixed.
+   * Note how we use the <code>std_cxx11::bind</code> function to convert
+   * <code>mat_vec_on_subranged</code> from a function that takes 5 arguments
+   * to one taking 2 by binding the remaining arguments (the modifiers
+   * <code>std_cxx11::ref</code> and <code>std_cxx11::cref</code> make sure
+   * that the enclosed variables are actually passed by reference and constant
+   * reference, rather than by value). The resulting function object requires
+   * only two arguments, begin_row and end_row, with all other arguments
+   * fixed.
    *
-   * The code, if in single-thread mode, will
-   * call <code>mat_vec_on_subranges</code>
-   * on the entire range
-   * <code>[0,n_rows)</code> exactly once. In
-   * multi-threaded mode, however, it may be
-   * called multiple times on subranges of
-   * this interval, possibly allowing more
-   * than one CPU core to take care of part
-   * of the work.
+   * The code, if in single-thread mode, will call
+   * <code>mat_vec_on_subranges</code> on the entire range
+   * <code>[0,n_rows)</code> exactly once. In multi-threaded mode, however, it
+   * may be called multiple times on subranges of this interval, possibly
+   * allowing more than one CPU core to take care of part of the work.
    *
-   * The @p grainsize argument (50 in the
-   * example above) makes sure that subranges
-   * do not become too small, to avoid
-   * spending more time on scheduling
-   * subranges to CPU resources than on doing
-   * actual work.
+   * The @p grainsize argument (50 in the example above) makes sure that
+   * subranges do not become too small, to avoid spending more time on
+   * scheduling subranges to CPU resources than on doing actual work.
    *
-   * For a discussion of the kind of
-   * problems to which this function
-   * is applicable, see also the
-   * @ref threads "Parallel computing with multiple processors"
-   * module.
+   * For a discussion of the kind of problems to which this function is
+   * applicable, see also the @ref threads "Parallel computing with multiple
+   * processors" module.
    */
   template <typename RangeType, typename Function>
   void apply_to_subranges (const RangeType                          &begin,
@@ -520,34 +446,28 @@ namespace parallel
   struct ParallelForInteger
   {
     /**
-     * Destructor. Made virtual to ensure that derived classes also
-     * have virtual destructors.
+     * Destructor. Made virtual to ensure that derived classes also have
+     * virtual destructors.
      */
     virtual ~ParallelForInteger ();
 
     /**
-     * This function runs the for loop over the
-     * given range <tt>[lower,upper)</tt>,
-     * possibly in parallel when end-begin is
-     * larger than the minimum parallel grain
-     * size. This function is marked const because
-     * it any operation that changes the data of a
-     * derived class will inherently not be
-     * thread-safe when several threads work with
-     * the same data simultaneously.
+     * This function runs the for loop over the given range
+     * <tt>[lower,upper)</tt>, possibly in parallel when end-begin is larger
+     * than the minimum parallel grain size. This function is marked const
+     * because it any operation that changes the data of a derived class will
+     * inherently not be thread-safe when several threads work with the same
+     * data simultaneously.
      */
     void apply_parallel (const std::size_t begin,
                          const std::size_t end,
                          const std::size_t minimum_parallel_grain_size) const;
 
     /**
-     * Virtual function for working on subrange to
-     * be defined in a derived class.  This
-     * function is marked const because it any
-     * operation that changes the data of a
-     * derived class will inherently not be
-     * thread-safe when several threads work with
-     * the same data simultaneously.
+     * Virtual function for working on subrange to be defined in a derived
+     * class.  This function is marked const because it any operation that
+     * changes the data of a derived class will inherently not be thread-safe
+     * when several threads work with the same data simultaneously.
      */
     virtual void apply_to_subrange (const std::size_t,
                                     const std::size_t) const = 0;
@@ -559,39 +479,28 @@ namespace parallel
   {
 #ifdef DEAL_II_WITH_THREADS
     /**
-     * A class that conforms to the Body
-     * requirements of the TBB
-     * parallel_reduce function. The first
-     * template argument denotes the type on
-     * which the reduction is to be done. The
-     * second denotes the type of the
-     * function object that shall be called
-     * for each subrange.
+     * A class that conforms to the Body requirements of the TBB
+     * parallel_reduce function. The first template argument denotes the type
+     * on which the reduction is to be done. The second denotes the type of
+     * the function object that shall be called for each subrange.
      */
     template <typename ResultType,
               typename Function>
     struct ReductionOnSubranges
     {
       /**
-       * A variable that will hold the
-       * result of the reduction.
+       * A variable that will hold the result of the reduction.
        */
       ResultType result;
 
       /**
-       * Constructor. Take the function
-       * object to call on each sub-range
-       * as well as the neutral element
-       * with respect to the reduction
-       * operation.
+       * Constructor. Take the function object to call on each sub-range as
+       * well as the neutral element with respect to the reduction operation.
        *
-       * The second argument denotes a
-       * function object that will be used
-       * to reduce the result of two
-       * computations into one number. An
-       * example if we want to simply
-       * accumulate integer results would
-       * be std::plus<int>().
+       * The second argument denotes a function object that will be used to
+       * reduce the result of two computations into one number. An example if
+       * we want to simply accumulate integer results would be
+       * std::plus<int>().
        */
       template <typename Reductor>
       ReductionOnSubranges (const Function &f,
@@ -605,8 +514,7 @@ namespace parallel
       {}
 
       /**
-       * Splitting constructor. See the TBB
-       * book for more details about this.
+       * Splitting constructor. See the TBB book for more details about this.
        */
       ReductionOnSubranges (const ReductionOnSubranges &r,
                             tbb::split)
@@ -618,9 +526,8 @@ namespace parallel
       {}
 
       /**
-       * Join operation: merge the results
-       * from computations on different
-       * sub-intervals.
+       * Join operation: merge the results from computations on different sub-
+       * intervals.
        */
       void join (const ReductionOnSubranges &r)
       {
@@ -628,8 +535,7 @@ namespace parallel
       }
 
       /**
-       * Execute the given function on the
-       * specified range.
+       * Execute the given function on the specified range.
        */
       template <typename RangeType>
       void operator () (const tbb::blocked_range<RangeType> &range)
@@ -640,25 +546,20 @@ namespace parallel
 
     private:
       /**
-       * The function object to call on
-       * every sub-range.
+       * The function object to call on every sub-range.
        */
       const Function f;
 
       /**
-       * The neutral element with respect
-       * to the reduction operation. This
-       * is needed when calling the
-       * splitting constructor since we
-       * have to re-set the result variable
-       * in this case.
+       * The neutral element with respect to the reduction operation. This is
+       * needed when calling the splitting constructor since we have to re-set
+       * the result variable in this case.
        */
       const ResultType neutral_element;
 
       /**
-       * The function object to be used to
-       * reduce the result of two calls
-       * into one number.
+       * The function object to be used to reduce the result of two calls into
+       * one number.
        */
       const std_cxx11::function<ResultType (ResultType, ResultType)> reductor;
     };
@@ -667,20 +568,14 @@ namespace parallel
 
 
   /**
-   * This function works a lot like the
-   * apply_to_subranges(), but it allows to
-   * accumulate numerical results computed on
-   * each subrange into one number. The type
-   * of this number is given by the
-   * ResultType template argument that needs
-   * to be explicitly specified.
+   * This function works a lot like the apply_to_subranges(), but it allows to
+   * accumulate numerical results computed on each subrange into one number.
+   * The type of this number is given by the ResultType template argument that
+   * needs to be explicitly specified.
    *
-   * An example of use of this function is to
-   * compute the value of the expression $x^T
-   * A x$ for a square matrix $A$ and a
-   * vector $x$. The sum over rows can be
-   * parallelized and the whole code might
-   * look like this:
+   * An example of use of this function is to compute the value of the
+   * expression $x^T A x$ for a square matrix $A$ and a vector $x$. The sum
+   * over rows can be parallelized and the whole code might look like this:
    * @code
    *   void matrix_norm (const FullMatrix &A,
    *                     const Vector     &x)
@@ -710,41 +605,25 @@ namespace parallel
    *   }
    * @endcode
    *
-   * Here,
-   * <code>mat_norm_sqr_on_subranges</code>
-   * is called on the entire range
-   * <code>[0,A.n_rows())</code> if this
-   * range is less than the minimum grainsize
-   * (above chosen as 50) or if deal.II is
-   * configured to not use
-   * multithreading. Otherwise, it may be
-   * called on subsets of the given range,
-   * with results from the individual
-   * subranges accumulated internally.
+   * Here, <code>mat_norm_sqr_on_subranges</code> is called on the entire
+   * range <code>[0,A.n_rows())</code> if this range is less than the minimum
+   * grainsize (above chosen as 50) or if deal.II is configured to not use
+   * multithreading. Otherwise, it may be called on subsets of the given
+   * range, with results from the individual subranges accumulated internally.
    *
-   * @warning If ResultType is a floating point
-   * type, then accumulation is not an
-   * associative operation. In other words,
-   * if the given function object is called
-   * three times on three subranges,
-   * returning values $a,b,c$, then the
-   * returned result of this function is
-   * $(a+b)+c$. However, depending on how the
-   * three sub-tasks are distributed on
-   * available CPU resources, the result may
-   * also be $(a+c)+b$ or any other
-   * permutation; because floating point
-   * addition is not associative (as opposed, of
-   * course, to addition of real %numbers),
-   * the result of invoking this function
-   * several times may differ on the order of
-   * round-off.
+   * @warning If ResultType is a floating point type, then accumulation is not
+   * an associative operation. In other words, if the given function object is
+   * called three times on three subranges, returning values $a,b,c$, then the
+   * returned result of this function is $(a+b)+c$. However, depending on how
+   * the three sub-tasks are distributed on available CPU resources, the
+   * result may also be $(a+c)+b$ or any other permutation; because floating
+   * point addition is not associative (as opposed, of course, to addition of
+   * real %numbers), the result of invoking this function several times may
+   * differ on the order of round-off.
    *
-   * For a discussion of the kind of
-   * problems to which this function
-   * is applicable, see also the
-   * @ref threads "Parallel computing with multiple processors"
-   * module.
+   * For a discussion of the kind of problems to which this function is
+   * applicable, see also the @ref threads "Parallel computing with multiple
+   * processors" module.
    */
   template <typename ResultType, typename RangeType, typename Function>
   ResultType accumulate_from_subranges (const Function &f,
@@ -783,29 +662,18 @@ namespace internal
   namespace Vector
   {
     /**
-     * If we do computations on vectors in
-     * parallel (say, we add two vectors to
-     * get a third, and we do the loop over
-     * all elements in parallel), then this
-     * variable determines the minimum number
-     * of elements for which it is profitable
-     * to split a range of elements any
-     * further to distribute to different
-     * threads.
+     * If we do computations on vectors in parallel (say, we add two vectors
+     * to get a third, and we do the loop over all elements in parallel), then
+     * this variable determines the minimum number of elements for which it is
+     * profitable to split a range of elements any further to distribute to
+     * different threads.
      *
-     * This variable is available as
-     * a global writable variable in
-     * order to allow the testsuite
-     * to also test the parallel
-     * case. By default, it is set to
-     * several thousand elements,
-     * which is a case that the
-     * testsuite would not normally
-     * encounter. As a consequence,
-     * in the testsuite we set it to
-     * one -- a value that's hugely
-     * unprofitable but definitely
-     * tests parallel operations.
+     * This variable is available as a global writable variable in order to
+     * allow the testsuite to also test the parallel case. By default, it is
+     * set to several thousand elements, which is a case that the testsuite
+     * would not normally encounter. As a consequence, in the testsuite we set
+     * it to one -- a value that's hugely unprofitable but definitely tests
+     * parallel operations.
      */
     extern unsigned int minimum_parallel_grain_size;
   }
@@ -814,11 +682,8 @@ namespace internal
   namespace SparseMatrix
   {
     /**
-     * Like
-     * internal::Vector::minimum_parallel_grain_size,
-     * but now denoting the number of rows of
-     * a matrix that should be worked on as a
-     * minimum.
+     * Like internal::Vector::minimum_parallel_grain_size, but now denoting
+     * the number of rows of a matrix that should be worked on as a minimum.
      */
     extern unsigned int minimum_parallel_grain_size;
   }
index e3607b2733a1d17ead34cd37d8d513f657191e90..c608d0ec929549ea531aeb17b71a68b4e0acf375 100644 (file)
@@ -59,9 +59,9 @@ namespace Patterns
 
   /**
    * Base class to declare common interface. The purpose of this class is
-   * mostly to define the interface of patterns, and to force derived
-   * classes to have a <tt>clone</tt> function. It is thus, in the
-   * languages of the "Design Patterns" book (Gamma et al.), a "prototype".
+   * mostly to define the interface of patterns, and to force derived classes
+   * to have a <tt>clone</tt> function. It is thus, in the languages of the
+   * "Design Patterns" book (Gamma et al.), a "prototype".
    */
   class PatternBase
   {
@@ -83,9 +83,9 @@ namespace Patterns
 
     /**
      * Return a pointer to an exact copy of the object. This is necessary
-     * since we want to store objects of this type in containers, were we
-     * need to copy objects without knowledge of their actual data type (we
-     * only have pointers to the base class).
+     * since we want to store objects of this type in containers, were we need
+     * to copy objects without knowledge of their actual data type (we only
+     * have pointers to the base class).
      *
      * Ownership of the objects returned by this function is passed to the
      * caller of this function.
@@ -94,16 +94,15 @@ namespace Patterns
 
     /**
      * Determine an estimate for the memory consumption (in bytes) of this
-     * object. To avoid unnecessary overhead, we do not force derived
-     * classes to provide this function as a virtual overloaded one, but
-     * rather try to cast the present object to one of the known derived
-     * classes and if that fails then take the size of this base class
-     * instead and add 32 byte (this value is arbitrary, it should account
-     * for virtual function tables, and some possible data elements). Since
-     * there are usually not many thousands of objects of this type around,
-     * and since the memory_consumption mechanism is used to find out where
-     * memory in the range of many megabytes is, this seems like a
-     * reasonable approximation.
+     * object. To avoid unnecessary overhead, we do not force derived classes
+     * to provide this function as a virtual overloaded one, but rather try to
+     * cast the present object to one of the known derived classes and if that
+     * fails then take the size of this base class instead and add 32 byte
+     * (this value is arbitrary, it should account for virtual function
+     * tables, and some possible data elements). Since there are usually not
+     * many thousands of objects of this type around, and since the
+     * memory_consumption mechanism is used to find out where memory in the
+     * range of many megabytes is, this seems like a reasonable approximation.
      *
      * On the other hand, if you know that your class deviates from this
      * assumption significantly, you can still overload this function.
@@ -112,27 +111,26 @@ namespace Patterns
   };
 
   /**
-  * Returns pointer to the correct derived class based on description.
-  */
+   * Returns pointer to the correct derived class based on description.
+   */
   PatternBase *pattern_factory (const std::string &description);
 
   /**
    * Test for the string being an integer. If bounds are given to the
-   * constructor, then the integer given also needs to be within the
-   * interval specified by these bounds. Note that unlike common convention
-   * in the C++ standard library, both bounds of this interval are
-   * inclusive; the reason is that in practice in most cases, one needs
-   * closed intervals, but these can only be realized with inclusive bounds
-   * for non-integer values. We thus stay consistent by always using closed
-   * intervals.
+   * constructor, then the integer given also needs to be within the interval
+   * specified by these bounds. Note that unlike common convention in the C++
+   * standard library, both bounds of this interval are inclusive; the reason
+   * is that in practice in most cases, one needs closed intervals, but these
+   * can only be realized with inclusive bounds for non-integer values. We
+   * thus stay consistent by always using closed intervals.
    *
    * If the upper bound given to the constructor is smaller than the lower
    * bound, then the infinite interval is implied, i.e. every integer is
    * allowed.
    *
-   * Giving bounds may be useful if for example a value can only be
-   * positive and less than a reasonable upper bound (for example the
-   * number of refinement steps to be performed), or in many other cases.
+   * Giving bounds may be useful if for example a value can only be positive
+   * and less than a reasonable upper bound (for example the number of
+   * refinement steps to be performed), or in many other cases.
    */
   class Integer : public PatternBase
   {
@@ -152,10 +150,10 @@ namespace Patterns
     static const int max_int_value;
 
     /**
-     * Constructor. Bounds can be specified within which a valid parameter
-     * has to be. If the upper bound is smaller than the lower bound, then
-     * the infinite interval is meant. The default values are chosen such
-     * that no bounds are enforced on parameters.
+     * Constructor. Bounds can be specified within which a valid parameter has
+     * to be. If the upper bound is smaller than the lower bound, then the
+     * infinite interval is meant. The default values are chosen such that no
+     * bounds are enforced on parameters.
      */
     Integer (const int lower_bound = min_int_value,
              const int upper_bound = max_int_value);
@@ -167,9 +165,9 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. If bounds were specified to the constructor, then include
-     * them into this description.
+     * Return a description of the pattern that valid strings are expected to
+     * match. If bounds were specified to the constructor, then include them
+     * into this description.
      */
     virtual std::string description () const;
 
@@ -190,8 +188,8 @@ namespace Patterns
   private:
     /**
      * Value of the lower bound. A number that satisfies the @ref match
-     * operation of this class must be equal to this value or larger, if
-     * the bounds of the interval for a valid range.
+     * operation of this class must be equal to this value or larger, if the
+     * bounds of the interval for a valid range.
      */
     const int lower_bound;
 
@@ -209,61 +207,59 @@ namespace Patterns
   };
 
   /**
-   * Test for the string being a <tt>double</tt>. If bounds are given to
-   * the constructor, then the integer given also needs to be within the
-   * interval specified by these bounds. Note that unlike common convention
-   * in the C++ standard library, both bounds of this interval are
-   * inclusive; the reason is that in practice in most cases, one needs
-   * closed intervals, but these can only be realized with inclusive bounds
-   * for non-integer values. We thus stay consistent by always using closed
-   * intervals.
+   * Test for the string being a <tt>double</tt>. If bounds are given to the
+   * constructor, then the integer given also needs to be within the interval
+   * specified by these bounds. Note that unlike common convention in the C++
+   * standard library, both bounds of this interval are inclusive; the reason
+   * is that in practice in most cases, one needs closed intervals, but these
+   * can only be realized with inclusive bounds for non-integer values. We
+   * thus stay consistent by always using closed intervals.
    *
    * If the upper bound given to the constructor is smaller than the lower
    * bound, then the infinite interval is implied, i.e. every integer is
    * allowed.
    *
-   * Giving bounds may be useful if for example a value can only be
-   * positive and less than a reasonable upper bound (for example damping
-   * parameters are frequently only reasonable if between zero and one), or
-   * in many other cases.
+   * Giving bounds may be useful if for example a value can only be positive
+   * and less than a reasonable upper bound (for example damping parameters
+   * are frequently only reasonable if between zero and one), or in many other
+   * cases.
    */
   class Double : public PatternBase
   {
   public:
     /**
      * Minimal double value. If the <tt>std::numeric_limits</tt> class is
-     * available use this information to obtain the extremal values,
-     * otherwise set it so that this class understands that all values are
-     * allowed.
+     * available use this information to obtain the extremal values, otherwise
+     * set it so that this class understands that all values are allowed.
      */
     static const double min_double_value;
 
     /**
-     * Maximal double value. If the numeric_limits class is available use
-     * this information to obtain the extremal values, otherwise set it so
-     * that this class understands that all values are allowed.
+     * Maximal double value. If the numeric_limits class is available use this
+     * information to obtain the extremal values, otherwise set it so that
+     * this class understands that all values are allowed.
      */
     static const double max_double_value;
 
     /**
-     * Constructor. Bounds can be specified within which a valid parameter
-     * has to be. If the upper bound is smaller than the lower bound, then
-     * the infinite interval is meant. The default values are chosen such
-     * that no bounds are enforced on parameters.
+     * Constructor. Bounds can be specified within which a valid parameter has
+     * to be. If the upper bound is smaller than the lower bound, then the
+     * infinite interval is meant. The default values are chosen such that no
+     * bounds are enforced on parameters.
      */
     Double (const double lower_bound = min_double_value,
             const double upper_bound = max_double_value);
 
     /**
-     * Return <tt>true</tt> if the string is a number and its value is
-     * within the specified range.
+     * Return <tt>true</tt> if the string is a number and its value is within
+     * the specified range.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. If bounds were specified to the constructor, then include
-     * them into this description.
+     * Return a description of the pattern that valid strings are expected to
+     * match. If bounds were specified to the constructor, then include them
+     * into this description.
      */
     virtual std::string description () const;
 
@@ -284,8 +280,8 @@ namespace Patterns
   private:
     /**
      * Value of the lower bound. A number that satisfies the @ref match
-     * operation of this class must be equal to this value or larger, if
-     * the bounds of the interval for a valid range.
+     * operation of this class must be equal to this value or larger, if the
+     * bounds of the interval for a valid range.
      */
     const double lower_bound;
 
@@ -304,11 +300,10 @@ namespace Patterns
 
   /**
    * Test for the string being one of a sequence of values given like a
-   * regular expression. For example, if the string given to the
-   * constructor is <tt>"red|blue|black"</tt>, then the @ref match function
-   * returns <tt>true</tt> exactly if the string is either "red" or "blue"
-   * or "black". Spaces around the pipe signs do not matter and are
-   * eliminated.
+   * regular expression. For example, if the string given to the constructor
+   * is <tt>"red|blue|black"</tt>, then the @ref match function returns
+   * <tt>true</tt> exactly if the string is either "red" or "blue" or "black".
+   * Spaces around the pipe signs do not matter and are eliminated.
    */
   class Selection : public PatternBase
   {
@@ -326,8 +321,8 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. Here, this is the list of valid strings passed to the
+     * Return a description of the pattern that valid strings are expected to
+     * match. Here, this is the list of valid strings passed to the
      * constructor.
      */
     virtual std::string description () const;
@@ -354,8 +349,8 @@ namespace Patterns
 
   private:
     /**
-     * List of valid strings as passed to the constructor. We don't make
-     * this string constant, as we process it somewhat in the constructor.
+     * List of valid strings as passed to the constructor. We don't make this
+     * string constant, as we process it somewhat in the constructor.
      */
     std::string sequence;
 
@@ -368,11 +363,10 @@ namespace Patterns
 
   /**
    * This pattern matches a list of values separated by commas (or another
-   * string), each of which
-   * have to match a pattern given to the constructor. With two additional
-   * parameters, the number of elements this list has to have can be
-   * specified. If none is specified, the list may have zero or more
-   * entries.
+   * string), each of which have to match a pattern given to the constructor.
+   * With two additional parameters, the number of elements this list has to
+   * have can be specified. If none is specified, the list may have zero or
+   * more entries.
    */
   class List : public PatternBase
   {
@@ -403,15 +397,14 @@ namespace Patterns
     virtual ~List ();
 
     /**
-     * Return <tt>true</tt> if the
-     * string is a comma-separated list of strings each of which match the
-     * pattern given to the constructor.
+     * Return <tt>true</tt> if the string is a comma-separated list of strings
+     * each of which match the pattern given to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match.
+     * Return a description of the pattern that valid strings are expected to
+     * match.
      */
     virtual std::string description () const;
 
@@ -435,8 +428,10 @@ namespace Patterns
      */
     std::size_t memory_consumption () const;
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception.
@@ -477,15 +472,15 @@ namespace Patterns
   /**
    * This pattern matches a list of comma-separated values each of which
    * denotes a pair of key and value. Both key and value have to match a
-   * pattern given to the constructor. For each entry of the map,
-   * parameters have to be entered in the form <code>key: value</code>. In
-   * other words, a map is described in the form
-   * <code>key1: value1, key2: value2, key3: value3, ...</code>. A constructor
-   * argument allows to choose a delimiter between pairs other than the comma.
+   * pattern given to the constructor. For each entry of the map, parameters
+   * have to be entered in the form <code>key: value</code>. In other words, a
+   * map is described in the form <code>key1: value1, key2: value2, key3:
+   * value3, ...</code>. A constructor argument allows to choose a delimiter
+   * between pairs other than the comma.
    *
-   * With two additional parameters, the number of elements this list has
-   * to have can be specified. If none is specified, the map may have zero
-   * or more entries.
+   * With two additional parameters, the number of elements this list has to
+   * have can be specified. If none is specified, the map may have zero or
+   * more entries.
    */
   class Map : public PatternBase
   {
@@ -517,14 +512,14 @@ namespace Patterns
     virtual ~Map ();
 
     /**
-     * Return <tt>true</tt> if the string is a comma-separated list of
-     * strings each of which match the pattern given to the constructor.
+     * Return <tt>true</tt> if the string is a comma-separated list of strings
+     * each of which match the pattern given to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match.
+     * Return a description of the pattern that valid strings are expected to
+     * match.
      */
     virtual std::string description () const;
 
@@ -548,8 +543,10 @@ namespace Patterns
      */
     std::size_t memory_consumption () const;
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception.
@@ -590,15 +587,15 @@ namespace Patterns
 
 
   /**
-   * This class is much like the Selection class, but it allows the input
-   * to be a comma-separated list of values which each have to be given in
-   * the constructor argument. Alternatively, it could be viewed as a
+   * This class is much like the Selection class, but it allows the input to
+   * be a comma-separated list of values which each have to be given in the
+   * constructor argument. Alternatively, it could be viewed as a
    * specialization of the List class. For example, if the string to the
-   * constructor was <tt>"ucd|gmv|eps"</tt>, then the following would be
-   * legal input: <tt>eps</tt>, <tt>gmv</tt>. You may give an arbitrarily
-   * long list of values, where there may be as many spaces around commas
-   * as you like.  However, commas are not allowed inside the values given
-   * to the constructor.
+   * constructor was <tt>"ucd|gmv|eps"</tt>, then the following would be legal
+   * input: <tt>eps</tt>, <tt>gmv</tt>. You may give an arbitrarily long list
+   * of values, where there may be as many spaces around commas as you like.
+   * However, commas are not allowed inside the values given to the
+   * constructor.
    */
   class MultipleSelection : public PatternBase
   {
@@ -616,8 +613,8 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. Here, this is the list of valid strings passed to the
+     * Return a description of the pattern that valid strings are expected to
+     * match. Here, this is the list of valid strings passed to the
      * constructor.
      */
     virtual std::string description () const;
@@ -642,8 +639,10 @@ namespace Patterns
      */
     std::size_t memory_consumption () const;
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception.
@@ -655,8 +654,8 @@ namespace Patterns
     //@}
   private:
     /**
-     * List of valid strings as passed to the constructor. We don't make
-     * this string constant, as we process it somewhat in the constructor.
+     * List of valid strings as passed to the constructor. We don't make this
+     * string constant, as we process it somewhat in the constructor.
      */
     std::string sequence;
 
@@ -667,8 +666,8 @@ namespace Patterns
   };
 
   /**
-   * Test for the string being either "true" or "false". This is mapped to
-   * the Selection class.
+   * Test for the string being either "true" or "false". This is mapped to the
+   * Selection class.
    */
   class Bool : public Selection
   {
@@ -679,8 +678,8 @@ namespace Patterns
     Bool ();
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match.
+     * Return a description of the pattern that valid strings are expected to
+     * match.
      */
     virtual std::string description () const;
 
@@ -724,8 +723,8 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. Here, this is the string <tt>"[Anything]"</tt>.
+     * Return a description of the pattern that valid strings are expected to
+     * match. Here, this is the string <tt>"[Anything]"</tt>.
      */
     virtual std::string description () const;
 
@@ -752,20 +751,18 @@ namespace Patterns
 
 
   /**
-   * A pattern that can be used to indicate when a parameter is intended to
-   * be the name of a file. By itself, this class does not check whether
-   * the string that is given in a parameter file actually corresponds to
-   * an existing file (it could, for example, be the name of a file to
-   * which you want to write output). Functionally, the class is therefore
-   * equivalent to the Anything class. However, it allows to specify the
-   * <i>intent</i> of a parameter. The flag given to the constructor also
-   * allows to specify whether the file is supposed to be an input or
-   * output file.
+   * A pattern that can be used to indicate when a parameter is intended to be
+   * the name of a file. By itself, this class does not check whether the
+   * string that is given in a parameter file actually corresponds to an
+   * existing file (it could, for example, be the name of a file to which you
+   * want to write output). Functionally, the class is therefore equivalent to
+   * the Anything class. However, it allows to specify the <i>intent</i> of a
+   * parameter. The flag given to the constructor also allows to specify
+   * whether the file is supposed to be an input or output file.
    *
-   * The reason for the existence of this class is to support graphical
-   * user interfaces for editing parameter files. These may open a file
-   * selection dialog if the filename is supposed to represent an input
-   * file.
+   * The reason for the existence of this class is to support graphical user
+   * interfaces for editing parameter files. These may open a file selection
+   * dialog if the filename is supposed to represent an input file.
    */
   class FileName : public PatternBase
   {
@@ -789,8 +786,8 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. Here, this is the string <tt>"[Filename]"</tt>.
+     * Return a description of the pattern that valid strings are expected to
+     * match. Here, this is the string <tt>"[Filename]"</tt>.
      */
     virtual std::string description () const;
 
@@ -822,16 +819,16 @@ namespace Patterns
 
 
   /**
-   * A pattern that can be used to indicate when a parameter is intended to
-   * be the name of a directory. By itself, this class does not check
-   * whether the string that is given in a parameter file actually
-   * corresponds to an existing directory. Functionally, the class is
-   * therefore equivalent to the Anything class. However, it allows to
-   * specify the <i>intent</i> of a parameter.
+   * A pattern that can be used to indicate when a parameter is intended to be
+   * the name of a directory. By itself, this class does not check whether the
+   * string that is given in a parameter file actually corresponds to an
+   * existing directory. Functionally, the class is therefore equivalent to
+   * the Anything class. However, it allows to specify the <i>intent</i> of a
+   * parameter.
    *
-   * The reason for the existence of this class is to support graphical
-   * user interfaces for editing parameter files. These may open a file
-   * selection dialog to select or create a directory.
+   * The reason for the existence of this class is to support graphical user
+   * interfaces for editing parameter files. These may open a file selection
+   * dialog to select or create a directory.
    */
   class DirectoryName : public PatternBase
   {
@@ -848,8 +845,8 @@ namespace Patterns
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of the pattern that valid strings are expected
-     * to match. Here, this is the string <tt>"[Filename]"</tt>.
+     * Return a description of the pattern that valid strings are expected to
+     * match. Here, this is the string <tt>"[Filename]"</tt>.
      */
     virtual std::string description () const;
 
@@ -877,27 +874,26 @@ namespace Patterns
 
 
 /**
- *   The ParameterHandler class provides a standard interface to an input
- *   file which provides at run-time for program parameters such as time
- *   step sizes, geometries, right hand sides etc. The input for the
- *   program is given in files, streams or strings in memory using text
- *   like
+ * The ParameterHandler class provides a standard interface to an input file
+ * which provides at run-time for program parameters such as time step sizes,
+ * geometries, right hand sides etc. The input for the program is given in
+ * files, streams or strings in memory using text like
  *   @code
  *     set Time step size = 0.3
  *     set Geometry       = [0,1]x[0,3]
  *   @endcode
- *   Input may be sorted into subsection trees in order to give the input a
- *   logical structure, and input files may include other files.
+ * Input may be sorted into subsection trees in order to give the input a
+ * logical structure, and input files may include other files.
  *
- *   The ParameterHandler class is discussed in detail in the @ref step_19
- *   "step-19" example program, and is used in more realistic situations in
- *   step-29, step-33 and step-34.
+ * The ParameterHandler class is discussed in detail in the @ref step_19
+ * "step-19" example program, and is used in more realistic situations in
+ * step-29, step-33 and step-34.
  *
- *   <h3>Declaring entries</h3>
+ * <h3>Declaring entries</h3>
  *
- *   In order to use the facilities of a ParameterHandler object, one first
- *   has to make known the different entries the input file may or may not
- *   contain. This is done in the following way:
+ * In order to use the facilities of a ParameterHandler object, one first has
+ * to make known the different entries the input file may or may not contain.
+ * This is done in the following way:
  *
  *   @code
  *     ...
@@ -911,24 +907,23 @@ namespace Patterns
  *                       Patterns::Anything());
  *     ...
  *   @endcode
- *   Each entry is declared using the function declare_entry(). The first
- *   parameter is the name of the entry (in short: the entry). The second
- *   is the default answer to be taken in case the entry is not specified
- *   in the input file. The third parameter is a regular expression which
- *   the input (and the default answer) has to match.  Several such regular
- *   expressions are defined in Patterns. This parameter can be omitted, in
- *   which case it will default to Patterns::Anything, i.e. a pattern that
- *   matches every input string. The fourth parameter can be used to
- *   document the intent or expected format of an entry; its value is
- *   printed as a comment when writing all entries of a ParameterHandler
- *   object using the print_parameters() function to allow for easier
- *   understanding of a parameter file. It can be omitted as well, in which
- *   case no such documentation will be printed.
- *
- *   Entries may be located in subsections which form a kind of input tree.
- *   For example input parameters for linear solver routines should be
- *   classified in a subsection named <tt>Linear solver</tt> or any other
- *   suitable name. This is accomplished in the following way:
+ * Each entry is declared using the function declare_entry(). The first
+ * parameter is the name of the entry (in short: the entry). The second is the
+ * default answer to be taken in case the entry is not specified in the input
+ * file. The third parameter is a regular expression which the input (and the
+ * default answer) has to match.  Several such regular expressions are defined
+ * in Patterns. This parameter can be omitted, in which case it will default
+ * to Patterns::Anything, i.e. a pattern that matches every input string. The
+ * fourth parameter can be used to document the intent or expected format of
+ * an entry; its value is printed as a comment when writing all entries of a
+ * ParameterHandler object using the print_parameters() function to allow for
+ * easier understanding of a parameter file. It can be omitted as well, in
+ * which case no such documentation will be printed.
+ *
+ * Entries may be located in subsections which form a kind of input tree. For
+ * example input parameters for linear solver routines should be classified in
+ * a subsection named <tt>Linear solver</tt> or any other suitable name. This
+ * is accomplished in the following way:
  *   @code
  *     ...
  *       LinEq eq;
@@ -951,10 +946,10 @@ namespace Patterns
  *     }
  *   @endcode
  *
- *   Subsections may be nested. For example a nonlinear solver may have a
- *   linear solver as member object. Then the function call tree would be
- *   something like (if the class <tt>NonLinEq</tt> has a member variables
- *   <tt>eq</tt> of type <tt>LinEq</tt>):
+ * Subsections may be nested. For example a nonlinear solver may have a linear
+ * solver as member object. Then the function call tree would be something
+ * like (if the class <tt>NonLinEq</tt> has a member variables <tt>eq</tt> of
+ * type <tt>LinEq</tt>):
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -968,15 +963,14 @@ namespace Patterns
  *     }
  *   @endcode
  *
- *   For class member functions which declare the different entries we
- *   propose to use the common name <tt>declare_parameters</tt>. In normal
- *   cases this method can be <tt>static</tt> since the entries will not
- *   depend on any previous knowledge. Classes for which entries should
- *   logically be grouped into subsections should declare these subsections
- *   themselves. If a class has two or more member variables of the same
- *   type both of which should have their own parameters, this parent
- *   class' method <tt>declare_parameters</tt> is responsible to group them
- *   into different subsections:
+ * For class member functions which declare the different entries we propose
+ * to use the common name <tt>declare_parameters</tt>. In normal cases this
+ * method can be <tt>static</tt> since the entries will not depend on any
+ * previous knowledge. Classes for which entries should logically be grouped
+ * into subsections should declare these subsections themselves. If a class
+ * has two or more member variables of the same type both of which should have
+ * their own parameters, this parent class' method <tt>declare_parameters</tt>
+ * is responsible to group them into different subsections:
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -998,9 +992,9 @@ namespace Patterns
  *   @endcode
  *
  *
- *   <h3>Input files and special characters</h3>
+ * <h3>Input files and special characters</h3>
  *
- *   For the first example above the input file would look like the following:
+ * For the first example above the input file would look like the following:
  *   @code
  *     ...
  *     subsection Nonlinear solver
@@ -1013,46 +1007,43 @@ namespace Patterns
  *     end
  *     ...                       # other stuff
  *   @endcode
- *   The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be
- *   either written in lowercase or uppercase letters. Leading and trailing
- *   whitespace is removed, multiple whitespace is condensed into only one.
- *   Since the latter applies also to the name of an entry, an entry name
- *   will not be recognized if in the declaration multiple whitespace is
- *   used.
+ * The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be either
+ * written in lowercase or uppercase letters. Leading and trailing whitespace
+ * is removed, multiple whitespace is condensed into only one. Since the
+ * latter applies also to the name of an entry, an entry name will not be
+ * recognized if in the declaration multiple whitespace is used.
  *
- *   In entry names and values the following characters are not allowed:
- *   <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved
- *   for the MultipleParameterLoop class.
+ * In entry names and values the following characters are not allowed:
+ * <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved for
+ * the MultipleParameterLoop class.
  *
- *   Comments starting with \# are skipped.
+ * Comments starting with \# are skipped.
  *
- *   We propose to use the following scheme to name entries: start the
- *   first word with a capital letter and use lowercase letters further on.
- *   The same applies to the possible entry values to the right of the
- *   <tt>=</tt> sign.
+ * We propose to use the following scheme to name entries: start the first
+ * word with a capital letter and use lowercase letters further on. The same
+ * applies to the possible entry values to the right of the <tt>=</tt> sign.
  *
  *
- *   <h3>Including other input files</h3>
+ * <h3>Including other input files</h3>
  *
- *   An input file can include other include files using the syntax
+ * An input file can include other include files using the syntax
  *   @code
  *     ...
  *     include some_other_file.prm
  *     ...
  *   @endcode
- *   The file so referenced is searched for relative to the current
- *   directory (not relative to the directory in which the including
- *   parameter file is located, since this is not known to all three
- *   versions of the read_input() function).
+ * The file so referenced is searched for relative to the current directory
+ * (not relative to the directory in which the including parameter file is
+ * located, since this is not known to all three versions of the read_input()
+ * function).
  *
  *
- *   <h3>Reading data from input sources</h3>
+ * <h3>Reading data from input sources</h3>
  *
- *   In order to read input there are three possibilities: reading from
- *   an <tt>std::istream</tt> object, reading from a file of which the name
- *   is given and reading from a string in memory in which the lines are
- *   separated by <tt>@\n</tt> characters. These possibilities are used as
- *   follows:
+ * In order to read input there are three possibilities: reading from an
+ * <tt>std::istream</tt> object, reading from a file of which the name is
+ * given and reading from a string in memory in which the lines are separated
+ * by <tt>@\n</tt> characters. These possibilities are used as follows:
  *   @code
  *     ParameterHandler prm;
  *     ...
@@ -1066,54 +1057,52 @@ namespace Patterns
  *     prm.read_input_from_string (in);
  *     ...
  *   @endcode
- *   You can use several sources of input successively. Entries which are
- *   changed more than once will be overwritten every time they are used.
- *
- *   You should not try to declare entries using declare_entry() and
- *   enter_subsection() with as yet unknown subsection names after
- *   using read_input(). The results in this case are unspecified.
- *
- *   If an error occurs upon reading the input, error messages are written
- *   to <tt>std::cerr</tt> and the reader function returns with a return
- *   value of <code>false</code>. This is opposed to almost all other
- *   functions in deal.II, which would normally throw an exception if an
- *   error occurs; this difference in behavior is a relic of the fact that
- *   this class predates deal.II and had previously been written for a
- *   different project.
- *
- *
- *   <h3>Using the %ParameterHandler Graphical User Interface</h3>
- *
- *   An alternative to using the hand-written input files shown above is to
- *   use the graphical user interface (GUI) that accompanies this class.
- *   For this, you first need to write a description of all the parameters,
- *   their default values, patterns and documentation strings into a file
- *   in a format that the GUI can understand; this is done using the
- *   ParameterHandler::print_parameters() function with
- *   ParameterHandler::XML as second argument, as discussed in more detail
- *   below in the <i>Representation of Parameters</i> section. This file
- *   can then be loaded using the executable for the GUI, which should be
- *   located in <code>lib/bin/dealii_parameter_gui</code> of your deal.II
- *   installation, assuming that you have a sufficiently recent version of
- *   the <a href="http://qt.nokia.com/">Qt toolkit</a> installed.
- *
- *   Once loaded, the GUI displays subsections and individual parameters in
- *   tree form (see also the discussion in the <i>Representation of
- *   Parameters</i> section below). Here is a screen shot
- *   with some sub-sections expanded and one parameter selected for
- *   editing:
- *
- *   @image html parameter_gui.png "Parameter GUI"
- *
- *   Using the GUI, you can edit the values of individual parameters and
- *   save the result in the same format as before. It can then be read in
- *   using the ParameterHandler::read_input_from_xml() function.
- *
- *
- *   <h3>Getting entry values out of a %ParameterHandler object</h3>
- *
- *   Each class gets its data out of a ParameterHandler object by
- *   calling the get()  member functions like this:
+ * You can use several sources of input successively. Entries which are
+ * changed more than once will be overwritten every time they are used.
+ *
+ * You should not try to declare entries using declare_entry() and
+ * enter_subsection() with as yet unknown subsection names after using
+ * read_input(). The results in this case are unspecified.
+ *
+ * If an error occurs upon reading the input, error messages are written to
+ * <tt>std::cerr</tt> and the reader function returns with a return value of
+ * <code>false</code>. This is opposed to almost all other functions in
+ * deal.II, which would normally throw an exception if an error occurs; this
+ * difference in behavior is a relic of the fact that this class predates
+ * deal.II and had previously been written for a different project.
+ *
+ *
+ * <h3>Using the %ParameterHandler Graphical User Interface</h3>
+ *
+ * An alternative to using the hand-written input files shown above is to use
+ * the graphical user interface (GUI) that accompanies this class. For this,
+ * you first need to write a description of all the parameters, their default
+ * values, patterns and documentation strings into a file in a format that the
+ * GUI can understand; this is done using the
+ * ParameterHandler::print_parameters() function with ParameterHandler::XML as
+ * second argument, as discussed in more detail below in the <i>Representation
+ * of Parameters</i> section. This file can then be loaded using the
+ * executable for the GUI, which should be located in
+ * <code>lib/bin/dealii_parameter_gui</code> of your deal.II installation,
+ * assuming that you have a sufficiently recent version of the <a
+ * href="http://qt.nokia.com/">Qt toolkit</a> installed.
+ *
+ * Once loaded, the GUI displays subsections and individual parameters in tree
+ * form (see also the discussion in the <i>Representation of Parameters</i>
+ * section below). Here is a screen shot with some sub-sections expanded and
+ * one parameter selected for editing:
+ *
+ * @image html parameter_gui.png "Parameter GUI"
+ *
+ * Using the GUI, you can edit the values of individual parameters and save
+ * the result in the same format as before. It can then be read in using the
+ * ParameterHandler::read_input_from_xml() function.
+ *
+ *
+ * <h3>Getting entry values out of a %ParameterHandler object</h3>
+ *
+ * Each class gets its data out of a ParameterHandler object by calling the
+ * get()  member functions like this:
  *   @code
  *      void NonLinEq::get_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -1122,67 +1111,62 @@ namespace Patterns
  *       prm.leave_subsection ();
  *     }
  *   @endcode
- *   get() returns the value of the given entry. If the entry was not
- *   specified in the input source(s), the default value is returned. You
- *   have to enter and leave subsections exactly as you did when declaring
- *   subsection. You may chose the order in which to transverse the
- *   subsection tree.
- *
- *   It is guaranteed that only entries matching the given regular
- *   expression are returned, i.e. an input entry value which does not
- *   match the regular expression is not stored.
- *
- *   You can use get() to retrieve the parameter in text form,
- *   get_integer() to get an integer or get_double() to get a double. You
- *   can also use get_bool(). It will cause an internal error if the string
- *   could not be converted to an integer, double or a bool. This should,
- *   though, not happen if you correctly specified the regular expression
- *   for this entry; you should not try to get out an integer or a double
- *   from an entry for which no according regular expression was set. The
- *   internal error is raised through the Assert() macro family which only
- *   works in debug mode.
- *
- *   If you want to print out all user selectable features, use the
- *   print_parameters() function. It is generally a good idea to print all
- *   parameters at the beginning of a log file, since this way input and
- *   output are together in one file which makes matching at a later time
- *   easier. Additionally, the function also print those entries which have
- *   not been modified in the input file und are thus set to default
- *   values; since default values may change in the process of program
- *   development, you cannot know the values of parameters not specified in
- *   the input file.
- *
- *
- *   <h3>Style guide for data retrieval</h3>
- *
- *   We propose that every class which gets data out of a ParameterHandler
- *   object provides a function named <tt>get_parameters</tt>. This should
- *   be declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in
- *   derived classes should call the <tt>BaseClass::get_parameters</tt>
- *   function.
- *
- *
- *   <h3>Experience with large parameter lists</h3>
- *
- *   Experience has shown that in programs defining larger numbers of
- *   parameters (more than, say, fifty) it is advantageous to define an
- *   additional class holding these parameters. This class is more like a
- *   C-style structure, having a large number of variables, usually public.
- *   It then has at least two functions, which declare and parse the
- *   parameters. In the main program, the main class has an object of this
- *   parameter class and delegates declaration and parsing of parameters to
- *   this object.
- *
- *   The advantage of this approach is that you can keep out the technical
- *   details (declaration and parsing) out of the main class and
- *   additionally don't clutter up your main class with dozens or more
- *   variables denoting the parameters.
- *
- *
- *
- *   <h3>Worked Example</h3>
- *
- *   This is the code:
+ * get() returns the value of the given entry. If the entry was not specified
+ * in the input source(s), the default value is returned. You have to enter
+ * and leave subsections exactly as you did when declaring subsection. You may
+ * chose the order in which to transverse the subsection tree.
+ *
+ * It is guaranteed that only entries matching the given regular expression
+ * are returned, i.e. an input entry value which does not match the regular
+ * expression is not stored.
+ *
+ * You can use get() to retrieve the parameter in text form, get_integer() to
+ * get an integer or get_double() to get a double. You can also use
+ * get_bool(). It will cause an internal error if the string could not be
+ * converted to an integer, double or a bool. This should, though, not happen
+ * if you correctly specified the regular expression for this entry; you
+ * should not try to get out an integer or a double from an entry for which no
+ * according regular expression was set. The internal error is raised through
+ * the Assert() macro family which only works in debug mode.
+ *
+ * If you want to print out all user selectable features, use the
+ * print_parameters() function. It is generally a good idea to print all
+ * parameters at the beginning of a log file, since this way input and output
+ * are together in one file which makes matching at a later time easier.
+ * Additionally, the function also print those entries which have not been
+ * modified in the input file und are thus set to default values; since
+ * default values may change in the process of program development, you cannot
+ * know the values of parameters not specified in the input file.
+ *
+ *
+ * <h3>Style guide for data retrieval</h3>
+ *
+ * We propose that every class which gets data out of a ParameterHandler
+ * object provides a function named <tt>get_parameters</tt>. This should be
+ * declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in derived
+ * classes should call the <tt>BaseClass::get_parameters</tt> function.
+ *
+ *
+ * <h3>Experience with large parameter lists</h3>
+ *
+ * Experience has shown that in programs defining larger numbers of parameters
+ * (more than, say, fifty) it is advantageous to define an additional class
+ * holding these parameters. This class is more like a C-style structure,
+ * having a large number of variables, usually public. It then has at least
+ * two functions, which declare and parse the parameters. In the main program,
+ * the main class has an object of this parameter class and delegates
+ * declaration and parsing of parameters to this object.
+ *
+ * The advantage of this approach is that you can keep out the technical
+ * details (declaration and parsing) out of the main class and additionally
+ * don't clutter up your main class with dozens or more variables denoting the
+ * parameters.
+ *
+ *
+ *
+ * <h3>Worked Example</h3>
+ *
+ * This is the code:
  *   @code
  *     #include <iostream>
  *     #include "../include/parameter_handler.h"
@@ -1328,7 +1312,7 @@ namespace Patterns
  *   @endcode
  *
  *
- *   This is the input file (named "prmtest.prm"):
+ * This is the input file (named "prmtest.prm"):
  *   @code
  *                                 # first declare the types of equations
  *     set Equation 1 = Poisson
@@ -1351,7 +1335,7 @@ namespace Patterns
  *     end
  *   @endcode
  *
- *   And here is the output of the program:
+ * And here is the output of the program:
  *   @code
  *     Line 8:
  *         The entry value
@@ -1393,15 +1377,15 @@ namespace Patterns
  *
  *
  *
- *   <h3>Representation of Parameters</h3>
+ * <h3>Representation of Parameters</h3>
  *
- *   Here is some more internal information about the repesentation of
- *   parameters:
+ * Here is some more internal information about the repesentation of
+ * parameters:
  *
- *   Logically, parameters and the nested sections they are arranged in can be
- *   thought of as a hierarchical directory structure, or a tree. Take, for
- *   example, the following code declaring a set of parameters and sections
- *   they live in:
+ * Logically, parameters and the nested sections they are arranged in can be
+ * thought of as a hierarchical directory structure, or a tree. Take, for
+ * example, the following code declaring a set of parameters and sections they
+ * live in:
  *   @code
  *     ParameterHandler prm;
  *
@@ -1427,44 +1411,40 @@ namespace Patterns
  *     prm.leave_subsection ();
  *   @endcode
  *
- *   We can think of the parameters so arranged as a file system in which
- *   every parameter is a directory. The name of this directory is the name
- *   of the parameter, and in this directory lie files that describe the
- *   parameter. These files are:
- *   - <code>value</code>: The content of this file is the current value of this
- *     parameter; initially, the content of the file equals the default value of
- *     the parameter.
- *   - <code>default_value</code>: The content of this file is the default value
- *     value of the parameter.
- *   - <code>pattern</code>: A textual representation of the pattern that describes
- *     the parameter's possible values.
- *   - <code>pattern_index</code>: A number that indexes the Patterns::PatternBase
- *     object that is used to describe the parameter.
- *   - <code>documentation</code>: The content of this file is the documentation
- *     given for a parameter as the last argument of the
- *     ParameterHandler::declare_entry call.
- *   With the exception of the <code>value</code> file, the contents of files
- *   are never changed after declaration of a parameter.
- *
- *   Alternatively, a directory in this file system may not have a file
- *   called <code>value</code> in it. In that case, the directory
- *   represents a subsection as declared above, and the directory's name
- *   will correspond to the name of the subsection. It will then have no
- *   files in it at all, but it may have further directories in it: some of
- *   these directories will be parameters (indicates by the presence of
- *   files) or further nested subsections.
- *
- *   Given this explanation, the code above will lead to a hierarchical
- *   representation of data that looks like this (the content of files is
- *   indicated at the right in a different font):
- *     @image html parameter_handler.png
- *   Once parameters have been read in, the contents of the <code>value</code>
- *   "files" may be different while the other files remain untouched.
- *
- *   Using the ParameterHandler::print_parameters() function with
- *   ParameterHandler::XML as second argument, we can get a complete
- *   representation of this data structure in XML. It will look like
- *   this:
+ * We can think of the parameters so arranged as a file system in which every
+ * parameter is a directory. The name of this directory is the name of the
+ * parameter, and in this directory lie files that describe the parameter.
+ * These files are: - <code>value</code>: The content of this file is the
+ * current value of this parameter; initially, the content of the file equals
+ * the default value of the parameter. - <code>default_value</code>: The
+ * content of this file is the default value value of the parameter. -
+ * <code>pattern</code>: A textual representation of the pattern that
+ * describes the parameter's possible values. - <code>pattern_index</code>: A
+ * number that indexes the Patterns::PatternBase object that is used to
+ * describe the parameter. - <code>documentation</code>: The content of this
+ * file is the documentation given for a parameter as the last argument of the
+ * ParameterHandler::declare_entry call. With the exception of the
+ * <code>value</code> file, the contents of files are never changed after
+ * declaration of a parameter.
+ *
+ * Alternatively, a directory in this file system may not have a file called
+ * <code>value</code> in it. In that case, the directory represents a
+ * subsection as declared above, and the directory's name will correspond to
+ * the name of the subsection. It will then have no files in it at all, but it
+ * may have further directories in it: some of these directories will be
+ * parameters (indicates by the presence of files) or further nested
+ * subsections.
+ *
+ * Given this explanation, the code above will lead to a hierarchical
+ * representation of data that looks like this (the content of files is
+ * indicated at the right in a different font): @image html
+ * parameter_handler.png Once parameters have been read in, the contents of
+ * the <code>value</code> "files" may be different while the other files
+ * remain untouched.
+ *
+ * Using the ParameterHandler::print_parameters() function with
+ * ParameterHandler::XML as second argument, we can get a complete
+ * representation of this data structure in XML. It will look like this:
  *   @code
  *   <?xml version="1.0" encoding="utf-8"?>
  *   <ParameterHandler>
@@ -1492,26 +1472,24 @@ namespace Patterns
  *     </Preconditioner>
  *   <ParameterHandler>
  *   @endcode
- *   This representation closely resembles the directory/file structure
- *   discussed above. The only difference is that directory and file
- *   names are mangled: since they should only contain letters and
- *   numbers, every character in their names that is not a letter or number
- *   is replaced
- *   by an underscore followed by its two-digit hexadecimal representation.
- *   In addition, the special name "value" is mangled when used as the
- *   name of a parameter, given that this name is also used to name
- *   special files in the hierarchy structure.
- *   Finally, the entire tree is wrapped into a tag
- *   <code>%ParameterHandler</code> to satisfy the XML requirement that there
- *   be only a single top-level construct in each file.
- *
- *   The tree structure (and its XML representation) is what the graphical
- *   user interface (see above) uses to represent parameters like a
- *   directory/file collection.
- *
- *
- *   @ingroup input
- *   @author Wolfgang Bangerth, October 1997, revised February 1998, 2010, 2011
+ * This representation closely resembles the directory/file structure
+ * discussed above. The only difference is that directory and file names are
+ * mangled: since they should only contain letters and numbers, every
+ * character in their names that is not a letter or number is replaced by an
+ * underscore followed by its two-digit hexadecimal representation. In
+ * addition, the special name "value" is mangled when used as the name of a
+ * parameter, given that this name is also used to name special files in the
+ * hierarchy structure. Finally, the entire tree is wrapped into a tag
+ * <code>%ParameterHandler</code> to satisfy the XML requirement that there be
+ * only a single top-level construct in each file.
+ *
+ * The tree structure (and its XML representation) is what the graphical user
+ * interface (see above) uses to represent parameters like a directory/file
+ * collection.
+ *
+ *
+ * @ingroup input
+ * @author Wolfgang Bangerth, October 1997, revised February 1998, 2010, 2011
  */
 class ParameterHandler : public Subscriptor
 {
@@ -1530,9 +1508,9 @@ public:
   /**
    * List of possible output formats.
    *
-   * The formats down the list with prefix <em>Short</em> and bit 6 and 7
-   * set reproduce the old behavior of not writing comments or original
-   * values to the files.
+   * The formats down the list with prefix <em>Short</em> and bit 6 and 7 set
+   * reproduce the old behavior of not writing comments or original values to
+   * the files.
    */
   enum OutputStyle
   {
@@ -1554,8 +1532,7 @@ public:
      * Write out everything as an <a
      * href="http://en.wikipedia.org/wiki/XML">XML</a> file.
      *
-     * See the general documentation of this class for an example of
-     * output.
+     * See the general documentation of this class for an example of output.
      */
     XML = 4,
 
@@ -1587,10 +1564,10 @@ public:
   virtual ~ParameterHandler ();
 
   /**
-   * Read input from a stream until the stream returns the <tt>eof</tt> condition
-   * or error. The second argument can be used to denote the name of the file
-   * (if that's what the input stream represents) we are reading from; this
-   * is only used when creating output for error messages.
+   * Read input from a stream until the stream returns the <tt>eof</tt>
+   * condition or error. The second argument can be used to denote the name of
+   * the file (if that's what the input stream represents) we are reading
+   * from; this is only used when creating output for error messages.
    *
    * Return whether the read was successful.
    */
@@ -1598,14 +1575,14 @@ public:
                            const std::string &filename = "input file");
 
   /**
-   * Read input from a file the name of which is given. The PathSearch
-   * class "PARAMETERS" is used to find the file.
+   * Read input from a file the name of which is given. The PathSearch class
+   * "PARAMETERS" is used to find the file.
    *
    * Return whether the read was successful.
    *
    * Unless <tt>optional</tt> is <tt>true</tt>, this function will
-   * automatically generate the requested file with default values if the
-   * file did not exist. This file will not contain additional comments if
+   * automatically generate the requested file with default values if the file
+   * did not exist. This file will not contain additional comments if
    * <tt>write_stripped_file</tt> is <tt>true</tt>.
    */
   virtual bool read_input (const std::string &filename,
@@ -1621,11 +1598,11 @@ public:
   virtual bool read_input_from_string (const char *s);
 
   /**
-   * Read a parameter file in XML format. This could be from a file
-   * originally written by the print_parameters() function using the XML
-   * output style and then modified by hand as necessary; or from a file
-   * written using this method and then modified by the graphical parameter
-   * GUI (see the general documentation of this class).
+   * Read a parameter file in XML format. This could be from a file originally
+   * written by the print_parameters() function using the XML output style and
+   * then modified by hand as necessary; or from a file written using this
+   * method and then modified by the graphical parameter GUI (see the general
+   * documentation of this class).
    *
    * Return whether the read was successful.
    */
@@ -1638,23 +1615,23 @@ public:
 
 
   /**
-   * Declare a new entry with name <tt>entry</tt>, default and for which
-   * any input has to match the <tt>pattern</tt> (default: any pattern).
+   * Declare a new entry with name <tt>entry</tt>, default and for which any
+   * input has to match the <tt>pattern</tt> (default: any pattern).
    *
    * The last parameter defaulting to an empty string is used to add a
    * documenting text to each entry which will be printed as a comment when
-   * this class is asked to write out all declarations to a stream using
-   * the print_parameters() function.
+   * this class is asked to write out all declarations to a stream using the
+   * print_parameters() function.
    *
    * The function generates an exception of type ExcValueDoesNotMatchPattern
-   * if the default value doesn't match the given pattern, using the C++
-   * throw mechanism. However, this exception is only generated <i>after</i>
-   * the entry has been created; if you have code where no sensible default
-   * value for a parameter is possible, you can then catch and ignore this
+   * if the default value doesn't match the given pattern, using the C++ throw
+   * mechanism. However, this exception is only generated <i>after</i> the
+   * entry has been created; if you have code where no sensible default value
+   * for a parameter is possible, you can then catch and ignore this
    * exception.
    *
-   * @note An entry can be declared more than once without
-   * generating an error, for example to override an earlier default value.
+   * @note An entry can be declared more than once without generating an
+   * error, for example to override an earlier default value.
    */
   void declare_entry (const std::string           &entry,
                       const std::string           &default_value,
@@ -1667,23 +1644,22 @@ public:
   void enter_subsection (const std::string &subsection);
 
   /**
-   * Leave present subsection. Return <tt>false</tt> if there is no
-   * subsection to leave; <tt>true</tt> otherwise.
+   * Leave present subsection. Return <tt>false</tt> if there is no subsection
+   * to leave; <tt>true</tt> otherwise.
    */
   bool leave_subsection ();
 
   /**
-   * Return value of entry <tt>entry_string</tt>.  If the entry was
-   * changed, then the changed value is returned, otherwise the default
-   * value. If the value of an undeclared entry is required, an exception
-   * will be thrown.
+   * Return value of entry <tt>entry_string</tt>.  If the entry was changed,
+   * then the changed value is returned, otherwise the default value. If the
+   * value of an undeclared entry is required, an exception will be thrown.
    */
   std::string get (const std::string &entry_string) const;
 
   /**
-   * Return value of entry <tt>entry_string</tt> as <tt>long int</tt>. (A
-   * long int is chosen so that even very large unsigned values can be
-   * returned by this function).
+   * Return value of entry <tt>entry_string</tt> as <tt>long int</tt>. (A long
+   * int is chosen so that even very large unsigned values can be returned by
+   * this function).
    */
   long int       get_integer (const std::string &entry_string) const;
 
@@ -1693,9 +1669,9 @@ public:
   double         get_double (const std::string &entry_name) const;
 
   /**
-   * Return value of entry <tt>entry_name</tt> as <tt>bool</tt>. The entry
-   * may be "true" or "yes" for <tt>true</tt>, "false" or "no" for
-   * <tt>false</tt> respectively.
+   * Return value of entry <tt>entry_name</tt> as <tt>bool</tt>. The entry may
+   * be "true" or "yes" for <tt>true</tt>, "false" or "no" for <tt>false</tt>
+   * respectively.
    */
   bool           get_bool (const std::string &entry_name) const;
 
@@ -1705,21 +1681,21 @@ public:
    *
    * The parameter must already exist in the present subsection.
    *
-   * The function throws an exception of type ExcValueDoesNotMatchPattern
-   * if the new value does not conform to the pattern for this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern if
+   * the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const std::string &new_value);
 
   /**
-   * Same as above, but an overload where the second argument is a
-   * character pointer. This is necessary, since otherwise the call to
+   * Same as above, but an overload where the second argument is a character
+   * pointer. This is necessary, since otherwise the call to
    * <tt>set("abc","def")</code> will be mapped to the function taking one
-   * string and a bool as arguments, which is certainly not what is most
-   * often intended.
+   * string and a bool as arguments, which is certainly not what is most often
+   * intended.
    *
-   * The function throws an exception of type ExcValueDoesNotMatchPattern
-   * if the new value does not conform to the pattern for this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern if
+   * the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const char        *new_value);
@@ -1730,8 +1706,8 @@ public:
    *
    * The parameter must already exist in the present subsection.
    *
-   * The function throws an exception of type ExcValueDoesNotMatchPattern
-   * if the new value does not conform to the pattern for this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern if
+   * the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const long int    &new_value);
@@ -1742,13 +1718,12 @@ public:
    *
    * The parameter must already exist in the present subsection.
    *
-   * For internal purposes, the new value needs to be converted to a
-   * string. This is done using 16 digits of accuracy, so the set value and
-   * the one you can get back out using get_double() may differ in the 16th
-   * digit.
+   * For internal purposes, the new value needs to be converted to a string.
+   * This is done using 16 digits of accuracy, so the set value and the one
+   * you can get back out using get_double() may differ in the 16th digit.
    *
-   * The function throws an exception of type ExcValueDoesNotMatchPattern
-   * if the new value does not conform to the pattern for this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern if
+   * the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const double      &new_value);
@@ -1759,47 +1734,45 @@ public:
    *
    * The parameter must already exist in the present subsection.
    *
-   * The function throws an exception of type ExcValueDoesNotMatchPattern
-   * if the new value does not conform to the pattern for this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern if
+   * the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const bool        &new_value);
 
 
   /**
-   * Print all parameters with the given style to <tt>out</tt>. Presently
-   * only <tt>Text</tt>, <tt>LaTeX</tt> and <tt>XML</tt> are implemented.
+   * Print all parameters with the given style to <tt>out</tt>. Presently only
+   * <tt>Text</tt>, <tt>LaTeX</tt> and <tt>XML</tt> are implemented.
    *
-   * In <tt>Text</tt> format, the output is formatted in such a way that it
-   * is possible to use it for later input again. This is most useful to
-   * record the parameters for a specific run, since if you output the
-   * parameters using this function into a log file, you can always recover
-   * the results by simply copying the output to your input file.
+   * In <tt>Text</tt> format, the output is formatted in such a way that it is
+   * possible to use it for later input again. This is most useful to record
+   * the parameters for a specific run, since if you output the parameters
+   * using this function into a log file, you can always recover the results
+   * by simply copying the output to your input file.
    *
    * Besides the name and value of each entry, the output also contains the
    * default value of entries if it is different from the actual value, as
-   * well as the documenting string given to the declare_entry() function
-   * if available.
+   * well as the documenting string given to the declare_entry() function if
+   * available.
    *
    * In <tt>XML</tt> format, the output starts with one root element
-   * <tt>ParameterHandler</tt> in order to get a valid XML document
-   * and all subsections under it.
+   * <tt>ParameterHandler</tt> in order to get a valid XML document and all
+   * subsections under it.
    *
-   * In <tt>Text</tt> format, the output contains the same information but
-   * in a format so that the resulting file can be input into a latex
-   * document such as a manual for the code for which this object handles
-   * run-time parameters. The various sections of parameters are then
-   * represented by latex section and subsection commands as well as by
-   * nested enumerations.
+   * In <tt>Text</tt> format, the output contains the same information but in
+   * a format so that the resulting file can be input into a latex document
+   * such as a manual for the code for which this object handles run-time
+   * parameters. The various sections of parameters are then represented by
+   * latex section and subsection commands as well as by nested enumerations.
    *
    * In addition, all parameter names are listed with <code>@\index</code>
-   * statements in two indices called <code>prmindex</code> (where the name
-   * of each parameter is listed in the index) and
-   * <code>prmindexfull</code> where parameter names are listed sorted by
-   * the section in which they exist. By default, the LaTeX program ignores
-   * these <code>@\index</code> commands, but they can be used to generate
-   * an index by using the following commands in the preamble of the latex
-   * file:
+   * statements in two indices called <code>prmindex</code> (where the name of
+   * each parameter is listed in the index) and <code>prmindexfull</code>
+   * where parameter names are listed sorted by the section in which they
+   * exist. By default, the LaTeX program ignores these <code>@\index</code>
+   * commands, but they can be used to generate an index by using the
+   * following commands in the preamble of the latex file:
    * @code
    * \usepackage{imakeidx}
    * \makeindex[name=prmindex, title=Index of run-time parameter entries]
@@ -1816,17 +1789,17 @@ public:
 
   /**
    * Print out the parameters of the present subsection as given by the
-   * <tt>subsection_path</tt> member variable. This variable is controlled
-   * by entering and leaving subsections through the enter_subsection() and
+   * <tt>subsection_path</tt> member variable. This variable is controlled by
+   * entering and leaving subsections through the enter_subsection() and
    * leave_subsection() functions.
    *
-   * If <tt>include_top_level_elements</tt> is <tt>true</tt>, also
-   * the higher subsection elements are printed. In <tt>XML</tt> format
-   * this is required to get a valid XML document and output starts
-   * with one root element <tt>ParameterHandler</tt>.
+   * If <tt>include_top_level_elements</tt> is <tt>true</tt>, also the higher
+   * subsection elements are printed. In <tt>XML</tt> format this is required
+   * to get a valid XML document and output starts with one root element
+   * <tt>ParameterHandler</tt>.
    *
-   * In most cases, you will not want to use this function directly, but
-   * have it called recursively by the previous function.
+   * In most cases, you will not want to use this function directly, but have
+   * it called recursively by the previous function.
    */
   void print_parameters_section (std::ostream       &out,
                                  const OutputStyle   style,
@@ -1835,19 +1808,19 @@ public:
 
   /**
    * Print parameters to a logstream. This function allows to print all
-   * parameters into a log-file. Sections will be indented in the usual
-   * log-file style.
+   * parameters into a log-file. Sections will be indented in the usual log-
+   * file style.
    */
   void log_parameters (LogStream &out);
 
   /**
-   * Log parameters in the present subsection. The subsection is determined
-   * by the <tt>subsection_path</tt> member variable. This variable is
-   * controlled by entering and leaving subsections through the
-   * enter_subsection() and leave_subsection() functions.
+   * Log parameters in the present subsection. The subsection is determined by
+   * the <tt>subsection_path</tt> member variable. This variable is controlled
+   * by entering and leaving subsections through the enter_subsection() and
+   * leave_subsection() functions.
    *
-   * In most cases, you will not want to use this function directly, but
-   * have it called recursively by the previous function.
+   * In most cases, you will not want to use this function directly, but have
+   * it called recursively by the previous function.
    */
   void log_parameters_section (LogStream &out);
 
@@ -1878,8 +1851,10 @@ public:
    */
   bool operator == (const ParameterHandler &prm2)  const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -1913,19 +1888,18 @@ public:
   //@}
 private:
   /**
-   * The separator used when accessing elements of a path into the
-   * parameter tree.
+   * The separator used when accessing elements of a path into the parameter
+   * tree.
    */
   static const char path_separator = '.';
 
   /**
-   * The complete tree of sections and entries. See the general
-   * documentation of this class for a description how data is stored in
-   * this variable.
+   * The complete tree of sections and entries. See the general documentation
+   * of this class for a description how data is stored in this variable.
    *
-   * The variable is a pointer so that we can use an incomplete type,
-   * rather than having to include all of the property_tree stuff from
-   * boost. This works around a problem with gcc 4.5.
+   * The variable is a pointer so that we can use an incomplete type, rather
+   * than having to include all of the property_tree stuff from boost. This
+   * works around a problem with gcc 4.5.
    */
   std::auto_ptr<boost::property_tree::ptree> entries;
 
@@ -1964,20 +1938,19 @@ private:
   std::string get_current_path () const;
 
   /**
-   * Given the name of an entry as argument, the function computes a full
-   * path into the parameter tree using the current subsection.
+   * Given the name of an entry as argument, the function computes a full path
+   * into the parameter tree using the current subsection.
    */
   std::string get_current_full_path (const std::string &name) const;
 
   /**
-   * Scan one line of input. <tt>input_filename</tt> and <tt>lineno</tt>
-   * are the name of the input file and the current number of the line
-   * presently scanned (for the logs if there are messages). Return
-   * <tt>false</tt> if line contained stuff that could not be understood,
-   * the uppermost subsection was to be left by an <tt>END</tt> or
-   * <tt>end</tt> statement, a value for a non-declared entry was given or
-   * the entry value did not match the regular expression. <tt>true</tt>
-   * otherwise.
+   * Scan one line of input. <tt>input_filename</tt> and <tt>lineno</tt> are
+   * the name of the input file and the current number of the line presently
+   * scanned (for the logs if there are messages). Return <tt>false</tt> if
+   * line contained stuff that could not be understood, the uppermost
+   * subsection was to be left by an <tt>END</tt> or <tt>end</tt> statement, a
+   * value for a non-declared entry was given or the entry value did not match
+   * the regular expression. <tt>true</tt> otherwise.
    *
    * The function modifies its argument, but also takes it by value, so the
    * caller's variable is not changed.
@@ -1992,64 +1965,60 @@ private:
 
 
 /**
- *   The class MultipleParameterLoop offers an easy possibility to test
- *   several parameter sets during one run of the program. For this it uses
- *   the ParameterHandler class to read in data in a standardized form,
- *   searches for variant entry values and performs a loop over all
- *   combinations of parameters.
+ * The class MultipleParameterLoop offers an easy possibility to test several
+ * parameter sets during one run of the program. For this it uses the
+ * ParameterHandler class to read in data in a standardized form, searches for
+ * variant entry values and performs a loop over all combinations of
+ * parameters.
  *
- *   Variant entry values are given like this:
+ * Variant entry values are given like this:
  *   @verbatim
  *     set Time step size = { 0.1 | 0.2 | 0.3 }
  *   @endverbatim
- *   The loop will then perform three runs of the program, one for each
- *   value of <tt>Time step size</tt>, while all other parameters are as
- *   specified or with their default value. If there are several variant
- *   entry values in the input, a loop is performed for each combination of
- *   variant values:
+ * The loop will then perform three runs of the program, one for each value of
+ * <tt>Time step size</tt>, while all other parameters are as specified or
+ * with their default value. If there are several variant entry values in the
+ * input, a loop is performed for each combination of variant values:
  *   @verbatim
  *     set Time step size = { 0.1 | 0.2 }
  *     set Solver         = { CG  | GMRES }
  *   @endverbatim
- *   will result in four runs of the programs, with time step 0.1 and 0.2
- *   for each of the two solvers.
+ * will result in four runs of the programs, with time step 0.1 and 0.2 for
+ * each of the two solvers.
  *
- *   In addition to variant entries, this class also supports <i>array
- *   entries</i> that look like this:
+ * In addition to variant entries, this class also supports <i>array
+ * entries</i> that look like this:
  *   @verbatim
  *     set Output file = ofile.{{ 1 | 2 | 3 | 4 }}
  *   @endverbatim
- *   This indicates that if there are variant entries producing a total of
- *   four different runs, then we will write their results to the files
- *   <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and
- *   <tt>ofile.4</tt>, respectively. Array entries do not generate multiple
- *   runs of the main loop themselves, but if there are variant entries,
- *   then in the <i>n</i>th run of the main loop, also the <i>n</i>th value
- *   of an array is returned.
- *
- *   Since the different variants are constructed in the order of
- *   declaration, not in the order in which the variant entries appear in
- *   the input file, it may be difficult to guess the mapping between the
- *   different variants and the appropriate entry in an array. You will
- *   have to check the order of declaration, or use only one variant entry.
- *
- *   It is guaranteed that only selections which match the regular
- *   expression (pattern) given upon declaration of an entry are given back
- *   to the program. If a variant value does not match the regular
- *   expression, the default value is stored and an error is issued. Before
- *   the first run of the loop, all possible values are checked for their
- *   conformance, so that the error is issued at the very beginning of the
- *   program.
- *
- *
- *   <h3>Usage</h3>
- *
- *   The usage of this class is similar to the ParameterHandler class.
- *   First the entries and subsections have to be declared, then a loop is
- *   performed in which the different parameter sets are set, a new
- *   instance of a user class is created which is then called. Taking the
- *   classes of the example for the ParameterHandler class, the extended
- *   program would look like this:
+ * This indicates that if there are variant entries producing a total of four
+ * different runs, then we will write their results to the files
+ * <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and <tt>ofile.4</tt>,
+ * respectively. Array entries do not generate multiple runs of the main loop
+ * themselves, but if there are variant entries, then in the <i>n</i>th run of
+ * the main loop, also the <i>n</i>th value of an array is returned.
+ *
+ * Since the different variants are constructed in the order of declaration,
+ * not in the order in which the variant entries appear in the input file, it
+ * may be difficult to guess the mapping between the different variants and
+ * the appropriate entry in an array. You will have to check the order of
+ * declaration, or use only one variant entry.
+ *
+ * It is guaranteed that only selections which match the regular expression
+ * (pattern) given upon declaration of an entry are given back to the program.
+ * If a variant value does not match the regular expression, the default value
+ * is stored and an error is issued. Before the first run of the loop, all
+ * possible values are checked for their conformance, so that the error is
+ * issued at the very beginning of the program.
+ *
+ *
+ * <h3>Usage</h3>
+ *
+ * The usage of this class is similar to the ParameterHandler class. First the
+ * entries and subsections have to be declared, then a loop is performed in
+ * which the different parameter sets are set, a new instance of a user class
+ * is created which is then called. Taking the classes of the example for the
+ * ParameterHandler class, the extended program would look like this:
  *   @code
  *     class HelperClass : public MultipleParameterLoop::UserClass {
  *       public:
@@ -2096,25 +2065,24 @@ private:
  *     }
  *   @endcode
  *
- *   As can be seen, first a new helper class has to be set up. This must
- *   contain a virtual constructor for a problem class. You can also derive
- *   your problem class from MultipleParameterLoop::UserClass and let
- *   <tt>create_new</tt> clear all member variables. If you have access to
- *   all inherited member variables in some way this is the recommended
- *   procedure. A third possibility is to use multiple inheritance and
- *   derive a helper class from both the MultipleParameterLoop::UserClass
- *   and the problem class. In any case, <tt>create_new</tt> has to provide
- *   a clean problem object which is the problem in the second and third
- *   possibility.
- *
- *   The derived class also has to provide for member functions which
- *   declare the entries and which run the program. Running the program
- *   includes getting the parameters out of the ParameterHandler object.
- *
- *   After defining an object of this helper class and an object of the
- *   MultipleParameterLoop class, the entries have to be declared in the
- *   same way as for the ParameterHandler class. Then the input has to be
- *   read. Finally the loop is called. This executes the following steps:
+ * As can be seen, first a new helper class has to be set up. This must
+ * contain a virtual constructor for a problem class. You can also derive your
+ * problem class from MultipleParameterLoop::UserClass and let
+ * <tt>create_new</tt> clear all member variables. If you have access to all
+ * inherited member variables in some way this is the recommended procedure. A
+ * third possibility is to use multiple inheritance and derive a helper class
+ * from both the MultipleParameterLoop::UserClass and the problem class. In
+ * any case, <tt>create_new</tt> has to provide a clean problem object which
+ * is the problem in the second and third possibility.
+ *
+ * The derived class also has to provide for member functions which declare
+ * the entries and which run the program. Running the program includes getting
+ * the parameters out of the ParameterHandler object.
+ *
+ * After defining an object of this helper class and an object of the
+ * MultipleParameterLoop class, the entries have to be declared in the same
+ * way as for the ParameterHandler class. Then the input has to be read.
+ * Finally the loop is called. This executes the following steps:
  *   @code
  *     for (each combination)
  *       {
@@ -2125,28 +2093,29 @@ private:
  *         UserObject.run (*this);
  *       }
  *   @endcode
- *   <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
- *   <tt>create_new</tt> is given the number of the run (starting from one)
 *   to enable naming output files differently for each run.
+ * <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
+ * <tt>create_new</tt> is given the number of the run (starting from one) to
* enable naming output files differently for each run.
  *
  *
- *   <h3>Syntax for variant and array entry values</h3>
+ * <h3>Syntax for variant and array entry values</h3>
  *
- *   Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ... }postfix</tt>. Whitespace
- *   to the right of the opening brace <tt>{</tt> is ignored as well as to the left of the
- *   closing brace <tt>}</tt> while whitespace on the respectively other side is not ignored.
- *   Whitespace around the mid symbols <tt>|</tt> is also ignored. The empty selection
- *   <tt>prefix{ v1 | }postfix</tt> is also allowed and produces the strings <tt>prefixv1postfix</tt> and
- *   <tt>prefixpostfix</tt>.
+ * Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ...
+ * }postfix</tt>. Whitespace to the right of the opening brace <tt>{</tt> is
+ * ignored as well as to the left of the closing brace <tt>}</tt> while
+ * whitespace on the respectively other side is not ignored. Whitespace around
+ * the mid symbols <tt>|</tt> is also ignored. The empty selection <tt>prefix{
+ * v1 | }postfix</tt> is also allowed and produces the strings
+ * <tt>prefixv1postfix</tt> and <tt>prefixpostfix</tt>.
  *
- *   The syntax for array values is equal, apart from the double braces:
- *   <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>.
+ * The syntax for array values is equal, apart from the double braces:
+ * <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>.
  *
  *
- *   <h3>Worked example</h3>
+ * <h3>Worked example</h3>
  *
- *   Given the above extensions to the example program for the
- *   ParameterHandler and the following input file
+ * Given the above extensions to the example program for the ParameterHandler
+ * and the following input file
  *   @verbatim
  *     set Equation 1 = Poisson
  *     set Equation 2 = Navier-Stokes
@@ -2168,7 +2137,7 @@ private:
  *       end
  *     end
  *   @endverbatim
- *   this is the output:
+ * this is the output:
  *   @verbatim
  *     LinEq: Method=CG, MaxIterations=10
  *     LinEq: Method=BiCGStab, MaxIterations=100
@@ -2201,38 +2170,38 @@ private:
  *              eq1=Poisson, eq2=Navier-Stokes
  *              Matrix1=Sparse, Matrix2=Full
  *   @endverbatim
- *   Since <tt>create_new</tt> gets the number of the run it would also be
- *   possible to output the number of the run.
+ * Since <tt>create_new</tt> gets the number of the run it would also be
+ * possible to output the number of the run.
  *
  *
- *   @ingroup input
- *   @author Wolfgang Bangerth, October 1997, 2010
+ * @ingroup input
+ * @author Wolfgang Bangerth, October 1997, 2010
  */
 class MultipleParameterLoop : public ParameterHandler
 {
 public:
   /**
-   * This is the class the helper class or the problem class has to be
-   * derived of.
+   * This is the class the helper class or the problem class has to be derived
+   * of.
    */
   class UserClass
   {
   public:
     /**
-     * Destructor. It doesn't actually do anything, but is declared to
-     * force derived classes to have a virtual destructor.
+     * Destructor. It doesn't actually do anything, but is declared to force
+     * derived classes to have a virtual destructor.
      */
     virtual ~UserClass ();
 
     /**
-     * <tt>create_new</tt> must provide a clean object, either by creating
-     * new one or by cleaning an old one.
+     * <tt>create_new</tt> must provide a clean object, either by creating a
+     * new one or by cleaning an old one.
      */
     virtual void create_new (const unsigned int run_no) = 0;
 
     /**
-     * This should declare parameters and call the
-     * <tt>declare_parameters</tt> function of the problem class.
+     * This should declare parameters and call the <tt>declare_parameters</tt>
+     * function of the problem class.
      */
     virtual void declare_parameters (ParameterHandler &prm) = 0;
 
@@ -2249,16 +2218,15 @@ public:
 
   /**
    * Destructor. Declare this only to have a virtual destructor, which is
-   * safer as we have virtual functions. It actually does nothing
-   * spectacular.
+   * safer as we have virtual functions. It actually does nothing spectacular.
    */
   virtual ~MultipleParameterLoop ();
 
   /**
-   * Read input from a stream until the stream returns the <tt>eof</tt> condition
-   * or error. The second argument can be used to denote the name of the file
-   * (if that's what the input stream represents) we are reading from; this
-   * is only used when creating output for error messages.
+   * Read input from a stream until the stream returns the <tt>eof</tt>
+   * condition or error. The second argument can be used to denote the name of
+   * the file (if that's what the input stream represents) we are reading
+   * from; this is only used when creating output for error messages.
    *
    * Return whether the read was successful.
    */
@@ -2266,14 +2234,14 @@ public:
                            const std::string &filename = "input file");
 
   /**
-   * Read input from a file the name of which is given. The PathSearch
-   * class "PARAMETERS" is used to find the file.
+   * Read input from a file the name of which is given. The PathSearch class
+   * "PARAMETERS" is used to find the file.
    *
    * Return whether the read was successful.
    *
    * Unless <tt>optional</tt> is <tt>true</tt>, this function will
-   * automatically generate the requested file with default values if the
-   * file did not exist. This file will not contain additional comments if
+   * automatically generate the requested file with default values if the file
+   * did not exist. This file will not contain additional comments if
    * <tt>write_stripped_file</tt> is <tt>true</tt>.
    */
   virtual bool read_input (const std::string &FileName,
index b4bd6ad4fd97334d9b57de86b3b96547f2fcd94b..a53368f72d6e1c5f73293def1ca08b08a8eae694 100644 (file)
@@ -26,15 +26,14 @@ DEAL_II_NAMESPACE_OPEN
 namespace Functions
 {
   /**
-   *   Friendly interface to the FunctionParser class. This class is
-   *   meant as a wrapper for the FunctionParser class. It is used in the
-   *   step-34 tutorial program.
+   * Friendly interface to the FunctionParser class. This class is meant as a
+   * wrapper for the FunctionParser class. It is used in the step-34 tutorial
+   * program.
    *
-   *   It provides two
-   *   methods to declare and parse a ParameterHandler object and creates
-   *   the Function object declared in the parameter file. This class is
-   *   derived from the AutoDerivativeFunction class, so you don't need
-   *   to specify derivatives. An example of usage of this class is as follows:
+   * It provides two methods to declare and parse a ParameterHandler object
+   * and creates the Function object declared in the parameter file. This
+   * class is derived from the AutoDerivativeFunction class, so you don't need
+   * to specify derivatives. An example of usage of this class is as follows:
    *
    *   @code
    *   // A parameter handler
@@ -58,9 +57,9 @@ namespace Functions
    *
    *   @endcode
    *
-   *   And here is an example of how the input parameter could look like
-   *   (see the documentation of the FunctionParser class for a detailed
-   *   description of the syntax of the function definition):
+   * And here is an example of how the input parameter could look like (see
+   * the documentation of the FunctionParser class for a detailed description
+   * of the syntax of the function definition):
    *
    *   @code
    *
@@ -73,44 +72,28 @@ namespace Functions
    *
    *   @endcode
    *
-   *   @ingroup functions
-   *   @author Luca Heltai, 2006
+   * @ingroup functions
+   * @author Luca Heltai, 2006
    */
   template <int dim>
   class ParsedFunction :  public AutoDerivativeFunction<dim>
   {
   public:
     /**
-     * Construct a vector
-     * function. The vector
-     * function which is generated
-     * has @p n_components
-     * components (defaults to
-     * 1). The parameter @p h is
-     * used to initialize the
-     * AutoDerivativeFunction class
-     * from which this class is
+     * Construct a vector function. The vector function which is generated has
+     * @p n_components components (defaults to 1). The parameter @p h is used
+     * to initialize the AutoDerivativeFunction class from which this class is
      * derived.
      */
     ParsedFunction (const unsigned int n_components = 1, const double h=1e-8);
 
     /**
-     * Declare parameters needed by
-     * this class. The additional
-     * parameter @p n_components is
-     * used to generate the right
-     * code according to the number
-     * of components of the
-     * function that will parse
-     * this ParameterHandler. If
-     * the number of components
-     * which is parsed does not
-     * match the number of
-     * components of this object,
-     * an assertion is thrown and
-     * the program is aborted.  The
-     * default behavior for this
-     * class is to declare the
+     * Declare parameters needed by this class. The additional parameter @p
+     * n_components is used to generate the right code according to the number
+     * of components of the function that will parse this ParameterHandler. If
+     * the number of components which is parsed does not match the number of
+     * components of this object, an assertion is thrown and the program is
+     * aborted.  The default behavior for this class is to declare the
      * following entries:
      *
      *  @code
@@ -126,25 +109,15 @@ namespace Functions
                                    const unsigned int n_components = 1);
 
     /**
-     * Parse parameters needed by
-     * this class.  If the number
-     * of components which is
-     * parsed does not match the
-     * number of components of this
-     * object, an assertion is
-     * thrown and the program is
-     * aborted.  In order for the
-     * class to function properly,
-     * we follow the same
-     * convenctions declared in the
-     * FunctionParser class (look
-     * there for a detailed
-     * description of the syntax
-     * for function declarations).
+     * Parse parameters needed by this class.  If the number of components
+     * which is parsed does not match the number of components of this object,
+     * an assertion is thrown and the program is aborted.  In order for the
+     * class to function properly, we follow the same convenctions declared in
+     * the FunctionParser class (look there for a detailed description of the
+     * syntax for function declarations).
      *
-     * The three variables that can
-     * be parsed from a parameter
-     * file are the following:
+     * The three variables that can be parsed from a parameter file are the
+     * following:
      *
      *  @code
      *
@@ -154,10 +127,8 @@ namespace Functions
      *
      *  @endcode
      *
-     *  Function constants is a
-     *  collection of pairs in the
-     *  form name=value, separated
-     *  by commas, for example:
+     * Function constants is a collection of pairs in the form name=value,
+     * separated by commas, for example:
      *
      *  @code
      *
@@ -165,16 +136,10 @@ namespace Functions
      *
      *  @endcode
      *
-     *  These constants can be used
-     *  in the declaration of the
-     *  function expression, which
-     *  follows the convention of
-     *  the FunctionParser
-     *  class. In order to specify
-     *  vector functions,
-     *  semicolons have to be used
-     *  to separate the different
-     *  components, e.g.:
+     * These constants can be used in the declaration of the function
+     * expression, which follows the convention of the FunctionParser class.
+     * In order to specify vector functions, semicolons have to be used to
+     * separate the different components, e.g.:
      *
      *  @code
      *
@@ -182,11 +147,8 @@ namespace Functions
      *
      *  @endcode
      *
-     *  The variable names entry
-     *  can be used to customize
-     *  the name of the variables
-     *  used in the Function. It
-     *  defaults to
+     * The variable names entry can be used to customize the name of the
+     * variables used in the Function. It defaults to
      *
      *  @code
      *
@@ -194,7 +156,7 @@ namespace Functions
      *
      *  @endcode
      *
-     *  for one dimensional problems,
+     * for one dimensional problems,
      *
      *  @code
      *
@@ -202,7 +164,7 @@ namespace Functions
      *
      *  @endcode
      *
-     *  for two dimensional problems and
+     * for two dimensional problems and
      *
      *  @code
      *
@@ -210,53 +172,40 @@ namespace Functions
      *
      *  @endcode
      *
-     *  for three dimensional problems.
+     * for three dimensional problems.
      *
-     *  The time variable can be
-     *  set according to
-     *  specifications in the
-     *  FunctionTime base class.
+     * The time variable can be set according to specifications in the
+     * FunctionTime base class.
      */
     void parse_parameters(ParameterHandler &prm);
 
     /**
-     * Return all components of a
-     * vector-valued function at the
-     * given point @p p.
+     * Return all components of a vector-valued function at the given point @p
+     * p.
      */
     virtual void vector_value (const Point<dim> &p,
                                Vector<double>   &values) const;
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component
-     * you want to have evaluated;
-     * it defaults to zero,
-     * i.e. the first component.
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
+     * first component.
      */
     virtual double value (const Point< dim >     &p,
                           const unsigned int  component = 0)    const;
 
     /**
-     * Set the time to a specific
-     * value for time-dependent
-     * functions.
+     * Set the time to a specific value for time-dependent functions.
      *
-     * We need to overwrite this to
-     * set the time also in the
-     * accessor
+     * We need to overwrite this to set the time also in the accessor
      * FunctionParser<dim>.
      */
     virtual void set_time(const double newtime);
 
   private:
     /**
-     * The object with which we do
-     * computations.
+     * The object with which we do computations.
      */
     FunctionParser<dim> function_object;
   };
index 3e3efca05641daa01720b0fc860f4716e9ecfc5e..d9407d6ffa6453b167a84d6bba0f17dc74336b20 100644 (file)
@@ -33,31 +33,27 @@ namespace Utilities
   namespace MPI
   {
     /**
-     * This class defines a model for the partitioning of a vector (or,
-     * in fact, any linear data structure) among processors using
-     * MPI.
+     * This class defines a model for the partitioning of a vector (or, in
+     * fact, any linear data structure) among processors using MPI.
      *
-     * The partitioner stores the global vector size and the locally
-     * owned range as a half-open interval [@p lower, @p
-     * upper). Furthermore, it includes a structure for the
-     * point-to-point communication patterns. It allows the inclusion of
-     * ghost indices (i.e. indices that a current processor needs to
-     * have access to, but are owned by another process) through an
-     * IndexSet. In addition, it also stores the other processors' ghost
-     * indices belonging to the current processor, which are the indices
-     * where other processors might require information from. In a
-     * sense, these import indices form the dual of the ghost
-     * indices. This information is gathered once when constructing the
-     * partitioner, which obviates subsequent global communication steps
-     * when exchanging data.
+     * The partitioner stores the global vector size and the locally owned
+     * range as a half-open interval [@p lower, @p upper). Furthermore, it
+     * includes a structure for the point-to-point communication patterns. It
+     * allows the inclusion of ghost indices (i.e. indices that a current
+     * processor needs to have access to, but are owned by another process)
+     * through an IndexSet. In addition, it also stores the other processors'
+     * ghost indices belonging to the current processor, which are the indices
+     * where other processors might require information from. In a sense,
+     * these import indices form the dual of the ghost indices. This
+     * information is gathered once when constructing the partitioner, which
+     * obviates subsequent global communication steps when exchanging data.
      *
      * The partitioner includes a mechanism for converting global to local and
      * local to global indices. Internally, this class stores vector elements
      * using the convention as follows: The local range is associated with
      * local indices [0,@p local_size), and ghost indices are stored
-     * consecutively in [@p local_size, @p local_size + @p
-     * n_ghost_indices). The ghost indices are sorted according to their
-     * global index.
+     * consecutively in [@p local_size, @p local_size + @p n_ghost_indices).
+     * The ghost indices are sorted according to their global index.
      *
      *
      * @author Katharina Kormann, Martin Kronbichler, 2010, 2011
@@ -71,47 +67,40 @@ namespace Utilities
       Partitioner ();
 
       /**
-       * Constructor with size argument. Creates an
-       * MPI_COMM_SELF structure where there is no
-       * real parallel layout.
+       * Constructor with size argument. Creates an MPI_COMM_SELF structure
+       * where there is no real parallel layout.
        */
       Partitioner (const unsigned int size);
 
       /**
-       * Constructor with index set arguments. This
-       *  constructor creates a distributed layout
-       *  based on a given communicators, an
-       *  IndexSet describing the locally owned
-       *  range and another one for describing ghost
-       *  indices that are owned by other
-       *  processors, but we need to have read or
-       *  write access to.
+       * Constructor with index set arguments. This constructor creates a
+       * distributed layout based on a given communicators, an IndexSet
+       * describing the locally owned range and another one for describing
+       * ghost indices that are owned by other processors, but we need to have
+       * read or write access to.
        */
       Partitioner (const IndexSet &locally_owned_indices,
                    const IndexSet &ghost_indices_in,
                    const MPI_Comm  communicator_in);
 
       /**
-       * Constructor with one index set argument. This
-       * constructor creates a distributed layout
-       * based on a given communicator, and an IndexSet
-       * describing the locally owned range. It
-       * allows to set the ghost indices at a later
-       * time. Apart from this, it is similar to the
-       * other constructor with two index sets.
+       * Constructor with one index set argument. This constructor creates a
+       * distributed layout based on a given communicator, and an IndexSet
+       * describing the locally owned range. It allows to set the ghost
+       * indices at a later time. Apart from this, it is similar to the other
+       * constructor with two index sets.
        */
       Partitioner (const IndexSet &locally_owned_indices,
                    const MPI_Comm  communicator_in);
 
       /**
-       * Sets the locally owned indices. Used in the
-       * constructor.
+       * Sets the locally owned indices. Used in the constructor.
        */
       void set_owned_indices (const IndexSet &locally_owned_indices);
 
       /**
-       * Allows to set the ghost indices after the
-       * constructor has been called.
+       * Allows to set the ghost indices after the constructor has been
+       * called.
        */
       void set_ghost_indices (const IndexSet &ghost_indices);
 
@@ -121,166 +110,135 @@ namespace Utilities
       types::global_dof_index size() const;
 
       /**
-       * Returns the local size, i.e.
-       * local_range().second minus
+       * Returns the local size, i.e. local_range().second minus
        * local_range().first.
        */
       unsigned int local_size() const;
 
       /**
-       * Returns an IndexSet representation of the
-       * local range. This class only supports
-       * contiguous local ranges, so the IndexSet
-       * actually only consists of one single range
-       * of data, and is equivalent to the result of
-       * local_range().
+       * Returns an IndexSet representation of the local range. This class
+       * only supports contiguous local ranges, so the IndexSet actually only
+       * consists of one single range of data, and is equivalent to the result
+       * of local_range().
        */
       const IndexSet &locally_owned_range() const;
 
       /**
-       * Returns the local range. The returned pair
-       * consists of the index of the first element
-       * and the index of the element one past the
-       * last locally owned one.
+       * Returns the local range. The returned pair consists of the index of
+       * the first element and the index of the element one past the last
+       * locally owned one.
        */
       std::pair<types::global_dof_index,types::global_dof_index>
       local_range() const;
 
       /**
-       * Returns true if the given global index is
-       * in the local range of this processor.
+       * Returns true if the given global index is in the local range of this
+       * processor.
        */
       bool in_local_range (const types::global_dof_index global_index) const;
 
       /**
-       * Returns the local index corresponding to
-       * the given global index. If the given global
-       * index is neither locally owned nor a ghost,
-       * an exception is thrown.
+       * Returns the local index corresponding to the given global index. If
+       * the given global index is neither locally owned nor a ghost, an
+       * exception is thrown.
        *
-       * Note that the local index for locally owned
-       * indices is between 0 and local_size()-1,
-       * and the local index for ghosts is between
-       * local_size() and
-       * local_size()+n_ghost_indices()-1.
+       * Note that the local index for locally owned indices is between 0 and
+       * local_size()-1, and the local index for ghosts is between
+       * local_size() and local_size()+n_ghost_indices()-1.
        */
       unsigned int
       global_to_local (const types::global_dof_index global_index) const;
 
       /**
-       * Returns the global index corresponding to
-       * the given local index.
+       * Returns the global index corresponding to the given local index.
        *
-       * Note that the local index for locally owned
-       * indices is between 0 and local_size()-1,
-       * and the local index for ghosts is between
-       * local_size() and
-       * local_size()+n_ghost_indices()-1.
+       * Note that the local index for locally owned indices is between 0 and
+       * local_size()-1, and the local index for ghosts is between
+       * local_size() and local_size()+n_ghost_indices()-1.
        */
       types::global_dof_index
       local_to_global (const unsigned int local_index) const;
 
       /**
-       * Returns whether the given global index is a
-       * ghost index on the present
-       * processor. Returns false for indices that
-       * are owned locally and for indices not
-       * present at all.
+       * Returns whether the given global index is a ghost index on the
+       * present processor. Returns false for indices that are owned locally
+       * and for indices not present at all.
        */
       bool is_ghost_entry (const types::global_dof_index global_index) const;
 
       /**
-       * Returns an IndexSet representation of all
-       * ghost indices.
+       * Returns an IndexSet representation of all ghost indices.
        */
       const IndexSet &ghost_indices() const;
 
       /**
-       * Returns the number of ghost indices. Same
-       * as ghost_indices().n_elements(), but cached
-       * for simpler access.
+       * Returns the number of ghost indices. Same as
+       * ghost_indices().n_elements(), but cached for simpler access.
        */
       unsigned int n_ghost_indices() const;
 
       /**
-       * Returns a list of processors (first entry)
-       * and the number of degrees of freedom for
-       * the individual processor on the ghost
-       * elements present (second entry).
+       * Returns a list of processors (first entry) and the number of degrees
+       * of freedom for the individual processor on the ghost elements present
+       * (second entry).
        */
       const std::vector<std::pair<unsigned int, types::global_dof_index> > &
       ghost_targets() const;
 
       /**
-       * The set of (local) indices that we are
-       * importing during compress(), i.e., others'
-       * ghosts that belong to the local
-       * range. Similar structure as in an IndexSet,
-       * but tailored to be iterated over, and some
-       * indices may be duplicates.
+       * The set of (local) indices that we are importing during compress(),
+       * i.e., others' ghosts that belong to the local range. Similar
+       * structure as in an IndexSet, but tailored to be iterated over, and
+       * some indices may be duplicates.
        */
       const std::vector<std::pair<types::global_dof_index, types::global_dof_index> > &
       import_indices() const;
 
       /**
-       * Number of import indices, i.e., indices
-       * that are ghosts on other processors and we
-       * will receive data from.
+       * Number of import indices, i.e., indices that are ghosts on other
+       * processors and we will receive data from.
        */
       unsigned int n_import_indices() const;
 
       /**
-       * Returns a list of processors (first entry)
-       * and the number of degrees of freedom for
-       * all the processors that data is obtained
-       * from (second entry), i.e., locally owned
-       * indices that are ghosts on other
+       * Returns a list of processors (first entry) and the number of degrees
+       * of freedom for all the processors that data is obtained from (second
+       * entry), i.e., locally owned indices that are ghosts on other
        * processors.
        */
       const std::vector<std::pair<unsigned int, types::global_dof_index> > &
       import_targets() const;
 
       /**
-       * Checks whether the given
-       * partitioner is compatible with the
-       * partitioner used for this
-       * vector. Two partitioners are
-       * compatible if the have the same
-       * local size and the same ghost
-       * indices. They do not necessarily
-       * need to be the same data
-       * field. This is a local operation
-       * only, i.e., if only some
-       * processors decide that the
-       * partitioning is not compatible,
-       * only these processors will return
-       * @p false, whereas the other
-       * processors will return @p true.
+       * Checks whether the given partitioner is compatible with the
+       * partitioner used for this vector. Two partitioners are compatible if
+       * the have the same local size and the same ghost indices. They do not
+       * necessarily need to be the same data field. This is a local operation
+       * only, i.e., if only some processors decide that the partitioning is
+       * not compatible, only these processors will return @p false, whereas
+       * the other processors will return @p true.
        */
       bool is_compatible (const Partitioner &part) const;
 
       /**
-       * Returns the MPI ID of the calling
-       * processor. Cached to have simple access.
+       * Returns the MPI ID of the calling processor. Cached to have simple
+       * access.
        */
       unsigned int this_mpi_process () const;
 
       /**
-       * Returns the total number of MPI processor
-       * participating in the given
+       * Returns the total number of MPI processor participating in the given
        * partitioner. Cached to have simple access.
        */
       unsigned int n_mpi_processes () const;
 
       /**
-       * Returns the MPI communicator underlying the
-       * partitioner object.
+       * Returns the MPI communicator underlying the partitioner object.
        */
       const MPI_Comm &get_communicator() const;
 
       /**
-       * Computes the memory consumption of this
-       * structure.
+       * Computes the memory consumption of this structure.
        */
       std::size_t memory_consumption() const;
 
@@ -300,77 +258,66 @@ namespace Utilities
       const types::global_dof_index global_size;
 
       /**
-       * The range of the vector that is stored
-       * locally.
+       * The range of the vector that is stored locally.
        */
       IndexSet locally_owned_range_data;
 
       /**
-       * The range of the vector that is stored
-       * locally. Extracted from locally_owned_range
-       * for performance reasons.
+       * The range of the vector that is stored locally. Extracted from
+       * locally_owned_range for performance reasons.
        */
       std::pair<types::global_dof_index,types::global_dof_index> local_range_data;
 
       /**
-       * The set of indices to which we need to have
-       * read access but that are not locally owned
+       * The set of indices to which we need to have read access but that are
+       * not locally owned
        */
       IndexSet ghost_indices_data;
 
       /**
-       * Caches the number of ghost indices. It
-       * would be expensive to use @p
+       * Caches the number of ghost indices. It would be expensive to use @p
        * ghost_indices.n_elements() to compute this.
        */
       unsigned int n_ghost_indices_data;
 
       /**
-       * Contains information which processors my
-       * ghost indices belong to and how many those
-       * indices are
+       * Contains information which processors my ghost indices belong to and
+       * how many those indices are
        */
       std::vector<std::pair<unsigned int, types::global_dof_index> > ghost_targets_data;
 
       /**
-       * The set of (local) indices that we are
-       * importing during compress(), i.e., others'
-       * ghosts that belong to the local
-       * range. Similar structure as in an IndexSet,
-       * but tailored to be iterated over, and some
-       * indices may be duplicates.
+       * The set of (local) indices that we are importing during compress(),
+       * i.e., others' ghosts that belong to the local range. Similar
+       * structure as in an IndexSet, but tailored to be iterated over, and
+       * some indices may be duplicates.
        */
       std::vector<std::pair<types::global_dof_index, types::global_dof_index> > import_indices_data;
 
       /**
-       * Caches the number of ghost indices. It
-       * would be expensive to compute it by
-       * iterating over the import indices and
-       * accumulate them.
+       * Caches the number of ghost indices. It would be expensive to compute
+       * it by iterating over the import indices and accumulate them.
        */
       unsigned int n_import_indices_data;
 
       /**
-       * The set of processors and length of data
-       * field which send us their ghost data
+       * The set of processors and length of data field which send us their
+       * ghost data
        */
       std::vector<std::pair<unsigned int,types::global_dof_index> > import_targets_data;
 
       /**
-       * The ID of the current processor in the MPI
-       * network
+       * The ID of the current processor in the MPI network
        */
       unsigned int my_pid;
 
       /**
-       * The total number of processors active in
-       * the problem
+       * The total number of processors active in the problem
        */
       unsigned int n_procs;
 
       /**
-       * The MPI communicator involved in the
-       * problem
+       * The MPI communicator involved in the problem
        */
       const MPI_Comm communicator;
     };
index f67f2b0add92affe5a87c4bd5d8d741cd6dae494..8db13e286e81af86399af50f95ce81b1ccd7b060 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Support for searching files in a list of paths and with a list of
- * suffixes.
+ * Support for searching files in a list of paths and with a list of suffixes.
  *
- * A list of search paths is maintained for each file class supported.
- * A file class is defined by a unique string. The classes provided are
- * <dl>
- * <dt> MESH <dd> mesh input files in various formats (see GridIn)
- * <dt> PARAMETER <dd> Parameter files (<tt>.prm</tt>)
- * </dl>
+ * A list of search paths is maintained for each file class supported. A file
+ * class is defined by a unique string. The classes provided are <dl> <dt>
+ * MESH <dd> mesh input files in various formats (see GridIn) <dt> PARAMETER
+ * <dd> Parameter files (<tt>.prm</tt>) </dl>
  *
  * Additional file classes can be added easily by using add_class().
  *
  * Usage: First, you construct a PathSearch object for a certain file class,
- * e.g. meshes. Then, you use the find() method to obtain a full path
- * name and you can open the file.
+ * e.g. meshes. Then, you use the find() method to obtain a full path name and
+ * you can open the file.
  * @code
  * #include <deal.II/base/path_search.h>
  *
@@ -54,30 +51,29 @@ DEAL_II_NAMESPACE_OPEN
  * ...
  * @endcode
  *
- * This piece of code will first traverse all paths in the list set up
- * for file class <TT>MESH</tt>. If it manages to open a file, it
- * returns the <tt>istream</tt> object. If not, it will try to append
- * the first suffix of the suffix list and do the same. And so on. If
- * no file is found in the end, an exception is thrown.
+ * This piece of code will first traverse all paths in the list set up for
+ * file class <TT>MESH</tt>. If it manages to open a file, it returns the
+ * <tt>istream</tt> object. If not, it will try to append the first suffix of
+ * the suffix list and do the same. And so on. If no file is found in the end,
+ * an exception is thrown.
  *
- * If you want to restrict your search to a certain mesh format,
- * <tt>.inp</tt> for instance, then either use <tt>"grid.inp"</tt> in
- * the code above or use the alternative find(const std::string&,const
- * std::string&,const char*) function
+ * If you want to restrict your search to a certain mesh format, <tt>.inp</tt>
+ * for instance, then either use <tt>"grid.inp"</tt> in the code above or use
+ * the alternative find(const std::string&,const std::string&,const char*)
+ * function
  * @code
  * std::string full_name = search.find("grid", ".inp");
  * @endcode
  *
  * Path lists are by default starting with the current directory
- * (<tt>"./"</tt>), followed optionally by a standard directory of
- * deal.II. Use show() to find out the path list
- * for a given class. Paths and suffixes can be added using the
- * functions add_path() and add_suffix(), respectively.
+ * (<tt>"./"</tt>), followed optionally by a standard directory of deal.II.
+ * Use show() to find out the path list for a given class. Paths and suffixes
+ * can be added using the functions add_path() and add_suffix(), respectively.
  *
- * @note Directories in the path list should always end with a
- * trailing <tt>"/"</tt>, while suffixes should always start with a
- * dot. These characters are not added automatically (allowing you to
- * do some real file name editing).
+ * @note Directories in the path list should always end with a trailing
+ * <tt>"/"</tt>, while suffixes should always start with a dot. These
+ * characters are not added automatically (allowing you to do some real file
+ * name editing).
  *
  * @todo Add support for environment variables like in kpathsea.
  *
@@ -88,8 +84,7 @@ class PathSearch
 {
 public:
   /**
-   * Position for adding a new item
-   * to a list.
+   * Position for adding a new item to a list.
    */
   enum Position
   {
@@ -102,91 +97,57 @@ public:
   };
 
   /**
-   * Constructor. The first argument is a
-   * string identifying the class of files
-   * to be searched for.
+   * Constructor. The first argument is a string identifying the class of
+   * files to be searched for.
    *
-   * The debug argument determines
-   * the verbosity of this class.
+   * The debug argument determines the verbosity of this class.
    */
   PathSearch (const std::string &cls,
               const unsigned int debug=0);
 
   /**
-   * Find a file in the class
-   * specified by the constructor
-   * and return its complete path
-   * name (including a possible
-   * suffix).
+   * Find a file in the class specified by the constructor and return its
+   * complete path name (including a possible suffix).
    *
-   * File search works by actually
-   * trying to open the file. If @p
-   * fopen is successful with the
-   * provided @p open_mode, then
-   * the file is found, otherwise
-   * the search continues.
+   * File search works by actually trying to open the file. If @p fopen is
+   * successful with the provided @p open_mode, then the file is found,
+   * otherwise the search continues.
    *
-   * @warning Be careful with @p
-   * open_mode! In particular, use
-   * <tt>"w"</tt> with great care!
-   * If the file does not exist, it
-   * cannot be found. If it does
-   * exist, the @p fopen function
-   * will truncate it to zero
-   * length.
+   * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
+   * with great care! If the file does not exist, it cannot be found. If it
+   * does exist, the @p fopen function will truncate it to zero length.
    *
-   * @param filename The base
-   * name of the file to be found,
-   * without path components and
-   * suffix.
-   * @param open_mode The mode
-   * handed over to the @p fopen
-   * function.
+   * @param filename The base name of the file to be found, without path
+   * components and suffix.
+   * @param open_mode The mode handed over to the @p fopen function.
    */
   std::string find (const std::string &filename,
                     const char *open_mode = "r");
 
   /**
-   * Find a file in the class
-   * specified by the constructor
-   * and return its complete path
-   * name. Do not use the standard
-   * suffix list, but only try to
+   * Find a file in the class specified by the constructor and return its
+   * complete path name. Do not use the standard suffix list, but only try to
    * apply the suffix given.
    *
-   * File search works by actually
-   * trying to open the file. If @p
-   * fopen is successful with the
-   * provided @p open_mode, then
-   * the file is found, otherwise
-   * the search continues.
+   * File search works by actually trying to open the file. If @p fopen is
+   * successful with the provided @p open_mode, then the file is found,
+   * otherwise the search continues.
    *
-   * @warning Be careful with @p
-   * open_mode! In particular, use
-   * <tt>"w"</tt> with great care!
-   * If the file does not exist, it
-   * cannot be found. If it does
-   * exist, the @p fopen function
-   * will truncate it to zero
-   * length.
+   * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
+   * with great care! If the file does not exist, it cannot be found. If it
+   * does exist, the @p fopen function will truncate it to zero length.
    *
-   * @param filename The base
-   * name of the file to be found,
-   * without path components and
-   * suffix.
-   * @param suffix The suffix to be
-   * used for opening.
-   * @param open_mode The mode
-   * handed over to the @p fopen
-   * function.
+   * @param filename The base name of the file to be found, without path
+   * components and suffix.
+   * @param suffix The suffix to be used for opening.
+   * @param open_mode The mode handed over to the @p fopen function.
    */
   std::string find (const std::string &filename,
                     const std::string &suffix,
                     const char *open_mode = "r");
 
   /**
-   * Show the paths and suffixes
-   * used for this object.
+   * Show the paths and suffixes used for this object.
    */
   template <class STREAM>
   void show(STREAM &stream) const;
@@ -197,25 +158,19 @@ public:
   static void add_class (const std::string &cls);
 
   /**
-   * Add a path to the current
-   * class. See
-   * PathSearch::Position for
-   * possible position arguments.
+   * Add a path to the current class. See PathSearch::Position for possible
+   * position arguments.
    */
   void add_path (const std::string &path, Position pos = back);
 
   /**
-   * Add a path to the current
-   * class. See
-   * PathSearch::Position for
-   * possible position arguments.
+   * Add a path to the current class. See PathSearch::Position for possible
+   * position arguments.
    */
   void add_suffix (const std::string &suffix, Position pos = back);
 
   /**
-   * This class was not
-   * registered in the path
-   * search mechanism.
+   * This class was not registered in the path search mechanism.
    * @ingroup Exceptions
    */
   DeclException1(ExcNoClass,
@@ -224,9 +179,8 @@ public:
                  << arg1
                  << " must be registered before referring it in PathSearch");
   /**
-   * The PathSearch class could not
-   * find a file with this name in
-   * its path list.
+   * The PathSearch class could not find a file with this name in its path
+   * list.
    * @ingroup Exceptions
    */
   DeclException2(ExcFileNotFound,
@@ -237,28 +191,24 @@ public:
 
 private:
   /**
-   * Type of values in the class
-   * maps.
+   * Type of values in the class maps.
    */
   typedef std::map<std::string, std::vector<std::string> >::value_type map_type;
 
   /**
-   * Initialize the static list
-   * objects for further use.
+   * Initialize the static list objects for further use.
    */
   static void initialize_classes();
 
   /**
-   * Get path list for a certain
-   * class. Used to set up
-   * #my_path_list in constructor.
+   * Get path list for a certain class. Used to set up #my_path_list in
+   * constructor.
    */
   static std::vector<std::string> &get_path_list(const std::string &cls);
 
   /**
-   * Get suffix list for a certain
-   * class. Used to set up
-   * #my_suffix_list in constructor.
+   * Get suffix list for a certain class. Used to set up #my_suffix_list in
+   * constructor.
    */
   static std::vector<std::string> &get_suffix_list(const std::string &cls);
 
@@ -268,27 +218,22 @@ private:
   const std::string cls;
 
   /**
-   * All path lists for all
-   * classes, such that we can
-   * build them only once.
+   * All path lists for all classes, such that we can build them only once.
    */
   static std::map<std::string, std::vector<std::string> > path_lists;
 
   /**
-   * List of suffixes for each
-   * class.
+   * List of suffixes for each class.
    */
   static std::map<std::string, std::vector<std::string> > suffix_lists;
 
   /**
-   * Path list for the class this
-   * object belongs to.
+   * Path list for the class this object belongs to.
    */
   std::vector<std::string> &my_path_list;
 
   /**
-   * Suffix list for the class this
-   * object belongs to.
+   * Suffix list for the class this object belongs to.
    */
   std::vector<std::string> &my_suffix_list;
 
index c4ac2d855960e38ae25466682815c5a425c14de5..7c0b7232550cab6d9eb23826fb0ee5c21afbe2d0 100644 (file)
@@ -56,18 +56,15 @@ class Point : public Tensor<1,dim,Number>
 {
 public:
   /**
-   * Standard constructor. Creates
-   * an object that corresponds to the origin, i.e., all coordinates
-   * are set to zero.
+   * Standard constructor. Creates an object that corresponds to the origin,
+   * i.e., all coordinates are set to zero.
    */
   Point ();
 
   /**
-   * Constructor. Initialize all
-   * entries to zero if
-   * <tt>initialize==true</tt> (in which case it is equivalent to the default
-   * constructor) or leaves the elements uninitialized if
-   * <tt>initialize==false</tt>.
+   * Constructor. Initialize all entries to zero if <tt>initialize==true</tt>
+   * (in which case it is equivalent to the default constructor) or leaves the
+   * elements uninitialized if <tt>initialize==false</tt>.
    */
   explicit Point (const bool initialize);
 
@@ -77,55 +74,46 @@ public:
   Point (const Tensor<1,dim,Number> &);
 
   /**
-   *  Constructor for one dimensional
-   *  points. This function is only
-   *  implemented for <tt>dim==1</tt> since
-   *  the usage is considered unsafe for
-   *  points with <tt>dim!=1</tt> as it would leave some components
-   *  of the point coordinates uninitialized.
+   * Constructor for one dimensional points. This function is only implemented
+   * for <tt>dim==1</tt> since the usage is considered unsafe for points with
+   * <tt>dim!=1</tt> as it would leave some components of the point
+   * coordinates uninitialized.
    */
   explicit Point (const Number x);
 
   /**
-   *  Constructor for two dimensional
-   *  points. This function is only
-   *  implemented for <tt>dim==2</tt> since
-   *  the usage is considered unsafe for
-   *  points with <tt>dim!=2</tt> as it would leave some components
-   *  of the point coordinates uninitialized (if dim>2) or would
-   *  not use some arguments (if dim<2).
+   * Constructor for two dimensional points. This function is only implemented
+   * for <tt>dim==2</tt> since the usage is considered unsafe for points with
+   * <tt>dim!=2</tt> as it would leave some components of the point
+   * coordinates uninitialized (if dim>2) or would not use some arguments (if
+   * dim<2).
    */
   Point (const Number x,
          const Number y);
 
   /**
-   *  Constructor for three dimensional
-   *  points. This function is only
-   *  implemented for <tt>dim==3</tt> since
-   *  the usage is considered unsafe for
-   *  points with <tt>dim!=3</tt> as it would leave some components
-   *  of the point coordinates uninitialized (if dim>3) or would
-   *  not use some arguments (if dim<3).
+   * Constructor for three dimensional points. This function is only
+   * implemented for <tt>dim==3</tt> since the usage is considered unsafe for
+   * points with <tt>dim!=3</tt> as it would leave some components of the
+   * point coordinates uninitialized (if dim>3) or would not use some
+   * arguments (if dim<3).
    */
   Point (const Number x,
          const Number y,
          const Number z);
 
   /**
-   * Return a unit vector in
-   * coordinate direction <tt>i</tt>.
+   * Return a unit vector in coordinate direction <tt>i</tt>.
    */
   static Point<dim,Number> unit_vector(const unsigned int i);
 
   /**
-   *  Read access to the <tt>index</tt>th
-   *  coordinate.
+   * Read access to the <tt>index</tt>th coordinate.
    */
   Number   operator () (const unsigned int index) const;
 
   /**
-   *  Read and write access to the
-   *  <tt>index</tt>th coordinate.
+   * Read and write access to the <tt>index</tt>th coordinate.
    */
   Number &operator () (const unsigned int index);
 
@@ -135,18 +123,14 @@ public:
    */
 
   /**
-   *  Add two point vectors. If possible,
-   *  use <tt>operator +=</tt> instead
-   *  since this does not need to copy a
-   *  point at least once.
+   * Add two point vectors. If possible, use <tt>operator +=</tt> instead
+   * since this does not need to copy a point at least once.
    */
   Point<dim,Number>   operator + (const Tensor<1,dim,Number> &) const;
 
   /**
-   *  Subtract two point vectors. If
-   *  possible, use <tt>operator +=</tt>
-   *  instead since this does not need to
-   *  copy a point at least once.
+   * Subtract two point vectors. If possible, use <tt>operator +=</tt> instead
+   * since this does not need to copy a point at least once.
    */
   Point<dim,Number>   operator - (const Tensor<1,dim,Number> &) const;
 
@@ -156,49 +140,40 @@ public:
   Point<dim,Number>   operator - () const;
 
   /**
-   *  Multiply by a factor. If possible,
-   *  use <tt>operator *=</tt> instead
-   *  since this does not need to copy a
-   *  point at least once.
+   * Multiply by a factor. If possible, use <tt>operator *=</tt> instead since
+   * this does not need to copy a point at least once.
    *
-   * There is a commutative complement to this
-   * function also
+   * There is a commutative complement to this function also
    */
   Point<dim,Number>   operator * (const Number) const;
 
   /**
-   *  Returns the scalar product of two
-   *  vectors.
+   * Returns the scalar product of two vectors.
    */
   Number       operator * (const Tensor<1,dim,Number> &) const;
 
   /**
-   *  Divide by a factor. If possible, use
-   *  <tt>operator /=</tt> instead since
-   *  this does not need to copy a point at
-   *  least once.
+   * Divide by a factor. If possible, use <tt>operator /=</tt> instead since
+   * this does not need to copy a point at least once.
    */
   Point<dim,Number>   operator / (const Number) const;
 
   /**
-   *  Returns the scalar product of this
-   *  point vector with itself, i.e. the
-   *  square, or the square of the norm.
+   * Returns the scalar product of this point vector with itself, i.e. the
+   * square, or the square of the norm.
    */
   Number              square () const;
 
   /**
-   * Returns the Euclidian distance of
-   * <tt>this</tt> point to the point
-   * <tt>p</tt>, i.e. the <tt>l_2</tt> norm
-   * of the difference between the vectors
-   * representing the two points.
+   * Returns the Euclidian distance of <tt>this</tt> point to the point
+   * <tt>p</tt>, i.e. the <tt>l_2</tt> norm of the difference between the
+   * vectors representing the two points.
    */
   Number distance (const Point<dim,Number> &p) const;
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
@@ -423,8 +398,7 @@ Point<dim,Number>::serialize(Archive &ar, const unsigned int)
 
 
 /**
- * Global operator scaling a point vector by a scalar.
- * @relates Point
+ * Global operator scaling a point vector by a scalar. @relates Point
  */
 template <int dim, typename Number>
 inline
@@ -437,8 +411,7 @@ Point<dim,Number> operator * (const Number             factor,
 
 
 /**
- * Global operator scaling a point vector by a scalar.
- * @relates Point
+ * Global operator scaling a point vector by a scalar. @relates Point
  */
 template <int dim>
 inline
@@ -451,9 +424,8 @@ Point<dim,double> operator * (const double             factor,
 
 
 /**
- * Output operator for points. Print the elements consecutively,
- * with a space in between.
- * @relates Point
+ * Output operator for points. Print the elements consecutively, with a space
+ * in between. @relates Point
  */
 template <int dim, typename Number>
 inline
@@ -470,9 +442,8 @@ std::ostream &operator << (std::ostream            &out,
 
 
 /**
- * Output operator for points. Print the elements consecutively,
- * with a space in between.
- * @relates Point
+ * Output operator for points. Print the elements consecutively, with a space
+ * in between. @relates Point
  */
 template <int dim, typename Number>
 inline
@@ -489,9 +460,9 @@ std::istream &operator >> (std::istream      &in,
 #ifndef DOXYGEN
 
 /**
- * Output operator for points of dimension 1. This is implemented
- * specialized from the general template in order to avoid a compiler
- * warning that the loop is empty.
+ * Output operator for points of dimension 1. This is implemented specialized
+ * from the general template in order to avoid a compiler warning that the
+ * loop is empty.
  */
 template <typename Number>
 inline
index 2eb2afe2b555ebcd9c9d375736b46203937d2240..d55b387cb5e2f9096d78bf709e4e28c8711427c6 100644 (file)
@@ -41,11 +41,11 @@ namespace Polynomials
 {
 
   /**
-   * Base class for all 1D polynomials. A polynomial is represented in
-   * this class by its coefficients, which are set through the
-   * constructor or by derived classes. Evaluation of a polynomial
-   * happens through the Horner scheme which provides both numerical
-   * stability and a minimal number of numerical operations.
+   * Base class for all 1D polynomials. A polynomial is represented in this
+   * class by its coefficients, which are set through the constructor or by
+   * derived classes. Evaluation of a polynomial happens through the Horner
+   * scheme which provides both numerical stability and a minimal number of
+   * numerical operations.
    *
    * @author Ralf Hartmann, Guido Kanschat, 2000, 2006
    */
@@ -169,7 +169,7 @@ namespace Polynomials
     Polynomial<number> &operator -= (const Polynomial<number> &p);
 
     /**
-     *  Test for equality of two polynomials.
+     * Test for equality of two polynomials.
      */
     bool operator == (const Polynomial<number> &p)  const;
 
@@ -244,8 +244,8 @@ namespace Polynomials
 
 
   /**
-   * Class generates Polynomial objects representing a monomial of
-   * degree n, that is, the function $x^n$.
+   * Class generates Polynomial objects representing a monomial of degree n,
+   * that is, the function $x^n$.
    *
    * @author Guido Kanschat, 2004
    */
@@ -254,25 +254,17 @@ namespace Polynomials
   {
   public:
     /**
-     * Constructor, taking the
-     * degree of the monomial and
-     * an optional coefficient as
-     * arguments.
+     * Constructor, taking the degree of the monomial and an optional
+     * coefficient as arguments.
      */
     Monomial(const unsigned int n,
              const double coefficient = 1.);
 
     /**
-     * Return a vector of Monomial
-     * objects of degree zero
-     * through <tt>degree</tt>, which
-     * then spans the full space of
-     * polynomials up to the given
-     * degree. This function may be
-     * used to initialize the
-     * TensorProductPolynomials
-     * and PolynomialSpace
-     * classes.
+     * Return a vector of Monomial objects of degree zero through
+     * <tt>degree</tt>, which then spans the full space of polynomials up to
+     * the given degree. This function may be used to initialize the
+     * TensorProductPolynomials and PolynomialSpace classes.
      */
     static
     std::vector<Polynomial<number> >
@@ -288,18 +280,17 @@ namespace Polynomials
 
 
   /**
-   * Lagrange polynomials with equidistant interpolation points in
-   * [0,1]. The polynomial of degree <tt>n</tt> has got <tt>n+1</tt> interpolation
-   * points. The interpolation points are sorted in ascending
-   * order. This order gives an index to each interpolation point.  A
-   * Lagrangian polynomial equals to 1 at its `support point', and 0 at
-   * all other interpolation points. For example, if the degree is 3,
-   * and the support point is 1, then the polynomial represented by this
-   * object is cubic and its value is 1 at the point <tt>x=1/3</tt>, and zero
-   * at the point <tt>x=0</tt>, <tt>x=2/3</tt>, and <tt>x=1</tt>. All the polynomials
-   * have polynomial degree equal to <tt>degree</tt>, but together they span
-   * the entire space of polynomials of degree less than or equal
-   * <tt>degree</tt>.
+   * Lagrange polynomials with equidistant interpolation points in [0,1]. The
+   * polynomial of degree <tt>n</tt> has got <tt>n+1</tt> interpolation
+   * points. The interpolation points are sorted in ascending order. This
+   * order gives an index to each interpolation point.  A Lagrangian
+   * polynomial equals to 1 at its `support point', and 0 at all other
+   * interpolation points. For example, if the degree is 3, and the support
+   * point is 1, then the polynomial represented by this object is cubic and
+   * its value is 1 at the point <tt>x=1/3</tt>, and zero at the point
+   * <tt>x=0</tt>, <tt>x=2/3</tt>, and <tt>x=1</tt>. All the polynomials have
+   * polynomial degree equal to <tt>degree</tt>, but together they span the
+   * entire space of polynomials of degree less than or equal <tt>degree</tt>.
    *
    * The Lagrange polynomials are implemented up to degree 10.
    *
@@ -320,9 +311,9 @@ namespace Polynomials
      * Return a vector of polynomial objects of degree <tt>degree</tt>, which
      * then spans the full space of polynomials up to the given degree. The
      * polynomials are generated by calling the constructor of this class with
-     * the same degree but support point running from zero to
-     * <tt>degree</tt>. This function may be used to initialize the
-     * TensorProductPolynomials and PolynomialSpace classes.
+     * the same degree but support point running from zero to <tt>degree</tt>.
+     * This function may be used to initialize the TensorProductPolynomials
+     * and PolynomialSpace classes.
      */
     static
     std::vector<Polynomial<double> >
@@ -355,16 +346,16 @@ namespace Polynomials
 
 
   /**
-   * Legendre polynomials of arbitrary degree.
-   * Constructing a Legendre polynomial of degree <tt>p</tt>, the coefficients
-   * will be computed by the three-term recursion formula.
+   * Legendre polynomials of arbitrary degree. Constructing a Legendre
+   * polynomial of degree <tt>p</tt>, the coefficients will be computed by the
+   * three-term recursion formula.
    *
    * @note The polynomials defined by this class differ in two aspects by what
    * is usually referred to as Legendre polynomials: (i) This classes defines
    * them on the reference interval $[0,1]$, rather than the commonly used
-   * interval $[-1,1]$. (ii) The polynomials have been scaled in such a way that
-   * they are orthonormal, not just orthogonal; consequently, the polynomials do
-   * not necessarily have boundary values equal to one.
+   * interval $[-1,1]$. (ii) The polynomials have been scaled in such a way
+   * that they are orthonormal, not just orthogonal; consequently, the
+   * polynomials do not necessarily have boundary values equal to one.
    *
    * @author Guido Kanschat, 2000
    */
@@ -372,22 +363,15 @@ namespace Polynomials
   {
   public:
     /**
-     * Constructor for polynomial of
-     * degree <tt>p</tt>.
+     * Constructor for polynomial of degree <tt>p</tt>.
      */
     Legendre (const unsigned int p);
 
     /**
-     * Return a vector of Legendre
-     * polynomial objects of degrees
-     * zero through <tt>degree</tt>, which
-     * then spans the full space of
-     * polynomials up to the given
-     * degree. This function may be
-     * used to initialize the
-     * TensorProductPolynomials
-     * and PolynomialSpace
-     * classes.
+     * Return a vector of Legendre polynomial objects of degrees zero through
+     * <tt>degree</tt>, which then spans the full space of polynomials up to
+     * the given degree. This function may be used to initialize the
+     * TensorProductPolynomials and PolynomialSpace classes.
      */
     static
     std::vector<Polynomial<double> >
@@ -400,40 +384,27 @@ namespace Polynomials
     static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > shifted_coefficients;
 
     /**
-     * Vector with already computed
-     * coefficients. For each degree of the
-     * polynomial, we keep one pointer to
-     * the list of coefficients; we do so
-     * rather than keeping a vector of
-     * vectors in order to simplify
-     * programming multithread-safe. In
-     * order to avoid memory leak, we use a
-     * shared_ptr in order to correctly
-     * free the memory of the vectors when
+     * Vector with already computed coefficients. For each degree of the
+     * polynomial, we keep one pointer to the list of coefficients; we do so
+     * rather than keeping a vector of vectors in order to simplify
+     * programming multithread-safe. In order to avoid memory leak, we use a
+     * shared_ptr in order to correctly free the memory of the vectors when
      * the global destructor is called.
      */
     static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > recursive_coefficients;
 
     /**
-     * Compute coefficients recursively.
-     * The coefficients are stored in a
-     * static data vector to be available
-     * when needed next time. Since the
-     * recursion is performed for the
-     * interval $[-1,1]$, the polynomials
-     * are shifted to $[0,1]$ by the
-     * <tt>scale</tt> and <tt>shift</tt>
-     * functions of <tt>Polynomial</tt>,
-     * afterwards.
+     * Compute coefficients recursively. The coefficients are stored in a
+     * static data vector to be available when needed next time. Since the
+     * recursion is performed for the interval $[-1,1]$, the polynomials are
+     * shifted to $[0,1]$ by the <tt>scale</tt> and <tt>shift</tt> functions
+     * of <tt>Polynomial</tt>, afterwards.
      */
     static void compute_coefficients (const unsigned int p);
 
     /**
-     * Get coefficients for
-     * constructor.  This way, it can
-     * use the non-standard
-     * constructor of
-     * Polynomial.
+     * Get coefficients for constructor.  This way, it can use the non-
+     * standard constructor of Polynomial.
      */
     static const std::vector<double> &
     get_coefficients (const unsigned int k);
@@ -444,16 +415,16 @@ namespace Polynomials
    *
    * These polynomials are the integrated Legendre polynomials on [0,1]. The
    * first two polynomials are the standard linear shape functions given by
-   * $l_0(x) = 1-x$ and $l_1(x) = x$. For $i\geq2$ we use the definition $l_i(x)
-   * = \frac{1}{\Vert L_{i-1}\Vert_2}\int_0^x L_{i-1}(t)\,dt$, where $L_i$
-   * denotes the $i$-th Legendre polynomial on $[0,1]$. The Lobatto polynomials
-   * $l_0,\ldots,l_k$ form a complete basis of the polynomials space of degree
-   * $k$.
+   * $l_0(x) = 1-x$ and $l_1(x) = x$. For $i\geq2$ we use the definition
+   * $l_i(x) = \frac{1}{\Vert L_{i-1}\Vert_2}\int_0^x L_{i-1}(t)\,dt$, where
+   * $L_i$ denotes the $i$-th Legendre polynomial on $[0,1]$. The Lobatto
+   * polynomials $l_0,\ldots,l_k$ form a complete basis of the polynomials
+   * space of degree $k$.
    *
    * Calling the constructor with a given index <tt>k</tt> will generate the
    * polynomial with index <tt>k</tt>. But only for $k\geq 1$ the index equals
-   * the degree of the polynomial. For <tt>k==0</tt> also a polynomial of degree
-   * 1 is generated.
+   * the degree of the polynomial. For <tt>k==0</tt> also a polynomial of
+   * degree 1 is generated.
    *
    * These polynomials are used for the construction of the shape functions of
    * N&eacute;d&eacute;lec elements of arbitrary order.
@@ -464,19 +435,14 @@ namespace Polynomials
   {
   public:
     /**
-     * Constructor for polynomial of degree
-     * <tt>p</tt>. There is an exception
-     * for <tt>p==0</tt>, see the general
-     * documentation.
+     * Constructor for polynomial of degree <tt>p</tt>. There is an exception
+     * for <tt>p==0</tt>, see the general documentation.
      */
     Lobatto (const unsigned int p = 0);
 
     /**
-     * Return the polynomials with index
-     * <tt>0</tt> up to
-     * <tt>degree</tt>. There is an
-     * exception for <tt>p==0</tt>, see the
-     * general documentation.
+     * Return the polynomials with index <tt>0</tt> up to <tt>degree</tt>.
+     * There is an exception for <tt>p==0</tt>, see the general documentation.
      */
     static std::vector<Polynomial<double> >
     generate_complete_basis (const unsigned int p);
@@ -493,24 +459,23 @@ namespace Polynomials
   /**
    * Hierarchical polynomials of arbitrary degree on <tt>[0,1]</tt>.
    *
-   * When Constructing a Hierarchical polynomial of degree <tt>p</tt>,
-   * the coefficients will be computed by a recursion formula.  The
-   * coefficients are stored in a static data vector to be available
-   * when needed next time.
+   * When Constructing a Hierarchical polynomial of degree <tt>p</tt>, the
+   * coefficients will be computed by a recursion formula.  The coefficients
+   * are stored in a static data vector to be available when needed next time.
    *
    * These hierarchical polynomials are based on those of Demkowicz, Oden,
    * Rachowicz, and Hardy (CMAME 77 (1989) 79-112, Sec. 4). The first two
-   * polynomials are the standard linear shape functions given by
-   * $\phi_{0}(x) = 1 - x$ and $\phi_{1}(x) = x$. For $l \geq 2$
-   * we use the definitions $\phi_{l}(x) = (2x-1)^l - 1, l = 2,4,6,...$
-   * and $\phi_{l}(x) = (2x-1)^l - (2x-1), l = 3,5,7,...$. These satisfy the
-   * recursion relations $\phi_{l}(x) = (2x-1)\phi_{l-1}, l=3,5,7,...$ and
-   * $\phi_{l}(x) = (2x-1)\phi_{l-1} + \phi_{2}, l=4,6,8,...$.
+   * polynomials are the standard linear shape functions given by $\phi_{0}(x)
+   * = 1 - x$ and $\phi_{1}(x) = x$. For $l \geq 2$ we use the definitions
+   * $\phi_{l}(x) = (2x-1)^l - 1, l = 2,4,6,...$ and $\phi_{l}(x) = (2x-1)^l -
+   * (2x-1), l = 3,5,7,...$. These satisfy the recursion relations
+   * $\phi_{l}(x) = (2x-1)\phi_{l-1}, l=3,5,7,...$ and $\phi_{l}(x) =
+   * (2x-1)\phi_{l-1} + \phi_{2}, l=4,6,8,...$.
    *
-   * The degrees of freedom are the values at the vertices and the
-   * derivatives at the midpoint. Currently, we do not scale the
-   * polynomials in any way, although better conditioning of the
-   * element stiffness matrix could possibly be achieved with scaling.
+   * The degrees of freedom are the values at the vertices and the derivatives
+   * at the midpoint. Currently, we do not scale the polynomials in any way,
+   * although better conditioning of the element stiffness matrix could
+   * possibly be achieved with scaling.
    *
    * Calling the constructor with a given index <tt>p</tt> will generate the
    * following: if <tt>p==0</tt>, then the resulting polynomial is the linear
@@ -518,15 +483,15 @@ namespace Polynomials
    * associated with the right vertex. For higher values of <tt>p</tt>, you
    * get the polynomial of degree <tt>p</tt> that is orthogonal to all
    * previous ones. Note that for <tt>p==0</tt> you therefore do <b>not</b>
-   * get a polynomial of degree zero, but one of degree one. This is to
-   * allow generating a complete basis for polynomial spaces, by just
-   * iterating over the indices given to the constructor.
+   * get a polynomial of degree zero, but one of degree one. This is to allow
+   * generating a complete basis for polynomial spaces, by just iterating over
+   * the indices given to the constructor.
    *
-   * On the other hand, the function generate_complete_basis() creates
-   * a complete basis of given degree. In order to be consistent with
-   * the concept of a polynomial degree, if the given argument is zero,
-   * it does <b>not</b> return the linear polynomial described above, but
-   * rather a constant polynomial.
+   * On the other hand, the function generate_complete_basis() creates a
+   * complete basis of given degree. In order to be consistent with the
+   * concept of a polynomial degree, if the given argument is zero, it does
+   * <b>not</b> return the linear polynomial described above, but rather a
+   * constant polynomial.
    *
    * @author Brian Carnes, 2002
    */
@@ -534,31 +499,20 @@ namespace Polynomials
   {
   public:
     /**
-     * Constructor for polynomial of
-     * degree <tt>p</tt>. There is an
-     * exception for <tt>p==0</tt>, see
-     * the general documentation.
+     * Constructor for polynomial of degree <tt>p</tt>. There is an exception
+     * for <tt>p==0</tt>, see the general documentation.
      */
     Hierarchical (const unsigned int p);
 
     /**
-     * Return a vector of
-     * Hierarchical polynomial
-     * objects of degrees zero through
-     * <tt>degree</tt>, which then spans
-     * the full space of polynomials
-     * up to the given degree. Note
-     * that there is an exception if
-     * the given <tt>degree</tt> equals
-     * zero, see the general
-     * documentation of this class.
+     * Return a vector of Hierarchical polynomial objects of degrees zero
+     * through <tt>degree</tt>, which then spans the full space of polynomials
+     * up to the given degree. Note that there is an exception if the given
+     * <tt>degree</tt> equals zero, see the general documentation of this
+     * class.
      *
-     * This function may be
-     * used to initialize the
-     * TensorProductPolynomials,
-     * AnisotropicPolynomials,
-     * and PolynomialSpace
-     * classes.
+     * This function may be used to initialize the TensorProductPolynomials,
+     * AnisotropicPolynomials, and PolynomialSpace classes.
      */
     static
     std::vector<Polynomial<double> >
@@ -571,26 +525,18 @@ namespace Polynomials
     static void compute_coefficients (const unsigned int p);
 
     /**
-     * Get coefficients for
-     * constructor.  This way, it can
-     * use the non-standard
-     * constructor of
-     * Polynomial.
+     * Get coefficients for constructor.  This way, it can use the non-
+     * standard constructor of Polynomial.
      */
     static const std::vector<double> &
     get_coefficients (const unsigned int p);
 
     /**
-     * Vector with already computed
-     * coefficients. For each degree of the
-     * polynomial, we keep one pointer to
-     * the list of coefficients; we do so
-     * rather than keeping a vector of
-     * vectors in order to simplify
-     * programming multithread-safe. In
-     * order to avoid memory leak, we use a
-     * shared_ptr in order to correctly
-     * free the memory of the vectors when
+     * Vector with already computed coefficients. For each degree of the
+     * polynomial, we keep one pointer to the list of coefficients; we do so
+     * rather than keeping a vector of vectors in order to simplify
+     * programming multithread-safe. In order to avoid memory leak, we use a
+     * shared_ptr in order to correctly free the memory of the vectors when
      * the global destructor is called.
      */
     static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > recursive_coefficients;
@@ -600,30 +546,23 @@ namespace Polynomials
   /**
    * Polynomials for Hermite interpolation condition.
    *
-   * This is the set of polynomials of degree at least three, such that
-   * the following interpolation conditions are met: the polynomials and
-   * their first derivatives vanish at the values <i>x</i>=0 and
-   * <i>x</i>=1, with the exceptions <i>p</i><sub>0</sub>(0)=1,
+   * This is the set of polynomials of degree at least three, such that the
+   * following interpolation conditions are met: the polynomials and their
+   * first derivatives vanish at the values <i>x</i>=0 and <i>x</i>=1, with
+   * the exceptions <i>p</i><sub>0</sub>(0)=1,
    * <i>p</i><sub><i>1</i></sub>(1)=1, <i>p</i>'<sub>2</sub>(0)=1,
    * <i>p'</i><sub>3</sub>(1)=1.
    *
-   * For degree three, we obtain the standard four Hermitian
-   * interpolation polynomials, see for instance <a
+   * For degree three, we obtain the standard four Hermitian interpolation
+   * polynomials, see for instance <a
    * href="http://en.wikipedia.org/wiki/Cubic_Hermite_spline">Wikipedia</a>.
-   * For higher degrees, these are augmented
-   * first, by the polynomial of degree four with vanishing values and
-   * derivatives at <i>x</i>=0 and <i>x</i>=1, then by the product of
-   * this fourth order polynomial with Legendre polynomials of
-   * increasing order. The implementation is
-   * @f{align*}{
-   * p_0(x) &= 2x^3-3x^2+1 \\
-   * p_1(x) &= -2x^2+3x^2 \\
-   * p_2(x) &= x^3-2x^2+x  \\
-   * p_3(x) &= x^3-x^2 \\
-   * p_4(x) &= 16x^2(x-1)^2 \\
-   * \ldots & \ldots \\
-   * p_k(x) &= x^2(x-1)^2 L_{k-4}(x)
-   * @f}
+   * For higher degrees, these are augmented first, by the polynomial of
+   * degree four with vanishing values and derivatives at <i>x</i>=0 and
+   * <i>x</i>=1, then by the product of this fourth order polynomial with
+   * Legendre polynomials of increasing order. The implementation is
+   * @f{align*}{ p_0(x) &= 2x^3-3x^2+1 \\ p_1(x) &= -2x^2+3x^2 \\ p_2(x) &=
+   * x^3-2x^2+x  \\ p_3(x) &= x^3-x^2 \\ p_4(x) &= 16x^2(x-1)^2 \\ \ldots &
+   * \ldots \\ p_k(x) &= x^2(x-1)^2 L_{k-4}(x) @f}
    *
    * @author Guido Kanschat
    * @date 2012
@@ -632,21 +571,15 @@ namespace Polynomials
   {
   public:
     /**
-                               * Constructor for polynomial
-                               * with index <tt>p</tt>. See
-                               * the class documentation on
-                               * the definition of the
-                               * sequence of polynomials.
-                               */
+     * Constructor for polynomial with index <tt>p</tt>. See the class
+     * documentation on the definition of the sequence of polynomials.
+     */
     HermiteInterpolation (const unsigned int p);
 
     /**
-     * Return the polynomials with index
-     * <tt>0</tt> up to
-     * <tt>p+1</tt> in a space of
-     * degree up to
-     * <tt>p</tt>. Here, <tt>p</tt>
-     * has to be at least 3.
+     * Return the polynomials with index <tt>0</tt> up to <tt>p+1</tt> in a
+     * space of degree up to <tt>p</tt>. Here, <tt>p</tt> has to be at least
+     * 3.
      */
     static std::vector<Polynomial<double> >
     generate_complete_basis (const unsigned int p);
index c866762ec58dacd654df34a3909f237231c0eb04..73fb3185e7ab39b0c9d75d3948b507d2aa9ad227 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Representation of the space of polynomials of degree at most n in
- * higher dimensions.
+ * Representation of the space of polynomials of degree at most n in higher
+ * dimensions.
  *
- * Given a vector of <i>n</i> one-dimensional polynomials
- * <i>P<sub>0</sub></i> to <i>P<sub>n</sub></i>, where
- * <i>P<sub>i</sub></i> has degree <i>i</i>, this class generates all
- * dim-dimensional polynomials of the form <i>
+ * Given a vector of <i>n</i> one-dimensional polynomials <i>P<sub>0</sub></i>
+ * to <i>P<sub>n</sub></i>, where <i>P<sub>i</sub></i> has degree <i>i</i>,
+ * this class generates all dim-dimensional polynomials of the form <i>
  * P<sub>ijk</sub>(x,y,z) =
- * P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>, where the sum
- * of <i>i</i>, <i>j</i> and <i>k</i> is less than or equal <i>n</i>.
+ * P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>, where the sum of
+ * <i>i</i>, <i>j</i> and <i>k</i> is less than or equal <i>n</i>.
  *
- * The output_indices() function prints the ordering of the
- * polynomials, i.e. for each dim-dimensional polynomial in the
- * polynomial space it gives the indices i,j,k of the one-dimensional
- * polynomials in x,y and z direction. The ordering of the
- * dim-dimensional polynomials can be changed by using the
+ * The output_indices() function prints the ordering of the polynomials, i.e.
+ * for each dim-dimensional polynomial in the polynomial space it gives the
+ * indices i,j,k of the one-dimensional polynomials in x,y and z direction.
+ * The ordering of the dim-dimensional polynomials can be changed by using the
  * set_numbering() function.
  *
- * The standard ordering of polynomials is that indices for the first
- * space dimension vary fastest and the last space dimension is
- * slowest. In particular, if we take for simplicity the vector of
- * monomials <i>x<sup>0</sup>, x<sup>1</sup>, x<sup>2</sup>,...,
- * x<sup>n</sup></i>, we get
+ * The standard ordering of polynomials is that indices for the first space
+ * dimension vary fastest and the last space dimension is slowest. In
+ * particular, if we take for simplicity the vector of monomials
+ * <i>x<sup>0</sup>, x<sup>1</sup>, x<sup>2</sup>,..., x<sup>n</sup></i>, we
+ * get
  *
- * <dl>
- * <dt> 1D <dd> <i> x<sup>0</sup>, x<sup>1</sup>,...,x<sup>n</sup></i>
+ * <dl> <dt> 1D <dd> <i> x<sup>0</sup>, x<sup>1</sup>,...,x<sup>n</sup></i>
  * <dt> 2D: <dd> <i> x<sup>0</sup>y<sup>0</sup>,
- *    x<sup>1</sup>y<sup>0</sup>,...,
- *    x<sup>n</sup>y<sup>0</sup>,<br>
- *    x<sup>0</sup>y<sup>1</sup>,
- *    x<sup>1</sup>y<sup>1</sup>,...,
- *    x<sup>n-1</sup>y<sup>1</sup>,<br>
- *    x<sup>0</sup>y<sup>2</sup>,...
- *    x<sup>n-2</sup>y<sup>2</sup>,<br>...<br>
- *    x<sup>0</sup>y<sup>n-1</sup>,
- *    x<sup>1</sup>y<sup>n-1</sup>,<br>
- *    x<sup>0</sup>y<sup>n</sup>
- *    </i>
- * <dt> 3D: <dd> <i> x<sup>0</sup>y<sup>0</sup>z<sup>0</sup>,...,
- *    x<sup>n</sup>y<sup>0</sup>z<sup>0</sup>,<br>
- *    x<sup>0</sup>y<sup>1</sup>z<sup>0</sup>,...,
- *    x<sup>n-1</sup>y<sup>1</sup>z<sup>0</sup>,<br>...<br>
- *    x<sup>0</sup>y<sup>n</sup>z<sup>0</sup>,<br>
- *    x<sup>0</sup>y<sup>0</sup>z<sup>1</sup>,...
- *    x<sup>n-1</sup>y<sup>0</sup>z<sup>1</sup>,<br>...<br>
- *    x<sup>0</sup>y<sup>n-1</sup>z<sup>1</sup>,<br>
- *    x<sup>0</sup>y<sup>0</sup>z<sup>2</sup>,...
- *    x<sup>n-2</sup>y<sup>0</sup>z<sup>2</sup>,<br>...<br>
- *    x<sup>0</sup>y<sup>0</sup>z<sup>n</sup>
- *    </i>
- * </dl>
+ * x<sup>1</sup>y<sup>0</sup>,...,
+ * x<sup>n</sup>y<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>1</sup>, x<sup>1</sup>y<sup>1</sup>,...,
+ * x<sup>n-1</sup>y<sup>1</sup>,<br>
+ * x<sup>0</sup>y<sup>2</sup>,...
+ * x<sup>n-2</sup>y<sup>2</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n-1</sup>,
+ * x<sup>1</sup>y<sup>n-1</sup>,<br>
+ * x<sup>0</sup>y<sup>n</sup> </i> <dt> 3D: <dd> <i>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>0</sup>,...,
+ * x<sup>n</sup>y<sup>0</sup>z<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>1</sup>z<sup>0</sup>,...,
+ * x<sup>n-1</sup>y<sup>1</sup>z<sup>0</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n</sup>z<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>1</sup>,...
+ * x<sup>n-1</sup>y<sup>0</sup>z<sup>1</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n-1</sup>z<sup>1</sup>,<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>2</sup>,...
+ * x<sup>n-2</sup>y<sup>0</sup>z<sup>2</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>n</sup> </i> </dl>
  *
  * @ingroup Polynomials
- * @author Guido Kanschat, Wolfgang Bangerth, Ralf Hartmann 2002, 2003, 2004, 2005
+ * @author Guido Kanschat, Wolfgang Bangerth, Ralf Hartmann 2002, 2003, 2004,
+ * 2005
  */
 template <int dim>
 class PolynomialSpace
 {
 public:
   /**
-   * Access to the dimension of
-   * this object, for checking and
-   * automatic setting of dimension
-   * in other classes.
+   * Access to the dimension of this object, for checking and automatic
+   * setting of dimension in other classes.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Constructor. <tt>pols</tt> is a
-   * vector of pointers to
-   * one-dimensional polynomials
-   * and will be copied into a
-   * private member variable. The static
-   * type of the template argument
-   * <tt>pols</tt> needs to be
-   * convertible to
-   * Polynomials::Polynomial@<double@>,
-   * i.e. should usually be a
-   * derived class of
-   * Polynomials::Polynomial@<double@>.
+   * Constructor. <tt>pols</tt> is a vector of pointers to one-dimensional
+   * polynomials and will be copied into a private member variable. The static
+   * type of the template argument <tt>pols</tt> needs to be convertible to
+   * Polynomials::Polynomial@<double@>, i.e. should usually be a derived class
+   * of Polynomials::Polynomial@<double@>.
    */
   template <class Pol>
   PolynomialSpace (const std::vector<Pol> &pols);
 
   /**
-   * Prints the list of the indices
-   * to <tt>out</tt>.
+   * Prints the list of the indices to <tt>out</tt>.
    */
   template <class STREAM>
   void output_indices(STREAM &out) const;
 
   /**
-   * Sets the ordering of the
-   * polynomials. Requires
-   * <tt>renumber.size()==n()</tt>.
-   * Stores a copy of
-   * <tt>renumber</tt>.
+   * Sets the ordering of the polynomials. Requires
+   * <tt>renumber.size()==n()</tt>. Stores a copy of <tt>renumber</tt>.
    */
   void set_numbering(const std::vector<unsigned int> &renumber);
 
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the value and the first and second derivatives of each
+   * polynomial at <tt>unit_point</tt>.
    *
-   * The size of the vectors must
-   * either be equal 0 or equal
-   * n(). In the first case,
-   * the function will not compute
-   * these values, i.e. you
-   * indicate what you want to have
-   * computed by resizing those
-   * vectors which you want filled.
+   * The size of the vectors must either be equal 0 or equal n(). In the first
+   * case, the function will not compute these values, i.e. you indicate what
+   * you want to have computed by resizing those vectors which you want
+   * filled.
    *
-   * If you need values or
-   * derivatives of all polynomials
-   * then use this function, rather
-   * than using any of the
-   * compute_value(),
-   * compute_grad() or
-   * compute_grad_grad()
-   * functions, see below, in a
-   * loop over all polynomials.
+   * If you need values or derivatives of all polynomials then use this
+   * function, rather than using any of the compute_value(), compute_grad() or
+   * compute_grad_grad() functions, see below, in a loop over all polynomials.
    */
   void compute (const Point<dim>            &unit_point,
                 std::vector<double>         &values,
@@ -160,9 +129,7 @@ public:
                 std::vector<Tensor<2,dim> > &grad_grads) const;
 
   /**
-   * Computes the value of the
-   * <tt>i</tt>th polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the value of the <tt>i</tt>th polynomial at <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
    */
@@ -170,8 +137,7 @@ public:
                         const Point<dim> &p) const;
 
   /**
-   * Computes the gradient of the
-   * <tt>i</tt>th polynomial at
+   * Computes the gradient of the <tt>i</tt>th polynomial at
    * <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
@@ -180,10 +146,8 @@ public:
                               const Point<dim> &p) const;
 
   /**
-   * Computes the second derivative
-   * (grad_grad) of the <tt>i</tt>th
-   * polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the second derivative (grad_grad) of the <tt>i</tt>th polynomial
+   * at <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
    */
@@ -191,46 +155,32 @@ public:
                                    const Point<dim> &p) const;
 
   /**
-   * Return the number of
-   * polynomials spanning the space
-   * represented by this
-   * class. Here, if <tt>N</tt> is the
-   * number of one-dimensional
-   * polynomials given, then the
-   * result of this function is
-   * <i>N</i> in 1d, <i>N(N+1)/2</i> in
-   * 2d, and <i>N(N+1)(N+2)/6</i> in
-   * 3d.
+   * Return the number of polynomials spanning the space represented by this
+   * class. Here, if <tt>N</tt> is the number of one-dimensional polynomials
+   * given, then the result of this function is <i>N</i> in 1d,
+   * <i>N(N+1)/2</i> in 2d, and <i>N(N+1)(N+2)/6</i> in 3d.
    */
   unsigned int n () const;
 
   /**
-   * Degree of the space. This is
-   * by definition the number of
-   * polynomials given to the
-   * constructor, NOT the maximal
-   * degree of a polynomial in this
-   * vector. The latter value is
-   * never checked and therefore
-   * left to the application.
+   * Degree of the space. This is by definition the number of polynomials
+   * given to the constructor, NOT the maximal degree of a polynomial in this
+   * vector. The latter value is never checked and therefore left to the
+   * application.
    */
   unsigned int degree () const;
 
   /**
-   * Static function used in the
-   * constructor to compute the
-   * number of polynomials.
+   * Static function used in the constructor to compute the number of
+   * polynomials.
    */
   static unsigned int compute_n_pols (const unsigned int n);
 
 protected:
 
   /**
-   * Compute numbers in x, y and z
-   * direction. Given an index
-   * <tt>n</tt> in the d-dimensional
-   * polynomial space, compute the
-   * indices i,j,k such that
+   * Compute numbers in x, y and z direction. Given an index <tt>n</tt> in the
+   * d-dimensional polynomial space, compute the indices i,j,k such that
    * <i>p<sub>n</sub>(x,y,z) =
    * p<sub>i</sub>(x)p<sub>j</sub>(y)p<sub>k</sub>(z)</i>.
    */
@@ -239,28 +189,22 @@ protected:
 
 private:
   /**
-   * Copy of the vector <tt>pols</tt> of
-   * polynomials given to the
-   * constructor.
+   * Copy of the vector <tt>pols</tt> of polynomials given to the constructor.
    */
   const std::vector<Polynomials::Polynomial<double> > polynomials;
 
   /**
-   * Store the precomputed value
-   * which the <tt>n()</tt> function
-   * returns.
+   * Store the precomputed value which the <tt>n()</tt> function returns.
    */
   const unsigned int n_pols;
 
   /**
-   * Index map for reordering the
-   * polynomials.
+   * Index map for reordering the polynomials.
    */
   std::vector<unsigned int> index_map;
 
   /**
-   * Index map for reordering the
-   * polynomials.
+   * Index map for reordering the polynomials.
    */
   std::vector<unsigned int> index_map_inverse;
 };
index 7ed9e15e88953a36046a9ad0a781ef2cbc0490e5..7d637848b291a1a994286072051b7443ca8afc0e 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Arnold-Boffi-Falk polynomials as described in the
- * article by Arnold-Boffi-Falk:
- * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal.
- * Vol.42, No.6, pp.2429-2451
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Arnold-Boffi-Falk polynomials as described in the article by Arnold-Boffi-
+ * Falk: Quadrilateral H(div) finite elements, SIAM J. Numer. Anal. Vol.42,
+ * No.6, pp.2429-2451
  *
  *
- * The ABF polynomials are constructed such that the
- * divergence is in the tensor product polynomial space
- * <i>Q<sub>k</sub></i>. Therefore, the polynomial order of each
- * component must be two orders higher in the corresponding direction,
- * yielding the polynomial spaces <i>(Q<sub>k+2,k</sub>,
- * Q<sub>k,k+2</sub>)</i> and <i>(Q<sub>k+2,k,k</sub>,
+ * The ABF polynomials are constructed such that the divergence is in the
+ * tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be two orders higher in the
+ * corresponding direction, yielding the polynomial spaces
+ * <i>(Q<sub>k+2,k</sub>, Q<sub>k,k+2</sub>)</i> and <i>(Q<sub>k+2,k,k</sub>,
  * Q<sub>k,k+2,k</sub>, Q<sub>k,k,k+2</sub>)</i> in 2D and 3D, resp.
  *
  * @ingroup Polynomials
@@ -56,15 +54,12 @@ class PolynomialsABF
 {
 public:
   /**
-   * Constructor. Creates all basis
-   * functions for Raviart-Thomas polynomials
+   * Constructor. Creates all basis functions for Raviart-Thomas polynomials
    * of given degree.
    *
-   * @arg k: the degree of the
-   * Raviart-Thomas-space, which is the degree
-   * of the largest tensor product
-   * polynomial space
-   * <i>Q<sub>k</sub></i> contained.
+   * @arg k: the degree of the Raviart-Thomas-space, which is the degree of
+   * the largest tensor product polynomial space <i>Q<sub>k</sub></i>
+   * contained.
    */
   PolynomialsABF (const unsigned int k);
 
@@ -74,28 +69,16 @@ public:
   ~PolynomialsABF ();
 
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each Raviart-Thomas
-   * polynomial at @p unit_point.
+   * Computes the value and the first and second derivatives of each Raviart-
+   * Thomas polynomial at @p unit_point.
    *
-   * The size of the vectors must
-   * either be zero or equal
-   * <tt>n()</tt>.  In the
-   * first case, the function will
-   * not compute these values.
+   * The size of the vectors must either be zero or equal <tt>n()</tt>.  In
+   * the first case, the function will not compute these values.
    *
-   * If you need values or
-   * derivatives of all tensor
-   * product polynomials then use
-   * this function, rather than
-   * using any of the
-   * <tt>compute_value</tt>,
-   * <tt>compute_grad</tt> or
-   * <tt>compute_grad_grad</tt>
-   * functions, see below, in a
-   * loop over all tensor product
-   * polynomials.
+   * If you need values or derivatives of all tensor product polynomials then
+   * use this function, rather than using any of the <tt>compute_value</tt>,
+   * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+   * in a loop over all tensor product polynomials.
    */
   void compute (const Point<dim>            &unit_point,
                 std::vector<Tensor<1,dim> > &values,
@@ -108,54 +91,42 @@ public:
   unsigned int n () const;
 
   /**
-   * Returns the degree of the ABF
-   * space, which is two less than
-   * the highest polynomial degree.
+   * Returns the degree of the ABF space, which is two less than the highest
+   * polynomial degree.
    */
   unsigned int degree () const;
 
   /**
-   * Return the name of the space,
-   * which is <tt>ABF</tt>.
+   * Return the name of the space, which is <tt>ABF</tt>.
    */
   std::string name () const;
 
   /**
-   * Return the number of
-   * polynomials in the space
-   * <TT>RT(degree)</tt> without
-   * requiring to build an object
-   * of PolynomialsABF. This is
-   * required by the FiniteElement
-   * classes.
+   * Return the number of polynomials in the space <TT>RT(degree)</tt> without
+   * requiring to build an object of PolynomialsABF. This is required by the
+   * FiniteElement classes.
    */
   static unsigned int compute_n_pols(unsigned int degree);
 
 private:
   /**
-   * The degree of this object as
-   * given to the constructor.
+   * The degree of this object as given to the constructor.
    */
   const unsigned int my_degree;
 
   /**
-   * An object representing the
-   * polynomial space for a single
-   * component. We can re-use it by
-   * rotating the coordinates of
-   * the evaluation point.
+   * An object representing the polynomial space for a single component. We
+   * can re-use it by rotating the coordinates of the evaluation point.
    */
   AnisotropicPolynomials<dim> *polynomial_space;
 
   /**
-   * Number of Raviart-Thomas
-   * polynomials.
+   * Number of Raviart-Thomas polynomials.
    */
   unsigned int n_pols;
 
   /**
-   * A mutex that guards the
-   * following scratch arrays.
+   * A mutex that guards the following scratch arrays.
    */
   mutable Threads::Mutex mutex;
 
index c3be076ee1e61bddc6d9cf3e570a15cc907a529d..899870bbbdf01b81bcd9b7dd0f97ee47f7d478b3 100644 (file)
@@ -26,12 +26,11 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * The cubic polynomial space for the Adini element
  *
- * This space consists of the cubic space <i>P<sub>3</sub></i>
- * augmented by the functions <i>xy<sup>3</sup></i> and
- * <i>x<sup>3</sup>y</i>.
+ * This space consists of the cubic space <i>P<sub>3</sub></i> augmented by
+ * the functions <i>xy<sup>3</sup></i> and <i>x<sup>3</sup>y</i>.
  *
- * The basis of the space is chosen to match the node functionals of
- * the Adini element.
+ * The basis of the space is chosen to match the node functionals of the Adini
+ * element.
  *
  * @todo This polynomial space is implemented in 2D only.
  *
@@ -42,35 +41,21 @@ class PolynomialsAdini
 {
 public:
   /**
-   * Constructor for
-   * the polynomials of
-   * the described space
+   * Constructor for the polynomials of the described space
    */
   PolynomialsAdini ();
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the value and the first and second derivatives of each
+   * polynomial at <tt>unit_point</tt>.
    *
-   * The size of the vectors must
-   * either be equal 0 or equal
-   * n(). In the first case,
-   * the function will not compute
-   * these values, i.e. you
-   * indicate what you want to have
-   * computed by resizing those
-   * vectors which you want filled.
+   * The size of the vectors must either be equal 0 or equal n(). In the first
+   * case, the function will not compute these values, i.e. you indicate what
+   * you want to have computed by resizing those vectors which you want
+   * filled.
    *
-   * If you need values or
-   * derivatives of all polynomials
-   * then use this function, rather
-   * than using any of the
-   * compute_value(),
-   * compute_grad() or
-   * compute_grad_grad()
-   * functions, see below, in a
-   * loop over all polynomials.
+   * If you need values or derivatives of all polynomials then use this
+   * function, rather than using any of the compute_value(), compute_grad() or
+   * compute_grad_grad() functions, see below, in a loop over all polynomials.
    */
 
   void compute (const Point<2> &unit_point,
@@ -79,9 +64,7 @@ public:
                 std::vector< Tensor<2,2> > &grad_grads) const;
 
   /**
-   * Computes the value of the
-   * <tt>i</tt>th polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the value of the <tt>i</tt>th polynomial at <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
    */
@@ -90,8 +73,7 @@ public:
                         const Point<2> &p) const;
 
   /**
-   * Computes the gradient of the
-   * <tt>i</tt>th polynomial at
+   * Computes the gradient of the <tt>i</tt>th polynomial at
    * <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
@@ -100,10 +82,8 @@ public:
   Tensor<1,2> compute_grad (const unsigned int i,
                             const Point<2> &p) const;
   /**
-   * Computes the second derivative
-   * (grad_grad) of the <tt>i</tt>th
-   * polynomial at
-   * <tt>unit_point</tt>.
+   * Computes the second derivative (grad_grad) of the <tt>i</tt>th polynomial
+   * at <tt>unit_point</tt>.
    *
    * Consider using compute() instead.
    */
@@ -113,42 +93,36 @@ public:
 
 private:
   /**
-   * Store the coefficients of the
-   * polynominals in the order
+   * Store the coefficients of the polynominals in the order
    * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
   Table<2, double> coef;
 
   /**
-   * Store the coefficients of the x-derivative
-   * of the polynominals in the order
-   * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+   * Store the coefficients of the x-derivative of the polynominals in the
+   * order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
 
   Table<2, double> dx;
   /**
-   * Store the coefficients of the y-derivative
-   * of the polynominals in the order
-   * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+   * Store the coefficients of the y-derivative of the polynominals in the
+   * order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
 
   Table<2, double> dy;
   /**
-   * Store the coefficients of the second x-derivative
-   * of the polynominals in the order
-   * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+   * Store the coefficients of the second x-derivative of the polynominals in
+   * the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
   Table<2, double> dxx;
   /**
-   * Store the coefficients of the second y-derivative
-   * of the polynominals in the order
-   * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+   * Store the coefficients of the second y-derivative of the polynominals in
+   * the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
   Table<2, double> dyy;
   /**
-   * Store the coefficients of the second mixed derivative
-   * of the polynominals in the order
-   * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+   * Store the coefficients of the second mixed derivative of the polynominals
+   * in the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
    */
   Table<2, double> dxy;
 
index 287735272697d3fc7ed4b8ed31cfee7ecbed911e..6d43fc470e05588ebefd9734797e3910555deae6 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Brezzi-Douglas-Marini polynomials as described in the
- * book by Brezzi and Fortin.
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Brezzi-Douglas-Marini polynomials as described in the book by Brezzi and
+ * Fortin.
  *
- * These polynomial spaces are based on the space
- * <i>P<sub>k</sub></i>, realized by a PolynomialSpace constructed
- * with Legendre polynomials. Since these shape functions are not
- * sufficient, additional functions are added. These are the following
- * vector valued polynomials:
+ * These polynomial spaces are based on the space <i>P<sub>k</sub></i>,
+ * realized by a PolynomialSpace constructed with Legendre polynomials. Since
+ * these shape functions are not sufficient, additional functions are added.
+ * These are the following vector valued polynomials:
  *
- * <dl>
- * <dt> In 2D:
- * <dd> The 2D-curl of the functions <i>x<sup>k+1</sup>y</i>
- * and <i>xy<sup>k+1</sup></i>.
- * <dt>In 3D:
- * <dd> For any <i>i=0,...,k</i> the curls of
- * <i>(0,0,xy<sup>i+1</sup>z<sup>k-i</sup>)</i>,
+ * <dl> <dt> In 2D: <dd> The 2D-curl of the functions <i>x<sup>k+1</sup>y</i>
+ * and <i>xy<sup>k+1</sup></i>. <dt>In 3D: <dd> For any <i>i=0,...,k</i> the
+ * curls of <i>(0,0,xy<sup>i+1</sup>z<sup>k-i</sup>)</i>,
  * <i>(x<sup>k-i</sup>yz<sup>i+1</sup>,0,0)</i> and
- * <i>(0,x<sup>i+1</sup>y<sup>k-i</sup>z,0)</i>
- * </dl>
+ * <i>(0,x<sup>i+1</sup>y<sup>k-i</sup>z,0)</i> </dl>
  *
  * @todo Second derivatives in 3D are missing.
  *
@@ -63,42 +57,26 @@ class PolynomialsBDM
 {
 public:
   /**
-   * Constructor. Creates all basis
-   * functions for BDM polynomials
-   * of given degree.
+   * Constructor. Creates all basis functions for BDM polynomials of given
+   * degree.
    *
-   * @arg k: the degree of the
-   * BDM-space, which is the degree
-   * of the largest complete
-   * polynomial space
-   * <i>P<sub>k</sub></i> contained
-   * in the BDM-space.
+   * @arg k: the degree of the BDM-space, which is the degree of the largest
+   * complete polynomial space <i>P<sub>k</sub></i> contained in the BDM-
+   * space.
    */
   PolynomialsBDM (const unsigned int k);
 
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each BDM
+   * Computes the value and the first and second derivatives of each BDM
    * polynomial at @p unit_point.
    *
-   * The size of the vectors must
-   * either be zero or equal
-   * <tt>n()</tt>.  In the
-   * first case, the function will
-   * not compute these values.
+   * The size of the vectors must either be zero or equal <tt>n()</tt>.  In
+   * the first case, the function will not compute these values.
    *
-   * If you need values or
-   * derivatives of all tensor
-   * product polynomials then use
-   * this function, rather than
-   * using any of the
-   * <tt>compute_value</tt>,
-   * <tt>compute_grad</tt> or
-   * <tt>compute_grad_grad</tt>
-   * functions, see below, in a
-   * loop over all tensor product
-   * polynomials.
+   * If you need values or derivatives of all tensor product polynomials then
+   * use this function, rather than using any of the <tt>compute_value</tt>,
+   * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+   * in a loop over all tensor product polynomials.
    */
   void compute (const Point<dim>            &unit_point,
                 std::vector<Tensor<1,dim> > &values,
@@ -111,56 +89,43 @@ public:
   unsigned int n () const;
 
   /**
-   * Returns the degree of the BDM
-   * space, which is one less than
-   * the highest polynomial degree.
+   * Returns the degree of the BDM space, which is one less than the highest
+   * polynomial degree.
    */
   unsigned int degree () const;
 
   /**
-   * Return the name of the space,
-   * which is <tt>BDM</tt>.
+   * Return the name of the space, which is <tt>BDM</tt>.
    */
   std::string name () const;
 
   /**
-   * Return the number of
-   * polynomials in the space
-   * <TT>BDM(degree)</tt> without
-   * requiring to build an object
-   * of PolynomialsBDM. This is
-   * required by the FiniteElement
-   * classes.
+   * Return the number of polynomials in the space <TT>BDM(degree)</tt>
+   * without requiring to build an object of PolynomialsBDM. This is required
+   * by the FiniteElement classes.
    */
   static unsigned int compute_n_pols(unsigned int degree);
 
 private:
   /**
-   * An object representing the
-   * polynomial space used
-   * here. The constructor fills
-   * this with the monomial basis.
+   * An object representing the polynomial space used here. The constructor
+   * fills this with the monomial basis.
    */
   const PolynomialSpace<dim> polynomial_space;
 
   /**
-   * Storage for monomials. In 2D,
-   * this is just the polynomial of
-   * order <i>k</i>. In 3D, we
-   * need all polynomials from
-   * degree zero to <i>k</i>.
+   * Storage for monomials. In 2D, this is just the polynomial of order
+   * <i>k</i>. In 3D, we need all polynomials from degree zero to <i>k</i>.
    */
   std::vector<Polynomials::Polynomial<double> > monomials;
 
   /**
-   * Number of BDM
-   * polynomials.
+   * Number of BDM polynomials.
    */
   unsigned int n_pols;
 
   /**
-   * A mutex that guards the
-   * following scratch arrays.
+   * A mutex that guards the following scratch arrays.
    */
   mutable Threads::Mutex mutex;
 
index 50451dc668377fa4285ffa96219874830fd3d351..154963005ef64a6dd6c277e81e9aa5765de4153f 100644 (file)
@@ -33,16 +33,16 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * This class implements the first family <i>H<sup>curl</sup></i>-conforming,
- * vector-valued polynomials, proposed by J.-C. Nédélec in 1980
- * (Numer. Math. 35).
+ * vector-valued polynomials, proposed by J.-C. Nédélec in 1980 (Numer.
+ * Math. 35).
  *
- * The Nédélec polynomials are constructed such that the curl
- * is in the tensor product polynomial space <i>Q<sub>k</sub></i>.
- * Therefore, the polynomial order of each component must be one
- * order higher in the corresponding two directions,
- * yielding the polynomial spaces <i>(Q<sub>k,k+1</sub>,
- * Q<sub>k+1,k</sub>)</i> and <i>(Q<sub>k,k+1,k+1</sub>,
- * Q<sub>k+1,k,k+1</sub>, Q<sub>k+1,k+1,k</sub>)</i> in 2D and 3D, resp.
+ * The Nédélec polynomials are constructed such that the curl is in the
+ * tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be one order higher in the
+ * corresponding two directions, yielding the polynomial spaces
+ * <i>(Q<sub>k,k+1</sub>, Q<sub>k+1,k</sub>)</i> and
+ * <i>(Q<sub>k,k+1,k+1</sub>, Q<sub>k+1,k,k+1</sub>,
+ * Q<sub>k+1,k+1,k</sub>)</i> in 2D and 3D, resp.
  *
  * @ingroup Polynomials
  * @author Markus Bürg
@@ -53,87 +53,60 @@ class PolynomialsNedelec
 {
 public:
   /**
-   * Constructor. Creates all basis
-   * functions for Nédélec polynomials
-   * of given degree.
+   * Constructor. Creates all basis functions for Nédélec polynomials of
+   * given degree.
    *
-   * @arg k: the degree of the
-   * Nédélec space, which is the degree
-   * of the largest tensor product
-   * polynomial space
-   * <i>Q<sub>k</sub></i> contained.
+   * @arg k: the degree of the Nédélec space, which is the degree of the
+   * largest tensor product polynomial space <i>Q<sub>k</sub></i> contained.
    */
   PolynomialsNedelec (const unsigned int k);
 
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each Nédélec
+   * Computes the value and the first and second derivatives of each Nédélec
    * polynomial at @p unit_point.
    *
-   * The size of the vectors must
-   * either be zero or equal
-   * <tt>n()</tt>.  In the
-   * first case, the function will
-   * not compute these values.
+   * The size of the vectors must either be zero or equal <tt>n()</tt>.  In
+   * the first case, the function will not compute these values.
    *
-   * If you need values or
-   * derivatives of all tensor
-   * product polynomials then use
-   * this function, rather than
-   * using any of the
-   * <tt>compute_value</tt>,
-   * <tt>compute_grad</tt> or
-   * <tt>compute_grad_grad</tt>
-   * functions, see below, in a
-   * loop over all tensor product
-   * polynomials.
+   * If you need values or derivatives of all tensor product polynomials then
+   * use this function, rather than using any of the <tt>compute_value</tt>,
+   * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+   * in a loop over all tensor product polynomials.
    */
   void compute (const Point<dim> &unit_point, std::vector<Tensor<1, dim> > &values, std::vector<Tensor<2, dim> > &grads, std::vector<Tensor<3, dim> > &grad_grads) const;
 
   /**
-   * Returns the number of Nédélec
-     * polynomials.
+   * Returns the number of Nédélec polynomials.
    */
   unsigned int n () const;
 
   /**
-   * Returns the degree of the Nédélec
-   * space, which is one less than
-   * the highest polynomial degree.
+   * Returns the degree of the Nédélec space, which is one less than the
+   * highest polynomial degree.
    */
   unsigned int degree () const;
 
   /**
-   * Return the name of the space,
-   * which is <tt>Nedelec</tt>.
+   * Return the name of the space, which is <tt>Nedelec</tt>.
    */
   std::string name () const;
 
   /**
-   * Return the number of
-   * polynomials in the space
-   * <TT>N(degree)</tt> without
-   * requiring to build an object
-   * of PolynomialsNedelec. This is
-   * required by the FiniteElement
-   * classes.
+   * Return the number of polynomials in the space <TT>N(degree)</tt> without
+   * requiring to build an object of PolynomialsNedelec. This is required by
+   * the FiniteElement classes.
    */
   static unsigned int compute_n_pols (unsigned int degree);
 
 private:
   /**
-   * The degree of this object as
-   * given to the constructor.
+   * The degree of this object as given to the constructor.
    */
   const unsigned int my_degree;
 
   /**
-   * An object representing the
-   * polynomial space for a single
-   * component. We can re-use it by
-   * rotating the coordinates of
-   * the evaluation point.
+   * An object representing the polynomial space for a single component. We
+   * can re-use it by rotating the coordinates of the evaluation point.
    */
   const AnisotropicPolynomials<dim> polynomial_space;
 
@@ -143,11 +116,8 @@ private:
   const unsigned int n_pols;
 
   /**
-   * A static member function that
-   * creates the polynomial space
-   * we use to initialize the
-   * #polynomial_space member
-   * variable.
+   * A static member function that creates the polynomial space we use to
+   * initialize the #polynomial_space member variable.
    */
   static std::vector<std::vector< Polynomials::Polynomial< double > > > create_polynomials (const unsigned int k);
 };
index 4e8cc6c894f82e048643fd9a8941ebd36ec78bc5..7102ecfb5da2ea4e52c4d27d939776528da9939e 100644 (file)
@@ -34,14 +34,13 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * This class implements the polynomial space of degree <tt>p</tt>
- * based on the monomials ${1,x,x^2,...}$. I.e. in <tt>d</tt>
- * dimensions it constructs all polynomials of the form $\prod_{i=1}^d
- * x_i^{n_i}$, where $\sum_i n_i\leq p$. The base polynomials are
- * given a specific ordering, e.g. in 2 dimensions:
- * ${1,x,y,xy,x^2,y^2,x^2y,xy^2,x^3,y^3,...}$. The ordering of the
- * monomials in $P_k1$ matches the ordering of the monomials in $P_k2$
- * for $k2>k1$.
+ * This class implements the polynomial space of degree <tt>p</tt> based on
+ * the monomials ${1,x,x^2,...}$. I.e. in <tt>d</tt> dimensions it constructs
+ * all polynomials of the form $\prod_{i=1}^d x_i^{n_i}$, where $\sum_i
+ * n_i\leq p$. The base polynomials are given a specific ordering, e.g. in 2
+ * dimensions: ${1,x,y,xy,x^2,y^2,x^2y,xy^2,x^3,y^3,...}$. The ordering of the
+ * monomials in $P_k1$ matches the ordering of the monomials in $P_k2$ for
+ * $k2>k1$.
  *
  * @author Ralf Hartmann, 2004
  */
@@ -50,39 +49,28 @@ class PolynomialsP: public PolynomialSpace<dim>
 {
 public:
   /**
-   * Access to the dimension of
-   * this object, for checking and
-   * automatic setting of dimension
-   * in other classes.
+   * Access to the dimension of this object, for checking and automatic
+   * setting of dimension in other classes.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Constructor. Creates all basis
-   * functions of $P_p$.
-   * @arg p: the degree of the
-   * polynomial space
+   * Constructor. Creates all basis functions of $P_p$. @arg p: the degree of
+   * the polynomial space
    */
   PolynomialsP (const unsigned int p);
 
   /**
-   * Returns the degree <tt>p</tt>
-   * of the polynomial space
-   * <tt>P_p</tt>.
+   * Returns the degree <tt>p</tt> of the polynomial space <tt>P_p</tt>.
    *
-   * Note, that this number is
-   * <tt>PolynomialSpace::degree()-1</tt>,
-   * compare definition in
-   * PolynomialSpace.
+   * Note, that this number is <tt>PolynomialSpace::degree()-1</tt>, compare
+   * definition in PolynomialSpace.
    */
   unsigned int degree() const;
 
   /**
-   * For the <tt>n</tt>th
-   * polynomial $p_n(x,y,z)=x^i y^j
-   * z^k$ this function gives the
-   * degrees i,j,k in the x,y,z
-   * directions.
+   * For the <tt>n</tt>th polynomial $p_n(x,y,z)=x^i y^j z^k$ this function
+   * gives the degrees i,j,k in the x,y,z directions.
    */
   void directional_degrees(unsigned int n,
                            unsigned int (&degrees)[dim]) const;
@@ -95,11 +83,8 @@ private:
   void create_polynomial_ordering(std::vector<unsigned int> &index_map) const;
 
   /**
-   * Degree <tt>p</tt> of the
-   * polynomial space $P_p$,
-   * i.e. the number <tt>p</tt>
-   * which was given to the
-   * constructor.
+   * Degree <tt>p</tt> of the polynomial space $P_p$, i.e. the number
+   * <tt>p</tt> which was given to the constructor.
    */
   const unsigned int p;
 };
index 1fbcb81ad5d8c800d9f8f0552801ea9a6ac04d47..2d4ed5bb017bd5240c95fae92cc4679ee9549163 100644 (file)
@@ -123,8 +123,7 @@ namespace Polynomials
     unsigned int n_intervals;
 
     /**
-     * Stores the index of the current polynomial in the range of
-     * intervals.
+     * Stores the index of the current polynomial in the range of intervals.
      */
     unsigned int interval;
 
index b7523a8d969ca46c5951b957dd51e68b9cbc69ef..36a00a4604d512bc9164105e3c2b071c1a731937 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Raviart-Thomas polynomials as described in the
- * book by Brezzi and Fortin.
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Raviart-Thomas polynomials as described in the book by Brezzi and Fortin.
  *
- * The Raviart-Thomas polynomials are constructed such that the
- * divergence is in the tensor product polynomial space
- * <i>Q<sub>k</sub></i>. Therefore, the polynomial order of each
- * component must be one order higher in the corresponding direction,
- * yielding the polynomial spaces <i>(Q<sub>k+1,k</sub>,
- * Q<sub>k,k+1</sub>)</i> and <i>(Q<sub>k+1,k,k</sub>,
+ * The Raviart-Thomas polynomials are constructed such that the divergence is
+ * in the tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be one order higher in the
+ * corresponding direction, yielding the polynomial spaces
+ * <i>(Q<sub>k+1,k</sub>, Q<sub>k,k+1</sub>)</i> and <i>(Q<sub>k+1,k,k</sub>,
  * Q<sub>k,k+1,k</sub>, Q<sub>k,k,k+1</sub>)</i> in 2D and 3D, resp.
  *
  * @ingroup Polynomials
@@ -52,41 +50,26 @@ class PolynomialsRaviartThomas
 {
 public:
   /**
-   * Constructor. Creates all basis
-   * functions for Raviart-Thomas polynomials
+   * Constructor. Creates all basis functions for Raviart-Thomas polynomials
    * of given degree.
    *
-   * @arg k: the degree of the
-   * Raviart-Thomas-space, which is the degree
-   * of the largest tensor product
-   * polynomial space
-   * <i>Q<sub>k</sub></i> contains.
+   * @arg k: the degree of the Raviart-Thomas-space, which is the degree of
+   * the largest tensor product polynomial space <i>Q<sub>k</sub></i>
+   * contains.
    */
   PolynomialsRaviartThomas (const unsigned int k);
 
   /**
-   * Computes the value and the
-   * first and second derivatives
-   * of each Raviart-Thomas
-   * polynomial at @p unit_point.
+   * Computes the value and the first and second derivatives of each Raviart-
+   * Thomas polynomial at @p unit_point.
    *
-   * The size of the vectors must
-   * either be zero or equal
-   * <tt>n()</tt>.  In the
-   * first case, the function will
-   * not compute these values.
+   * The size of the vectors must either be zero or equal <tt>n()</tt>.  In
+   * the first case, the function will not compute these values.
    *
-   * If you need values or
-   * derivatives of all tensor
-   * product polynomials then use
-   * this function, rather than
-   * using any of the
-   * <tt>compute_value</tt>,
-   * <tt>compute_grad</tt> or
-   * <tt>compute_grad_grad</tt>
-   * functions, see below, in a
-   * loop over all tensor product
-   * polynomials.
+   * If you need values or derivatives of all tensor product polynomials then
+   * use this function, rather than using any of the <tt>compute_value</tt>,
+   * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+   * in a loop over all tensor product polynomials.
    */
   void compute (const Point<dim>            &unit_point,
                 std::vector<Tensor<1,dim> > &values,
@@ -99,57 +82,43 @@ public:
   unsigned int n () const;
 
   /**
-   * Returns the degree of the Raviart-Thomas
-   * space, which is one less than
+   * Returns the degree of the Raviart-Thomas space, which is one less than
    * the highest polynomial degree.
    */
   unsigned int degree () const;
 
   /**
-   * Return the name of the space,
-   * which is <tt>RaviartThomas</tt>.
+   * Return the name of the space, which is <tt>RaviartThomas</tt>.
    */
   std::string name () const;
 
   /**
-   * Return the number of
-   * polynomials in the space
-   * <TT>RT(degree)</tt> without
-   * requiring to build an object
-   * of PolynomialsRaviartThomas. This is
-   * required by the FiniteElement
-   * classes.
+   * Return the number of polynomials in the space <TT>RT(degree)</tt> without
+   * requiring to build an object of PolynomialsRaviartThomas. This is
+   * required by the FiniteElement classes.
    */
   static unsigned int compute_n_pols(unsigned int degree);
 
 private:
   /**
-   * The degree of this object as
-   * given to the constructor.
+   * The degree of this object as given to the constructor.
    */
   const unsigned int my_degree;
 
   /**
-   * An object representing the
-   * polynomial space for a single
-   * component. We can re-use it by
-   * rotating the coordinates of
-   * the evaluation point.
+   * An object representing the polynomial space for a single component. We
+   * can re-use it by rotating the coordinates of the evaluation point.
    */
   const AnisotropicPolynomials<dim> polynomial_space;
 
   /**
-   * Number of Raviart-Thomas
-   * polynomials.
+   * Number of Raviart-Thomas polynomials.
    */
   const unsigned int n_pols;
 
   /**
-   * A static member function that
-   * creates the polynomial space
-   * we use to initialize the
-   * #polynomial_space member
-   * variable.
+   * A static member function that creates the polynomial space we use to
+   * initialize the #polynomial_space member variable.
    */
   static
   std::vector<std::vector< Polynomials::Polynomial< double > > >
index d8f984b21092d7a008a4346811e670c4f693722d..18d399338cff3cbc8c8b2e18855ca2671c67ffaf 100644 (file)
@@ -26,103 +26,86 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- *  This class is a helper class to facilitate the usage of quadrature formulae
- *  on faces or subfaces of cells. It computes the locations of quadrature
- *  points on the unit cell from a quadrature object for a manifold of
- *  one dimension less than that of the cell and the number of the face.
- *  For example, giving the Simpson rule in one dimension and using the
- *  project_to_face() function with face number 1, the returned points will
- *  be (1,0), (1,0.5) and (1,1). Note that faces have an orientation,
- *  so when projecting to face 3, you will get (0,0), (0,0.5) and (0,1),
- *  which is in clockwise sense, while for face 1 the points were in
- *  counterclockwise sense.
+ * This class is a helper class to facilitate the usage of quadrature formulae
+ * on faces or subfaces of cells. It computes the locations of quadrature
+ * points on the unit cell from a quadrature object for a manifold of one
+ * dimension less than that of the cell and the number of the face. For
+ * example, giving the Simpson rule in one dimension and using the
+ * project_to_face() function with face number 1, the returned points will be
+ * (1,0), (1,0.5) and (1,1). Note that faces have an orientation, so when
+ * projecting to face 3, you will get (0,0), (0,0.5) and (0,1), which is in
+ * clockwise sense, while for face 1 the points were in counterclockwise
+ * sense.
  *
- *  For the projection to subfaces (i.e. to the children of a face of the
- *  unit cell), the same applies as above. Note the order in which the
- *  children of a face are numbered, which in two dimensions coincides
- *  with the orientation of the face.
+ * For the projection to subfaces (i.e. to the children of a face of the unit
+ * cell), the same applies as above. Note the order in which the children of a
+ * face are numbered, which in two dimensions coincides with the orientation
+ * of the face.
  *
- *  The second set of functions generates a quadrature formula by
- *  projecting a given quadrature rule on <b>all</b> faces and
- *  subfaces. This is used in the FEFaceValues and
- *  FESubfaceValues classes. Since we now have the quadrature
- *  points of all faces and subfaces in one array, we need to have a
- *  way to find the starting index of the points and weights
- *  corresponding to one face or subface within this array. This is
- *  done through the DataSetDescriptor member class.
+ * The second set of functions generates a quadrature formula by projecting a
+ * given quadrature rule on <b>all</b> faces and subfaces. This is used in the
+ * FEFaceValues and FESubfaceValues classes. Since we now have the quadrature
+ * points of all faces and subfaces in one array, we need to have a way to
+ * find the starting index of the points and weights corresponding to one face
+ * or subface within this array. This is done through the DataSetDescriptor
+ * member class.
  *
- *  The different functions are grouped into a common class to avoid
- *  putting them into global namespace. However, since they have no
- *  local data, all functions are declared <tt>static</tt> and can be
- *  called without creating an object of this class.
+ * The different functions are grouped into a common class to avoid putting
+ * them into global namespace. However, since they have no local data, all
+ * functions are declared <tt>static</tt> and can be called without creating
+ * an object of this class.
  *
- *  For the 3d case, you should note that the orientation of faces is
- *  even more intricate than for two dimensions. Quadrature formulae
- *  are projected upon the faces in their standard orientation, not to
- *  the inside or outside of the hexahedron. To make things more
- *  complicated, in 3d we allow faces in two orientations (which can
- *  be identified using <tt>cell->face_orientation(face)</tt>), so we
- *  have to project quadrature formula onto faces and subfaces in two
- *  orientations. (Refer to the documentation of the Triangulation
- *  class for a description of the orientation of the different faces,
- *  as well as to
- *  @ref GlossFaceOrientation "the glossary entry on face orientation"
- *  for more information on this.) The
- *  DataSetDescriptor member class is used to identify where each
- *  dataset starts.
+ * For the 3d case, you should note that the orientation of faces is even more
+ * intricate than for two dimensions. Quadrature formulae are projected upon
+ * the faces in their standard orientation, not to the inside or outside of
+ * the hexahedron. To make things more complicated, in 3d we allow faces in
+ * two orientations (which can be identified using
+ * <tt>cell->face_orientation(face)</tt>), so we have to project quadrature
+ * formula onto faces and subfaces in two orientations. (Refer to the
+ * documentation of the Triangulation class for a description of the
+ * orientation of the different faces, as well as to @ref GlossFaceOrientation
+ * "the glossary entry on face orientation" for more information on this.) The
+ * DataSetDescriptor member class is used to identify where each dataset
+ * starts.
  *
- *  @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2003, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2003, 2005
  */
 template <int dim>
 class QProjector
 {
 public:
   /**
-   * Define a typedef for a
-   * quadrature that acts on an
-   * object of one dimension
-   * less. For cells, this would
-   * then be a face quadrature.
+   * Define a typedef for a quadrature that acts on an object of one dimension
+   * less. For cells, this would then be a face quadrature.
    */
   typedef Quadrature<dim-1> SubQuadrature;
 
   /**
-   * Compute the quadrature points
-   * on the cell if the given
-   * quadrature formula is used on
-   * face <tt>face_no</tt>. For further
-   * details, see the general doc
-   * for this class.
+   * Compute the quadrature points on the cell if the given quadrature formula
+   * is used on face <tt>face_no</tt>. For further details, see the general
+   * doc for this class.
    */
   static void project_to_face (const SubQuadrature &quadrature,
                                const unsigned int      face_no,
                                std::vector<Point<dim> > &q_points);
 
   /**
-   * Compute the cell quadrature
-   * formula corresponding to using
-   * <tt>quadrature</tt> on face
-   * <tt>face_no</tt>. For further
-   * details, see the general doc
-   * for this class.
+   * Compute the cell quadrature formula corresponding to using
+   * <tt>quadrature</tt> on face <tt>face_no</tt>. For further details, see
+   * the general doc for this class.
    */
   static Quadrature<dim>
   project_to_face (const SubQuadrature &quadrature,
                    const unsigned int      face_no);
 
   /**
-   * Compute the quadrature points on the
-   * cell if the given quadrature formula is
-   * used on face <tt>face_no</tt>, subface
-   * number <tt>subface_no</tt> corresponding
-   * to RefineCase::Type
-   * <tt>ref_case</tt>. The last argument is
+   * Compute the quadrature points on the cell if the given quadrature formula
+   * is used on face <tt>face_no</tt>, subface number <tt>subface_no</tt>
+   * corresponding to RefineCase::Type <tt>ref_case</tt>. The last argument is
    * only used in 3D.
    *
-   * @note Only the points are
-   * transformed. The quadrature
-   * weights are the same as those
-   * of the original rule.
+   * @note Only the points are transformed. The quadrature weights are the
+   * same as those of the original rule.
    */
   static void project_to_subface (const SubQuadrature       &quadrature,
                                   const unsigned int         face_no,
@@ -131,19 +114,13 @@ public:
                                   const RefinementCase<dim-1> &ref_case=RefinementCase<dim-1>::isotropic_refinement);
 
   /**
-   * Compute the cell quadrature formula
-   * corresponding to using
-   * <tt>quadrature</tt> on subface
-   * <tt>subface_no</tt> of face
-   * <tt>face_no</tt> with
-   * RefinementCase<dim-1>
-   * <tt>ref_case</tt>. The last argument is
-   * only used in 3D.
+   * Compute the cell quadrature formula corresponding to using
+   * <tt>quadrature</tt> on subface <tt>subface_no</tt> of face
+   * <tt>face_no</tt> with RefinementCase<dim-1> <tt>ref_case</tt>. The last
+   * argument is only used in 3D.
    *
-   * @note Only the points are
-   * transformed. The quadrature
-   * weights are the same as those
-   * of the original rule.
+   * @note Only the points are transformed. The quadrature weights are the
+   * same as those of the original rule.
    */
   static Quadrature<dim>
   project_to_subface (const SubQuadrature       &quadrature,
@@ -152,80 +129,48 @@ public:
                       const RefinementCase<dim-1> &ref_case=RefinementCase<dim-1>::isotropic_refinement);
 
   /**
-   * Take a face quadrature formula
-   * and generate a cell quadrature
-   * formula from it where the
-   * quadrature points of the given
-   * argument are projected on all
-   * faces.
+   * Take a face quadrature formula and generate a cell quadrature formula
+   * from it where the quadrature points of the given argument are projected
+   * on all faces.
    *
-   * The weights of the new rule
-   * are replications of the
-   * original weights. Thus, the
-   * sum of the weights is not one,
-   * but the number of faces, which
-   * is the surface of the
-   * reference cell.
+   * The weights of the new rule are replications of the original weights.
+   * Thus, the sum of the weights is not one, but the number of faces, which
+   * is the surface of the reference cell.
    *
-   * This in particular allows us
-   * to extract a subset of points
-   * corresponding to a single face
-   * and use it as a quadrature on
-   * this face, as is done in
+   * This in particular allows us to extract a subset of points corresponding
+   * to a single face and use it as a quadrature on this face, as is done in
    * FEFaceValues.
    *
-   * @note In 3D, this function
-   * produces eight sets of
-   * quadrature points for each
-   * face, in order to cope
-   * possibly different
-   * orientations of the mesh.
+   * @note In 3D, this function produces eight sets of quadrature points for
+   * each face, in order to cope possibly different orientations of the mesh.
    */
   static Quadrature<dim>
   project_to_all_faces (const SubQuadrature &quadrature);
 
   /**
-   * Take a face quadrature formula
-   * and generate a cell quadrature
-   * formula from it where the
-   * quadrature points of the given
-   * argument are projected on all
-   * subfaces.
+   * Take a face quadrature formula and generate a cell quadrature formula
+   * from it where the quadrature points of the given argument are projected
+   * on all subfaces.
    *
-   * Like in project_to_all_faces(),
-   * the weights of the new rule
-   * sum up to the number of faces
-   * (not subfaces), which
-   * is the surface of the
-   * reference cell.
+   * Like in project_to_all_faces(), the weights of the new rule sum up to the
+   * number of faces (not subfaces), which is the surface of the reference
+   * cell.
    *
-   * This in particular allows us
-   * to extract a subset of points
-   * corresponding to a single subface
-   * and use it as a quadrature on
-   * this face, as is done in
-   * FESubfaceValues.
+   * This in particular allows us to extract a subset of points corresponding
+   * to a single subface and use it as a quadrature on this face, as is done
+   * in FESubfaceValues.
    */
   static Quadrature<dim>
   project_to_all_subfaces (const SubQuadrature &quadrature);
 
   /**
-   * Project a given quadrature
-   * formula to a child of a
-   * cell. You may want to use this
-   * function in case you want to
-   * extend an integral only over
-   * the area which a potential
-   * child would occupy. The child
-   * numbering is the same as the
-   * children would be numbered
-   * upon refinement of the cell.
+   * Project a given quadrature formula to a child of a cell. You may want to
+   * use this function in case you want to extend an integral only over the
+   * area which a potential child would occupy. The child numbering is the
+   * same as the children would be numbered upon refinement of the cell.
    *
-   * As integration using this
-   * quadrature formula now only
-   * extends over a fraction of the
-   * cell, the weights of the
-   * resulting object are divided by
+   * As integration using this quadrature formula now only extends over a
+   * fraction of the cell, the weights of the resulting object are divided by
    * GeometryInfo<dim>::children_per_cell.
    */
   static
@@ -234,33 +179,21 @@ public:
                     const unsigned int      child_no);
 
   /**
-   * Project a quadrature rule to
-   * all children of a
-   * cell. Similarly to
-   * project_to_all_subfaces(),
-   * this function replicates the
-   * formula generated by
-   * project_to_child() for all
-   * children, such that the
-   * weights sum up to one, the
-   * volume of the total cell
-   * again.
+   * Project a quadrature rule to all children of a cell. Similarly to
+   * project_to_all_subfaces(), this function replicates the formula generated
+   * by project_to_child() for all children, such that the weights sum up to
+   * one, the volume of the total cell again.
    *
-   * The child
-   * numbering is the same as the
-   * children would be numbered
-   * upon refinement of the cell.
+   * The child numbering is the same as the children would be numbered upon
+   * refinement of the cell.
    */
   static
   Quadrature<dim>
   project_to_all_children (const Quadrature<dim>  &quadrature);
 
   /**
-   * Project the onedimensional
-   * rule <tt>quadrature</tt> to
-   * the straight line connecting
-   * the points <tt>p1</tt> and
-   * <tt>p2</tt>.
+   * Project the onedimensional rule <tt>quadrature</tt> to the straight line
+   * connecting the points <tt>p1</tt> and <tt>p2</tt>.
    */
   static
   Quadrature<dim>
@@ -269,27 +202,14 @@ public:
                   const Point<dim> &p2);
 
   /**
-   * Since the
-   * project_to_all_faces() and
-   * project_to_all_subfaces()
-   * functions chain together the
-   * quadrature points and weights
-   * of all projections of a face
-   * quadrature formula to the
-   * faces or subfaces of a cell,
-   * we need a way to identify
-   * where the starting index of
-   * the points and weights for a
-   * particular face or subface
-   * is. This class provides this:
-   * there are static member
-   * functions that generate
-   * objects of this type, given
-   * face or subface indices, and
-   * you can then use the generated
-   * object in place of an integer
-   * that denotes the offset of a
-   * given dataset.
+   * Since the project_to_all_faces() and project_to_all_subfaces() functions
+   * chain together the quadrature points and weights of all projections of a
+   * face quadrature formula to the faces or subfaces of a cell, we need a way
+   * to identify where the starting index of the points and weights for a
+   * particular face or subface is. This class provides this: there are static
+   * member functions that generate objects of this type, given face or
+   * subface indices, and you can then use the generated object in place of an
+   * integer that denotes the offset of a given dataset.
    *
    * @author Wolfgang Bangerth, 2003
    */
@@ -297,48 +217,29 @@ public:
   {
   public:
     /**
-     * Default constructor. This
-     * doesn't do much except
-     * generating an invalid
-     * index, since you didn't
-     * give a valid descriptor of
-     * the cell, face, or subface
-     * you wanted.
+     * Default constructor. This doesn't do much except generating an invalid
+     * index, since you didn't give a valid descriptor of the cell, face, or
+     * subface you wanted.
      */
     DataSetDescriptor ();
 
     /**
-     * Static function to
-     * generate the offset of a
-     * cell. Since we only have
-     * one cell per quadrature
-     * object, this offset is of
-     * course zero, but we carry
-     * this function around for
-     * consistency with the other
-     * static functions.
+     * Static function to generate the offset of a cell. Since we only have
+     * one cell per quadrature object, this offset is of course zero, but we
+     * carry this function around for consistency with the other static
+     * functions.
      */
     static DataSetDescriptor cell ();
 
     /**
-     * Static function to generate an
-     * offset object for a given face of a
-     * cell with the given face
-     * orientation, flip and rotation. This
-     * function of course is only allowed
-     * if <tt>dim>=2</tt>, and the face
-     * orientation, flip and rotation are
-     * ignored if the space dimension
-     * equals 2.
+     * Static function to generate an offset object for a given face of a cell
+     * with the given face orientation, flip and rotation. This function of
+     * course is only allowed if <tt>dim>=2</tt>, and the face orientation,
+     * flip and rotation are ignored if the space dimension equals 2.
      *
-     * The last argument denotes
-     * the number of quadrature
-     * points the
-     * lower-dimensional face
-     * quadrature formula (the
-     * one that has been
-     * projected onto the faces)
-     * has.
+     * The last argument denotes the number of quadrature points the lower-
+     * dimensional face quadrature formula (the one that has been projected
+     * onto the faces) has.
      */
     static
     DataSetDescriptor
@@ -349,28 +250,16 @@ public:
           const unsigned int n_quadrature_points);
 
     /**
-     * Static function to generate an
-     * offset object for a given subface of
-     * a cell with the given face
-     * orientation, flip and rotation. This
-     * function of course is only allowed
-     * if <tt>dim>=2</tt>, and the face
-     * orientation, flip and rotation are
-     * ignored if the space dimension
-     * equals 2.
+     * Static function to generate an offset object for a given subface of a
+     * cell with the given face orientation, flip and rotation. This function
+     * of course is only allowed if <tt>dim>=2</tt>, and the face orientation,
+     * flip and rotation are ignored if the space dimension equals 2.
      *
-     * The last but one argument denotes
-     * the number of quadrature
-     * points the
-     * lower-dimensional face
-     * quadrature formula (the
-     * one that has been
-     * projected onto the faces)
-     * has.
+     * The last but one argument denotes the number of quadrature points the
+     * lower-dimensional face quadrature formula (the one that has been
+     * projected onto the faces) has.
      *
-     * Through the last argument
-     * anisotropic refinement can be
-     * respected.
+     * Through the last argument anisotropic refinement can be respected.
      */
     static
     DataSetDescriptor
@@ -383,70 +272,44 @@ public:
              const internal::SubfaceCase<dim> ref_case=internal::SubfaceCase<dim>::case_isotropic);
 
     /**
-     * Conversion operator to an
-     * integer denoting the
-     * offset of the first
-     * element of this dataset in
-     * the set of quadrature
-     * formulas all projected
-     * onto faces and
-     * subfaces. This conversion
-     * operator allows us to use
-     * offset descriptor objects
-     * in place of integer
-     * offsets.
+     * Conversion operator to an integer denoting the offset of the first
+     * element of this dataset in the set of quadrature formulas all projected
+     * onto faces and subfaces. This conversion operator allows us to use
+     * offset descriptor objects in place of integer offsets.
      */
     operator unsigned int () const;
 
   private:
     /**
-     * Store the integer offset
-     * for a given cell, face, or
-     * subface.
+     * Store the integer offset for a given cell, face, or subface.
      */
     const unsigned int dataset_offset;
 
     /**
-     * This is the real
-     * constructor, but it is
-     * private and thus only
-     * available to the static
-     * member functions above.
+     * This is the real constructor, but it is private and thus only available
+     * to the static member functions above.
      */
     DataSetDescriptor (const unsigned int dataset_offset);
   };
 
 private:
   /**
-   * Given a quadrature object in
-   * 2d, reflect all quadrature
-   * points at the main diagonal
-   * and return them with their
-   * original weights.
+   * Given a quadrature object in 2d, reflect all quadrature points at the
+   * main diagonal and return them with their original weights.
    *
-   * This function is necessary for
-   * projecting a 2d quadrature
-   * rule onto the faces of a 3d
-   * cube, since there we need both
-   * orientations.
+   * This function is necessary for projecting a 2d quadrature rule onto the
+   * faces of a 3d cube, since there we need both orientations.
    */
   static Quadrature<2> reflect (const Quadrature<2> &q);
 
   /**
-   * Given a quadrature object in
-   * 2d, rotate all quadrature
-   * points by @p n_times * 90 degrees
-   * counterclockwise
-   * and return them with their
-   * original weights.
+   * Given a quadrature object in 2d, rotate all quadrature points by @p
+   * n_times * 90 degrees counterclockwise and return them with their original
+   * weights.
    *
-   * This function is necessary for
-   * projecting a 2d quadrature
-   * rule onto the faces of a 3d
-   * cube, since there we need all
-   * rotations to account for
-   * face_flip and face_rotation
-   * of non-standard faces.
+   * This function is necessary for projecting a 2d quadrature rule onto the
+   * faces of a 3d cube, since there we need all rotations to account for
+   * face_flip and face_rotation of non-standard faces.
    */
   static Quadrature<2> rotate (const Quadrature<2> &q,
                                const unsigned int n_times);
index 16ed2dc27fabe6b81283d8c545bb59280c7c0b2f..52829c729c2157df3873c4c7337c590de8f62a1c 100644 (file)
@@ -29,54 +29,50 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * Base class for quadrature formulæ in arbitrary dimensions. This class
- * stores quadrature points and weights on the unit line [0,1], unit
- * square [0,1]x[0,1], etc.
+ * stores quadrature points and weights on the unit line [0,1], unit square
+ * [0,1]x[0,1], etc.
  *
- * There are a number of derived classes, denoting concrete
- * integration formulæ. Their names names prefixed by
- * <tt>Q</tt>. Refer to the list of derived classes for more details.
+ * There are a number of derived classes, denoting concrete integration
+ * formulæ. Their names names prefixed by <tt>Q</tt>. Refer to the list of
+ * derived classes for more details.
  *
- * The schemes for higher dimensions are typically tensor products of the
- * one-dimensional formulæ, but refer to the section on implementation
- * detail below.
+ * The schemes for higher dimensions are typically tensor products of the one-
+ * dimensional formulæ, but refer to the section on implementation detail
+ * below.
  *
- * In order to allow for dimension independent programming, a
- * quadrature formula of dimension zero exists. Since an integral over
- * zero dimensions is the evaluation at a single point, any
- * constructor of such a formula initializes to a single quadrature
- * point with weight one. Access to the weight is possible, while
- * access to the quadrature point is not permitted, since a Point of
- * dimension zero contains no information. The main purpose of these
- * formulæ is their use in QProjector, which will create a useful
+ * In order to allow for dimension independent programming, a quadrature
+ * formula of dimension zero exists. Since an integral over zero dimensions is
+ * the evaluation at a single point, any constructor of such a formula
+ * initializes to a single quadrature point with weight one. Access to the
+ * weight is possible, while access to the quadrature point is not permitted,
+ * since a Point of dimension zero contains no information. The main purpose
+ * of these formulæ is their use in QProjector, which will create a useful
  * formula of dimension one out of them.
  *
  * <h3>Mathematical background</h3>
  *
- * For each quadrature formula we denote by <tt>m</tt>, the maximal
- * degree of polynomials integrated exactly. This number is given in
- * the documentation of each formula. The order of the integration
- * error is <tt>m+1</tt>, that is, the error is the size of the cell
- * to the <tt>m+1</tt> by the Bramble-Hilbert Lemma. The number
- * <tt>m</tt> is to be found in the documentation of each concrete
- * formula. For the optimal formulæ QGauss we have $m = 2N-1$, where
- * N is the constructor parameter to QGauss. The tensor product
- * formulæ are exact on tensor product polynomials of degree
- * <tt>m</tt> in each space direction, but they are still only of
- * <tt>m+1</tt>st order.
+ * For each quadrature formula we denote by <tt>m</tt>, the maximal degree of
+ * polynomials integrated exactly. This number is given in the documentation
+ * of each formula. The order of the integration error is <tt>m+1</tt>, that
+ * is, the error is the size of the cell to the <tt>m+1</tt> by the Bramble-
+ * Hilbert Lemma. The number <tt>m</tt> is to be found in the documentation of
+ * each concrete formula. For the optimal formulæ QGauss we have $m = 2N-1$,
+ * where N is the constructor parameter to QGauss. The tensor product formulæ
+ * are exact on tensor product polynomials of degree <tt>m</tt> in each space
+ * direction, but they are still only of <tt>m+1</tt>st order.
  *
  * <h3>Implementation details</h3>
  *
- * Most integration formulæ in more than one space dimension are
- * tensor products of quadrature formulæ in one space dimension, or
- * more generally the tensor product of a formula in <tt>(dim-1)</tt>
- * dimensions and one in one dimension. There is a special constructor
- * to generate a quadrature formula from two others.  For example, the
- * QGauss@<dim@> formulæ include <i>N<sup>dim</sup></i> quadrature
- * points in <tt>dim</tt> dimensions, where N is the constructor
- * parameter of QGauss.
+ * Most integration formulæ in more than one space dimension are tensor
+ * products of quadrature formulæ in one space dimension, or more generally
+ * the tensor product of a formula in <tt>(dim-1)</tt> dimensions and one in
+ * one dimension. There is a special constructor to generate a quadrature
+ * formula from two others.  For example, the QGauss@<dim@> formulæ include
+ * <i>N<sup>dim</sup></i> quadrature points in <tt>dim</tt> dimensions, where
+ * N is the constructor parameter of QGauss.
  *
- * @note Instantiations for this template are provided for dimensions
- * 0, 1, 2, and 3 (see the section on @ref Instantiations).
+ * @note Instantiations for this template are provided for dimensions 0, 1, 2,
+ * and 3 (see the section on @ref Instantiations).
  *
  * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2005, 2009
  */
@@ -85,62 +81,41 @@ class Quadrature : public Subscriptor
 {
 public:
   /**
-   * Define a typedef for a
-   * quadrature that acts on an
-   * object of one dimension
-   * less. For cells, this would
-   * then be a face quadrature.
+   * Define a typedef for a quadrature that acts on an object of one dimension
+   * less. For cells, this would then be a face quadrature.
    */
   typedef Quadrature<dim-1> SubQuadrature;
 
   /**
    * Constructor.
    *
-   * This constructor is marked as
-   * explicit to avoid involuntary
-   * accidents like in
-   * <code>hp::QCollection@<dim@>
-   * q_collection(3)</code> where
-   * <code>hp::QCollection@<dim@>
-   * q_collection(QGauss@<dim@>(3))</code>
-   * was meant.
+   * This constructor is marked as explicit to avoid involuntary accidents
+   * like in <code>hp::QCollection@<dim@> q_collection(3)</code> where
+   * <code>hp::QCollection@<dim@> q_collection(QGauss@<dim@>(3))</code> was
+   * meant.
    */
   explicit Quadrature (const unsigned int n_quadrature_points = 0);
 
   /**
-   * Build this quadrature formula
-   * as the tensor product of a
-   * formula in a dimension one
-   * less than the present and a
-   * formula in one dimension.
+   * Build this quadrature formula as the tensor product of a formula in a
+   * dimension one less than the present and a formula in one dimension.
    *
-   * <tt>SubQuadrature<dim>::type</tt>
-   * expands to
-   * <tt>Quadrature<dim-1></tt>.
+   * <tt>SubQuadrature<dim>::type</tt> expands to <tt>Quadrature<dim-1></tt>.
    */
   Quadrature (const SubQuadrature &,
               const Quadrature<1> &);
 
   /**
-   * Build this quadrature formula
-   * as the <tt>dim</tt>-fold
-   * tensor product of a formula in
-   * one dimension.
+   * Build this quadrature formula as the <tt>dim</tt>-fold tensor product of
+   * a formula in one dimension.
    *
-   * Assuming that the points in
-   * the one-dimensional rule are in
-   * ascending order, the points of
-   * the resulting rule are ordered
-   * lexicographically with
-   * <i>x</i> running fastest.
+   * Assuming that the points in the one-dimensional rule are in ascending
+   * order, the points of the resulting rule are ordered lexicographically
+   * with <i>x</i> running fastest.
    *
-   * In order to avoid a conflict
-   * with the copy constructor in
-   * 1d, we let the argument be a
-   * 0d quadrature formula for
-   * dim==1, and a 1d quadrature
-   * formula for all other space
-   * dimensions.
+   * In order to avoid a conflict with the copy constructor in 1d, we let the
+   * argument be a 0d quadrature formula for dim==1, and a 1d quadrature
+   * formula for all other space dimensions.
    */
   explicit Quadrature (const Quadrature<dim != 1 ? 1 : 0> &quadrature_1d);
 
@@ -150,39 +125,25 @@ public:
   Quadrature (const Quadrature<dim> &q);
 
   /**
-   * Construct a quadrature formula
-   * from given vectors of
-   * quadrature points (which
-   * should really be in the unit
-   * cell) and the corresponding
-   * weights. You will want to have
-   * the weights sum up to one, but
-   * this is not checked.
+   * Construct a quadrature formula from given vectors of quadrature points
+   * (which should really be in the unit cell) and the corresponding weights.
+   * You will want to have the weights sum up to one, but this is not checked.
    */
   Quadrature (const std::vector<Point<dim> > &points,
               const std::vector<double>      &weights);
 
   /**
-   * Construct a dummy quadrature
-   * formula from a list of points,
-   * with weights set to
-   * infinity. The resulting object
-   * is therefore not meant to
-   * actually perform integrations,
-   * but rather to be used with
-   * FEValues objects in
-   * order to find the position of
-   * some points (the quadrature
-   * points in this object) on the
-   * transformed cell in real
-   * space.
+   * Construct a dummy quadrature formula from a list of points, with weights
+   * set to infinity. The resulting object is therefore not meant to actually
+   * perform integrations, but rather to be used with FEValues objects in
+   * order to find the position of some points (the quadrature points in this
+   * object) on the transformed cell in real space.
    */
   Quadrature (const std::vector<Point<dim> > &points);
 
   /**
-   * Constructor for a one-point
-   * quadrature. Sets the weight of
-   * this point to one.
+   * Constructor for a one-point quadrature. Sets the weight of this point to
+   * one.
    */
   Quadrature (const Point<dim> &point);
 
@@ -192,22 +153,19 @@ public:
   virtual ~Quadrature ();
 
   /**
-   * Assignment operator. Copies
-   * contents of #weights and
-   * #quadrature_points as well as
-   * size.
+   * Assignment operator. Copies contents of #weights and #quadrature_points
+   * as well as size.
    */
   Quadrature &operator = (const Quadrature<dim> &);
 
   /**
-                   *  Test for equality of two quadratures.
-                   */
+   * Test for equality of two quadratures.
+   */
   bool operator == (const Quadrature<dim> &p) const;
 
   /**
-   * Set the quadrature points and
-   * weights to the values provided
-   * in the arguments.
+   * Set the quadrature points and weights to the values provided in the
+   * arguments.
    */
   void initialize(const std::vector<Point<dim> > &points,
                   const std::vector<double>      &weights);
@@ -218,71 +176,60 @@ public:
   unsigned int size () const;
 
   /**
-   * Return the <tt>i</tt>th quadrature
-   * point.
+   * Return the <tt>i</tt>th quadrature point.
    */
   const Point<dim> &point (const unsigned int i) const;
 
   /**
-   * Return a reference to the
-   * whole array of quadrature
-   * points.
+   * Return a reference to the whole array of quadrature points.
    */
   const std::vector<Point<dim> > &get_points () const;
 
   /**
-   * Return the weight of the <tt>i</tt>th
-   * quadrature point.
+   * Return the weight of the <tt>i</tt>th quadrature point.
    */
   double weight (const unsigned int i) const;
 
   /**
-   * Return a reference to the whole array
-   * of weights.
+   * Return a reference to the whole array of weights.
    */
   const std::vector<double> &get_weights () const;
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
+   * Determine an estimate for the memory consumption (in bytes) of this
    * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-  * Write or read the data of this object to or
-  * from a stream for the purpose of serialization.
-  */
+   * Write or read the data of this object to or from a stream for the purpose
+   * of serialization.
+   */
   template <class Archive>
   void serialize (Archive &ar, const unsigned int version);
 
 protected:
   /**
-   * List of quadrature points. To
-   * be filled by the constructors
-   * of derived classes.
+   * List of quadrature points. To be filled by the constructors of derived
+   * classes.
    */
   std::vector<Point<dim> > quadrature_points;
 
   /**
-   * List of weights of the
-   * quadrature points.  To be
-   * filled by the constructors of
-   * derived classes.
+   * List of weights of the quadrature points.  To be filled by the
+   * constructors of derived classes.
    */
   std::vector<double>      weights;
 };
 
 
 /**
- * Quadrature formula implementing anisotropic distributions of
- * quadrature points on the reference cell. To this end, the tensor
- * product of <tt>dim</tt> one-dimensional quadrature formulas is
- * generated.
+ * Quadrature formula implementing anisotropic distributions of quadrature
+ * points on the reference cell. To this end, the tensor product of
+ * <tt>dim</tt> one-dimensional quadrature formulas is generated.
  *
- * @note Each constructor can only be used in the dimension matching
- * the number of arguments.
+ * @note Each constructor can only be used in the dimension matching the
+ * number of arguments.
  *
  * @author Guido Kanschat, 2005
  */
@@ -291,23 +238,19 @@ class QAnisotropic : public Quadrature<dim>
 {
 public:
   /**
-   * Constructor for a
-   * one-dimensional formula. This
-   * one just copies the given
+   * Constructor for a one-dimensional formula. This one just copies the given
    * quadrature rule.
    */
   QAnisotropic(const Quadrature<1> &qx);
 
   /**
-   * Constructor for a
-   * two-dimensional formula.
+   * Constructor for a two-dimensional formula.
    */
   QAnisotropic(const Quadrature<1> &qx,
                const Quadrature<1> &qy);
 
   /**
-   * Constructor for a
-   * three-dimensional formula.
+   * Constructor for a three-dimensional formula.
    */
   QAnisotropic(const Quadrature<1> &qx,
                const Quadrature<1> &qy,
@@ -316,27 +259,27 @@ public:
 
 
 /**
- * Quadrature formula constructed by iteration of another quadrature formula in
- * each direction. In more than one space dimension, the resulting quadrature
- * formula is constructed in the usual way by building the tensor product of
- * the respective iterated quadrature formula in one space dimension.
+ * Quadrature formula constructed by iteration of another quadrature formula
+ * in each direction. In more than one space dimension, the resulting
+ * quadrature formula is constructed in the usual way by building the tensor
+ * product of the respective iterated quadrature formula in one space
+ * dimension.
  *
- * In one space dimension, the given base formula is copied and scaled onto
- * a given number of subintervals of length <tt>1/n_copies</tt>. If the quadrature
- * formula uses both end points of the unit interval, then in the interior
- * of the iterated quadrature formula there would be quadrature points which
- * are used twice; we merge them into one with a weight which is the sum
- * of the weights of the left- and the rightmost quadrature point.
+ * In one space dimension, the given base formula is copied and scaled onto a
+ * given number of subintervals of length <tt>1/n_copies</tt>. If the
+ * quadrature formula uses both end points of the unit interval, then in the
+ * interior of the iterated quadrature formula there would be quadrature
+ * points which are used twice; we merge them into one with a weight which is
+ * the sum of the weights of the left- and the rightmost quadrature point.
  *
- * Since all dimensions higher than one are built up by tensor products of
- * one dimensional and <tt>dim-1</tt> dimensional quadrature formulæ, the
- * argument given to the constructor needs to be a quadrature formula in
- * one space dimension, rather than in <tt>dim</tt> dimensions.
+ * Since all dimensions higher than one are built up by tensor products of one
+ * dimensional and <tt>dim-1</tt> dimensional quadrature formulæ, the
+ * argument given to the constructor needs to be a quadrature formula in one
+ * space dimension, rather than in <tt>dim</tt> dimensions.
  *
- * The aim of this class is to provide a
- * low order formula, where the error constant can be tuned by
- * increasing the number of quadrature points. This is useful in
- * integrating non-differentiable functions on cells.
+ * The aim of this class is to provide a low order formula, where the error
+ * constant can be tuned by increasing the number of quadrature points. This
+ * is useful in integrating non-differentiable functions on cells.
  *
  * @author Wolfgang Bangerth 1999
  */
@@ -345,9 +288,8 @@ class QIterated : public Quadrature<dim>
 {
 public:
   /**
-   * Constructor. Iterate the given
-   * quadrature formula <tt>n_copies</tt> times in
-   * each direction.
+   * Constructor. Iterate the given quadrature formula <tt>n_copies</tt> times
+   * in each direction.
    */
   QIterated (const Quadrature<1> &base_quadrature,
              const unsigned int   n_copies);
@@ -358,10 +300,8 @@ public:
   DeclException0 (ExcInvalidQuadratureFormula);
 private:
   /**
-   * Check whether the given
-   * quadrature formula has quadrature
-   * points at the left and right end points
-   * of the interval.
+   * Check whether the given quadrature formula has quadrature points at the
+   * left and right end points of the interval.
    */
   static bool
   uses_both_endpoints (const Quadrature<1> &base_quadrature);
index 11e2aa82a865c2fc0a88777705ace37a04ea071f..b484edb34cac26118478decc5c9ea045b460b753 100644 (file)
@@ -26,8 +26,7 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * The Gauss-Legendre family of quadrature rules for numerical
- * integration.
+ * The Gauss-Legendre family of quadrature rules for numerical integration.
  *
  * The coefficients of these quadrature rules are computed by the function
  * described in <a
@@ -41,40 +40,34 @@ class QGauss : public Quadrature<dim>
 {
 public:
   /**
-   * Generate a formula with
-   * <tt>n</tt> quadrature points (in
-   * each space direction), exact for
-   * polynomials of degree
-   * <tt>2n-1</tt>.
+   * Generate a formula with <tt>n</tt> quadrature points (in each space
+   * direction), exact for polynomials of degree <tt>2n-1</tt>.
    */
   QGauss (const unsigned int n);
 };
 
 
 /**
- * The Gauss-Lobatto family of quadrature rules for numerical
- * integration.
+ * The Gauss-Lobatto family of quadrature rules for numerical integration.
  *
- * This modification of the Gauss quadrature uses the two interval end
- * points as well. Being exact for polynomials of degree <i>2n-3</i>,
- * this formula is suboptimal by two degrees.
+ * This modification of the Gauss quadrature uses the two interval end points
+ * as well. Being exact for polynomials of degree <i>2n-3</i>, this formula is
+ * suboptimal by two degrees.
  *
- * The quadrature points are interval end points plus the roots of
- * the derivative of the Legendre polynomial <i>P<sub>n-1</sub></i> of
- * degree <i>n-1</i>. The quadrature weights are
+ * The quadrature points are interval end points plus the roots of the
+ * derivative of the Legendre polynomial <i>P<sub>n-1</sub></i> of degree
+ * <i>n-1</i>. The quadrature weights are
  * <i>2/(n(n-1)(P<sub>n-1</sub>(x<sub>i</sub>)<sup>2</sup>)</i>.
  *
- * @note This implementation has not been optimized concerning
- *   numerical stability and efficiency. It can be easily adapted
- *   to the general case of Gauss-Lobatto-Jacobi-Bouzitat quadrature
- *   with arbitrary parameters $\alpha$, $\beta$, of which
- *   the Gauss-Lobatto-Legendre quadrature ($\alpha = \beta = 0$)
- *   is a special case.
+ * @note This implementation has not been optimized concerning numerical
+ * stability and efficiency. It can be easily adapted to the general case of
+ * Gauss-Lobatto-Jacobi-Bouzitat quadrature with arbitrary parameters
+ * $\alpha$, $\beta$, of which the Gauss-Lobatto-Legendre quadrature ($\alpha
+ * = \beta = 0$) is a special case.
  *
- * @sa http://en.wikipedia.org/wiki/Handbook_of_Mathematical_Functions
- * @sa Karniadakis, G.E. and Sherwin, S.J.:
- *     Spectral/hp element methods for computational fluid dynamics.
- *     Oxford: Oxford University Press, 2005
+ * @sa http://en.wikipedia.org/wiki/Handbook_of_Mathematical_Functions @sa
+ * Karniadakis, G.E. and Sherwin, S.J.: Spectral/hp element methods for
+ * computational fluid dynamics. Oxford: Oxford University Press, 2005
  *
  * @author Guido Kanschat, 2005, 2006; F. Prill, 2006
  */
@@ -83,22 +76,16 @@ class QGaussLobatto : public Quadrature<dim>
 {
 public:
   /**
-   * Generate a formula with
-   * <tt>n</tt> quadrature points
-   * (in each space direction).
+   * Generate a formula with <tt>n</tt> quadrature points (in each space
+   * direction).
    */
   QGaussLobatto(const unsigned int n);
 
 protected:
   /**
-   * Compute Legendre-Gauss-Lobatto
-   * quadrature points in the
-   * interval $[-1, +1]$. They are
-   * equal to the roots of the
-   * corresponding Jacobi
-   * polynomial (specified by @p
-   * alpha, @p beta).  @p q is the
-   * number of points.
+   * Compute Legendre-Gauss-Lobatto quadrature points in the interval $[-1,
+   * +1]$. They are equal to the roots of the corresponding Jacobi polynomial
+   * (specified by @p alpha, @p beta).  @p q is the number of points.
    *
    * @return Vector containing nodes.
    */
@@ -108,12 +95,9 @@ protected:
                              const int beta) const;
 
   /**
-   * Compute Legendre-Gauss-Lobatto quadrature
-   * weights.
-   * The quadrature points and weights are
-   * related to Jacobi polynomial specified
-   * by @p alpha, @p beta.
-   * @p x denotes the quadrature points.
+   * Compute Legendre-Gauss-Lobatto quadrature weights. The quadrature points
+   * and weights are related to Jacobi polynomial specified by @p alpha, @p
+   * beta. @p x denotes the quadrature points.
    *
    * @return Vector containing weights.
    */
@@ -123,14 +107,10 @@ protected:
                               const int beta) const;
 
   /**
-   * Evaluate a Jacobi polynomial
-   * $ P^{\alpha, \beta}_n(x) $
-   * specified by the parameters
-   * @p alpha, @p beta, @p n.
-   * Note: The Jacobi polynomials are
-   * not orthonormal and defined on
-   * the interval $[-1, +1]$.
-   * @p x is the point of evaluation.
+   * Evaluate a Jacobi polynomial $ P^{\alpha, \beta}_n(x) $ specified by the
+   * parameters @p alpha, @p beta, @p n. Note: The Jacobi polynomials are not
+   * orthonormal and defined on the interval $[-1, +1]$. @p x is the point of
+   * evaluation.
    */
   long double JacobiP(const long double x,
                       const int alpha,
@@ -138,8 +118,7 @@ protected:
                       const unsigned int n) const;
 
   /**
-   * Evaluate the Gamma function
-   * $ \Gamma(n) = (n-1)! $.
+   * Evaluate the Gamma function $ \Gamma(n) = (n-1)! $.
    * @param n  point of evaluation (integer).
    */
   long double gamma(const unsigned int n) const;
@@ -194,8 +173,8 @@ public:
 
 
 /**
- * The Milne rule for numerical quadrature formula. The Milne rule is a
- * closed Newton-Cotes formula and is exact for polynomials of degree 5.
+ * The Milne rule for numerical quadrature formula. The Milne rule is a closed
+ * Newton-Cotes formula and is exact for polynomials of degree 5.
  *
  * @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
  */
@@ -208,8 +187,8 @@ public:
 
 
 /**
- * The Weddle rule for numerical quadrature. The Weddle rule is a
- * closed Newton-Cotes formula and is exact for polynomials of degree 7.
+ * The Weddle rule for numerical quadrature. The Weddle rule is a closed
+ * Newton-Cotes formula and is exact for polynomials of degree 7.
  *
  * @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
  */
@@ -223,17 +202,15 @@ public:
 
 
 /**
- * A class for Gauss quadrature with
- * logarithmic weighting function. This
- * formula is used to integrate $\ln|x|\;f(x)$ on the interval
- * $[0,1]$, where $f$ is a smooth function without
- * singularities. The collection of quadrature points and weights has
- * been obtained using <tt>Numerical Recipes</tt>.
+ * A class for Gauss quadrature with logarithmic weighting function. This
+ * formula is used to integrate $\ln|x|\;f(x)$ on the interval $[0,1]$, where
+ * $f$ is a smooth function without singularities. The collection of
+ * quadrature points and weights has been obtained using <tt>Numerical
+ * Recipes</tt>.
  *
- * Notice that only the function $f(x)$ should be provided,
- * i.e., $\int_0^1 f(x) \ln|x| dx = \sum_{i=0}^N w_i f(q_i)$. Setting
- * the @p revert flag to true at construction time switches the weight
- * from $\ln|x|$ to $\ln|1-x|$.
+ * Notice that only the function $f(x)$ should be provided, i.e., $\int_0^1
+ * f(x) \ln|x| dx = \sum_{i=0}^N w_i f(q_i)$. Setting the @p revert flag to
+ * true at construction time switches the weight from $\ln|x|$ to $\ln|1-x|$.
  *
  * The weights and functions have been tabulated up to order 12.
  */
@@ -242,23 +219,20 @@ class QGaussLog : public Quadrature<dim>
 {
 public:
   /**
-   * Generate a formula with
-   * <tt>n</tt> quadrature points
+   * Generate a formula with <tt>n</tt> quadrature points
    */
   QGaussLog(const unsigned int n,
             const bool revert=false);
 
 protected:
   /**
-   * Sets the points of the
-   * quadrature formula.
+   * Sets the points of the quadrature formula.
    */
   std::vector<double>
   set_quadrature_points(const unsigned int n) const;
 
   /**
-   * Sets the weights of the
-   * quadrature formula.
+   * Sets the weights of the quadrature formula.
    */
   std::vector<double>
   set_quadrature_weights(const unsigned int n) const;
@@ -269,44 +243,38 @@ protected:
 
 
 /**
- * A class for Gauss quadrature with arbitrary logarithmic weighting
- * function. This formula is used to to integrate
- * $\ln(|x-x_0|/\alpha)\;f(x)$ on the interval $[0,1]$,
- * where $f$ is a smooth function without singularities, and $x_0$ and
- * $\alpha$ are given at construction time, and are the location of the
- * singularity $x_0$ and an arbitrary scaling factor in the
- * singularity.
+ * A class for Gauss quadrature with arbitrary logarithmic weighting function.
+ * This formula is used to to integrate $\ln(|x-x_0|/\alpha)\;f(x)$ on the
+ * interval $[0,1]$, where $f$ is a smooth function without singularities, and
+ * $x_0$ and $\alpha$ are given at construction time, and are the location of
+ * the singularity $x_0$ and an arbitrary scaling factor in the singularity.
  *
  * You have to make sure that the point $x_0$ is not one of the Gauss
- * quadrature points of order $N$, otherwise an exception is thrown,
- * since the quadrature weights cannot be computed correctly.
+ * quadrature points of order $N$, otherwise an exception is thrown, since the
+ * quadrature weights cannot be computed correctly.
  *
- * This quadrature formula is rather expensive, since it uses
- * internally two Gauss quadrature formulas of order n to integrate
- * the nonsingular part of the factor, and two GaussLog quadrature
- * formulas to integrate on the separate segments $[0,x_0]$ and
- * $[x_0,1]$. If the singularity is one of the extremes and the factor
- * alpha is 1, then this quadrature is the same as QGaussLog.
+ * This quadrature formula is rather expensive, since it uses internally two
+ * Gauss quadrature formulas of order n to integrate the nonsingular part of
+ * the factor, and two GaussLog quadrature formulas to integrate on the
+ * separate segments $[0,x_0]$ and $[x_0,1]$. If the singularity is one of the
+ * extremes and the factor alpha is 1, then this quadrature is the same as
+ * QGaussLog.
  *
- * The last argument from the constructor allows you to use this
- * quadrature rule in one of two possible ways:
- * \f[
- * \int_0^1 g(x) dx =
- * \int_0^1 f(x) \ln\left(\frac{|x-x_0|}{\alpha}\right) dx
- * = \sum_{i=0}^N w_i g(q_i) = \sum_{i=0}^N \bar{w}_i f(q_i)
- * \f]
+ * The last argument from the constructor allows you to use this quadrature
+ * rule in one of two possible ways: \f[ \int_0^1 g(x) dx = \int_0^1 f(x)
+ * \ln\left(\frac{|x-x_0|}{\alpha}\right) dx = \sum_{i=0}^N w_i g(q_i) =
+ * \sum_{i=0}^N \bar{w}_i f(q_i) \f]
  *
- * Which one of the two sets of weights is provided, can be selected
- * by the @p factor_out_singular_weight parameter. If it is false (the
- * default), then the $\bar{w}_i$ weigths are computed, and you should
- * provide only the smooth function $f(x)$, since the singularity is
- * included inside the quadrature. If the parameter is set to true,
- * then the singularity is factored out of the quadrature formula, and
- * you should provide a function $g(x)$, which should at least be
- * similar to $\ln(|x-x_0|/\alpha)$.
+ * Which one of the two sets of weights is provided, can be selected by the @p
+ * factor_out_singular_weight parameter. If it is false (the default), then
+ * the $\bar{w}_i$ weigths are computed, and you should provide only the
+ * smooth function $f(x)$, since the singularity is included inside the
+ * quadrature. If the parameter is set to true, then the singularity is
+ * factored out of the quadrature formula, and you should provide a function
+ * $g(x)$, which should at least be similar to $\ln(|x-x_0|/\alpha)$.
  *
- * Notice that this quadrature rule is worthless if you try to use it
- * for regular functions once you factored out the singularity.
+ * Notice that this quadrature rule is worthless if you try to use it for
+ * regular functions once you factored out the singularity.
  *
  * The weights and functions have been tabulated up to order 12.
  */
@@ -315,16 +283,11 @@ class QGaussLogR : public Quadrature<dim>
 {
 public:
   /**
-   * The constructor takes four arguments:
-   * the order of the gauss formula on each
-   * of the segments $[0,x_0]$ and
-   * $[x_0,1]$, the actual location of the
-   * singularity, the scale factor inside
-   * the logarithmic function and a flag
-   * that decides whether the singularity is
-   * left inside the quadrature formula or
-   * it is factored out, to be included in
-   * the integrand.
+   * The constructor takes four arguments: the order of the gauss formula on
+   * each of the segments $[0,x_0]$ and $[x_0,1]$, the actual location of the
+   * singularity, the scale factor inside the logarithmic function and a flag
+   * that decides whether the singularity is left inside the quadrature
+   * formula or it is factored out, to be included in the integrand.
    */
   QGaussLogR(const unsigned int n,
              const Point<dim> x0 = Point<dim>(),
@@ -333,8 +296,7 @@ public:
 
 protected:
   /**
-   * This is the length of interval
-   * $(0,origin)$, or 1 if either of the two
+   * This is the length of interval $(0,origin)$, or 1 if either of the two
    * extremes have been selected.
    */
   const double fraction;
@@ -343,48 +305,45 @@ protected:
 
 /**
  * A class for Gauss quadrature with $1/R$ weighting function. This formula
- * can be used to to integrate $1/R \ f(x)$ on the reference
- * element $[0,1]^2$, where $f$ is a smooth function without
- * singularities, and $R$ is the distance from the point $x$ to the vertex
- * $\xi$, given at construction time by specifying its index. Notice that
- * this distance is evaluated in the reference element.
+ * can be used to to integrate $1/R \ f(x)$ on the reference element
+ * $[0,1]^2$, where $f$ is a smooth function without singularities, and $R$ is
+ * the distance from the point $x$ to the vertex $\xi$, given at construction
+ * time by specifying its index. Notice that this distance is evaluated in the
+ * reference element.
  *
- * This quadrature formula is obtained from two QGauss quadrature
- * formulas, upon transforming them into polar coordinate system
- * centered at the singularity, and then again into another reference
- * element. This allows for the singularity to be cancelled by part of
- * the Jacobian of the transformation, which contains $R$. In practice
- * the reference element is transformed into a triangle by collapsing
- * one of the sides adjacent to the singularity. The Jacobian of this
- * transformation contains $R$, which is removed before scaling the
- * original quadrature, and this process is repeated for the next half
- * element.
+ * This quadrature formula is obtained from two QGauss quadrature formulas,
+ * upon transforming them into polar coordinate system centered at the
+ * singularity, and then again into another reference element. This allows for
+ * the singularity to be cancelled by part of the Jacobian of the
+ * transformation, which contains $R$. In practice the reference element is
+ * transformed into a triangle by collapsing one of the sides adjacent to the
+ * singularity. The Jacobian of this transformation contains $R$, which is
+ * removed before scaling the original quadrature, and this process is
+ * repeated for the next half element.
  *
- * Upon construction it is possible to specify whether we want the
- * singularity removed, or not. In other words, this quadrature can be
- * used to integrate $g(x) = 1/R\ f(x)$, or simply $f(x)$, with the $1/R$
- * factor already included in the quadrature weights.
+ * Upon construction it is possible to specify whether we want the singularity
+ * removed, or not. In other words, this quadrature can be used to integrate
+ * $g(x) = 1/R\ f(x)$, or simply $f(x)$, with the $1/R$ factor already
+ * included in the quadrature weights.
  */
 template <int dim>
 class QGaussOneOverR : public Quadrature<dim>
 {
 public:
   /**
-   * This constructor takes three arguments: the order of the Gauss
-   * formula, the point of the reference element in which the
-   * singularity is located, and whether we include the weighting
-   * singular function inside the quadrature, or we leave it in the
-   * user function to be integrated.
+   * This constructor takes three arguments: the order of the Gauss formula,
+   * the point of the reference element in which the singularity is located,
+   * and whether we include the weighting singular function inside the
+   * quadrature, or we leave it in the user function to be integrated.
    *
-   * Traditionally, quadrature formulas include their weighting
-   * function, and the last argument is set to false by
-   * default. There are cases, however, where this is undesirable
-   * (for example when you only know that your singularity has the
-   * same order of 1/R, but cannot be written exactly in this
-   * way).
+   * Traditionally, quadrature formulas include their weighting function, and
+   * the last argument is set to false by default. There are cases, however,
+   * where this is undesirable (for example when you only know that your
+   * singularity has the same order of 1/R, but cannot be written exactly in
+   * this way).
    *
-   * In other words, you can use this function in either of
-   * the following way, obtaining the same result:
+   * In other words, you can use this function in either of the following way,
+   * obtaining the same result:
    *
    * @code
    * QGaussOneOverR singular_quad(order, q_point, false);
@@ -407,23 +366,21 @@ public:
                  const Point<dim> singularity,
                  const bool factor_out_singular_weight=false);
   /**
-   * The constructor takes three arguments: the order of the Gauss
-   * formula, the index of the vertex where the singularity is
-   * located, and whether we include the weighting singular function
-   * inside the quadrature, or we leave it in the user function to
-   * be integrated. Notice that this is a specialized version of the
-   * previous constructor which works only for the vertices of the
-   * quadrilateral.
+   * The constructor takes three arguments: the order of the Gauss formula,
+   * the index of the vertex where the singularity is located, and whether we
+   * include the weighting singular function inside the quadrature, or we
+   * leave it in the user function to be integrated. Notice that this is a
+   * specialized version of the previous constructor which works only for the
+   * vertices of the quadrilateral.
    *
-   * Traditionally, quadrature formulas include their weighting
-   * function, and the last argument is set to false by
-   * default. There are cases, however, where this is undesirable
-   * (for example when you only know that your singularity has the
-   * same order of 1/R, but cannot be written exactly in this
-   * way).
+   * Traditionally, quadrature formulas include their weighting function, and
+   * the last argument is set to false by default. There are cases, however,
+   * where this is undesirable (for example when you only know that your
+   * singularity has the same order of 1/R, but cannot be written exactly in
+   * this way).
    *
-   * In other words, you can use this function in either of
-   * the following way, obtaining the same result:
+   * In other words, you can use this function in either of the following way,
+   * obtaining the same result:
    *
    * @code
    * QGaussOneOverR singular_quad(order, vertex_id, false);
@@ -447,10 +404,9 @@ public:
                  const bool factor_out_singular_weight=false);
 private:
   /**
-   * Given a quadrature point and a degree n, this function returns
-   * the size of the singular quadrature rule, considering whether
-   * the point is inside the cell, on an edge of the cell, or on a
-   * corner of the cell.
+   * Given a quadrature point and a degree n, this function returns the size
+   * of the singular quadrature rule, considering whether the point is inside
+   * the cell, on an edge of the cell, or on a corner of the cell.
    */
   static unsigned int quad_size(const Point<dim> singularity,
                                 const unsigned int n);
@@ -459,14 +415,13 @@ private:
 
 
 /**
- * Sorted Quadrature. Given an arbitrary quadrature formula, this
- * class generates a quadrature formula where the quadrature points
- * are ordered according the weights, from those with smaller
- * corresponding weight, to those with higher corresponding weights.
- * This might be necessary, for example, when integrating high order
- * polynomials, since in these cases you might sum very big numbers
- * with very small numbers, and summation is not stable if the numbers
- * to sum are not close to each other.
+ * Sorted Quadrature. Given an arbitrary quadrature formula, this class
+ * generates a quadrature formula where the quadrature points are ordered
+ * according the weights, from those with smaller corresponding weight, to
+ * those with higher corresponding weights. This might be necessary, for
+ * example, when integrating high order polynomials, since in these cases you
+ * might sum very big numbers with very small numbers, and summation is not
+ * stable if the numbers to sum are not close to each other.
  */
 template <int dim>
 class QSorted : public Quadrature<dim>
index 1db8371ab609466f1480c9eae1b03397eceff452..79aa6c0caea370c95d18c44e66bff1b6bc7341ee 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class implements the quadrature rule passed to its constructor
- * as a string. Supported quadratures are QGauss (of all
- * orders), QMidpoint, QMilne, QSimpson,
- * QTrapez and QWeddle.
+ * This class implements the quadrature rule passed to its constructor as a
+ * string. Supported quadratures are QGauss (of all orders), QMidpoint,
+ * QMilne, QSimpson, QTrapez and QWeddle.
  *
- * This class is useful if you want to use flexible quadrature rules,
- * that are read from a parameter file (see ParameterHandler for
- * this).
+ * This class is useful if you want to use flexible quadrature rules, that are
+ * read from a parameter file (see ParameterHandler for this).
  *
  * @ingroup Quadrature
  * @author Ralf Schulz, 2003
@@ -43,29 +41,24 @@ class QuadratureSelector : public Quadrature<dim>
 {
 public:
   /**
-   * Constructor. Takes the name of
-   * the quadrature rule (one of
-   * "gauss", "milne", "weddle",
-   * etc) and, if it iss "gauss",
-   * the order of the quadrature
-   * rule as argument.
+   * Constructor. Takes the name of the quadrature rule (one of "gauss",
+   * "milne", "weddle", etc) and, if it iss "gauss", the order of the
+   * quadrature rule as argument.
    */
   QuadratureSelector (const std::string &s,
                       const unsigned int order=0);
 
   /**
-   * This function returns all
-   * possible names for quadratures
-   * as a list separated by <tt>|</tt>,
-   * so that you can use it for the
-   * definition of parameter files
-   * (see ParameterHandler for
-   * details).
+   * This function returns all possible names for quadratures as a list
+   * separated by <tt>|</tt>, so that you can use it for the definition of
+   * parameter files (see ParameterHandler for details).
    */
   static std::string get_quadrature_names();
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
 
   /**
@@ -94,12 +87,9 @@ public:
   //@}
 private:
   /**
-   * This static function creates a
-   * quadrature object according to
-   * the name given as a string,
-   * and the appropriate order (if
-   * the name is "gauss"). It is
-   * called from the constructor.
+   * This static function creates a quadrature object according to the name
+   * given as a string, and the appropriate order (if the name is "gauss"). It
+   * is called from the constructor.
    */
   static
   Quadrature<dim>
index 7619993fcd956569ccf5e1cb9f78abcf5243a685..924d1e93b424dd747f96fe0c9a1d287d160d8190 100644 (file)
@@ -24,20 +24,20 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * Smart pointers avoid destruction of an object in use. They can be used just
- * like a pointer (i.e. using the <tt>*</tt> and <tt>-></tt> operators and through casting)
- * but make sure that the object pointed to is not deleted in the course of
- * use of the pointer by signalling the pointee its use.
+ * like a pointer (i.e. using the <tt>*</tt> and <tt>-></tt> operators and
+ * through casting) but make sure that the object pointed to is not deleted in
+ * the course of use of the pointer by signalling the pointee its use.
  *
- * Objects pointed to, i.e. the class T, should inherit
- * Subscriptor or must implement the same functionality. Null pointers
- * are an exception from this rule and are allowed, too.
+ * Objects pointed to, i.e. the class T, should inherit Subscriptor or must
+ * implement the same functionality. Null pointers are an exception from this
+ * rule and are allowed, too.
  *
  * The second template argument P only serves a single purpose: if a
- * constructor without a debug string is used, then the name of P is
- * used as the debug string.
+ * constructor without a debug string is used, then the name of P is used as
+ * the debug string.
  *
- * SmartPointer does NOT implement any memory handling! Especially,
- * deleting a SmartPointer does not delete the object. Writing
+ * SmartPointer does NOT implement any memory handling! Especially, deleting a
+ * SmartPointer does not delete the object. Writing
  * @code
  * SmartPointer<T,P> dont_do_this = new T;
  * @endcode
@@ -52,8 +52,8 @@ DEAL_II_NAMESPACE_OPEN
  * @endcode
  *
  * Note that a smart pointer can handle <tt>const</tt>ness of an object, i.e.
- * a <tt>SmartPointer<const ABC></tt> really behaves as if it were a pointer to
- * a constant object (disallowing write access when dereferenced), while
+ * a <tt>SmartPointer<const ABC></tt> really behaves as if it were a pointer
+ * to a constant object (disallowing write access when dereferenced), while
  * <tt>SmartPointer<ABC></tt> is a mutable pointer.
  *
  * @ingroup memory
@@ -64,105 +64,71 @@ class SmartPointer
 {
 public:
   /**
-   * Standard constructor for null
-   * pointer. The id of this
-   * pointer is set to the name of
-   * the class P.
+   * Standard constructor for null pointer. The id of this pointer is set to
+   * the name of the class P.
    */
   SmartPointer ();
 
   /**
-   * Copy constructor for
-   * SmartPointer. We do now
-   * copy the object subscribed to
-   * from <tt>tt</tt>, but subscribe
-   * ourselves to it again.
+   * Copy constructor for SmartPointer. We do now copy the object subscribed
+   * to from <tt>tt</tt>, but subscribe ourselves to it again.
    */
   template <class Q>
   SmartPointer (const SmartPointer<T,Q> &tt);
 
   /**
-   * Copy constructor for
-   * SmartPointer. We do now
-   * copy the object subscribed to
-   * from <tt>tt</tt>, but subscribe
-   * ourselves to it again.
+   * Copy constructor for SmartPointer. We do now copy the object subscribed
+   * to from <tt>tt</tt>, but subscribe ourselves to it again.
    */
   SmartPointer (const SmartPointer<T,P> &tt);
 
   /**
-   * Constructor taking a normal
-   * pointer.  If possible, i.e. if
-   * the pointer is not a null
-   * pointer, the constructor
-   * subscribes to the given object
-   * to lock it, i.e. to prevent
-   * its destruction before the end
-   * of its use.
+   * Constructor taking a normal pointer.  If possible, i.e. if the pointer is
+   * not a null pointer, the constructor subscribes to the given object to
+   * lock it, i.e. to prevent its destruction before the end of its use.
    *
-   * The <tt>id</tt> is used in the
-   * call to
-   * Subscriptor::subscribe(id) and
-   * by ~SmartPointer() in the call
-   * to Subscriptor::unsubscribe().
+   * The <tt>id</tt> is used in the call to Subscriptor::subscribe(id) and by
+   * ~SmartPointer() in the call to Subscriptor::unsubscribe().
    */
   SmartPointer (T *t, const char *id);
 
   /**
-   * Constructor taking a normal
-   * pointer.  If possible, i.e. if
-   * the pointer is not a null
-   * pointer, the constructor
-   * subscribes to the given object
-   * to lock it, i.e. to prevent
-   * its destruction before the end
-   * of its use. The id of this
-   * pointer is set to the name of
-   * the class P.
+   * Constructor taking a normal pointer.  If possible, i.e. if the pointer is
+   * not a null pointer, the constructor subscribes to the given object to
+   * lock it, i.e. to prevent its destruction before the end of its use. The
+   * id of this pointer is set to the name of the class P.
    */
   SmartPointer (T *t);
 
 
   /**
-   * Destructor, removing the
-   * subscription.
+   * Destructor, removing the subscription.
    */
   ~SmartPointer();
 
   /**
-   * Assignment operator for normal
-   * pointers. The pointer
-   * subscribes to the new object
-   * automatically and unsubscribes
-   * to an old one if it exists. It
-   * will not try to subscribe to a
-   * null-pointer, but still
-   * delete the old subscription.
+   * Assignment operator for normal pointers. The pointer subscribes to the
+   * new object automatically and unsubscribes to an old one if it exists. It
+   * will not try to subscribe to a null-pointer, but still delete the old
+   * subscription.
    */
   SmartPointer<T,P> &operator= (T *tt);
 
   /**
-   * Assignment operator for
-   * SmartPointer.  The pointer
-   * subscribes to the new object
-   * automatically and unsubscribes
-   * to an old one if it exists.
+   * Assignment operator for SmartPointer.  The pointer subscribes to the new
+   * object automatically and unsubscribes to an old one if it exists.
    */
   template <class Q>
   SmartPointer<T,P> &operator= (const SmartPointer<T,Q> &tt);
 
   /**
-   * Assignment operator for
-   * SmartPointer.  The pointer
-   * subscribes to the new object
-   * automatically and unsubscribes
-   * to an old one if it exists.
+   * Assignment operator for SmartPointer.  The pointer subscribes to the new
+   * object automatically and unsubscribes to an old one if it exists.
    */
   SmartPointer<T,P> &operator= (const SmartPointer<T,P> &tt);
 
   /**
-   * Delete the object pointed to
-   * and set the pointer to zero.
+   * Delete the object pointed to and set the pointer to zero.
    */
   void clear ();
 
@@ -172,83 +138,56 @@ public:
   operator T *() const;
 
   /**
-   * Dereferencing operator. This
-   * operator throws an
-   * ExcNotInitialized if the
+   * Dereferencing operator. This operator throws an ExcNotInitialized if the
    * pointer is a null pointer.
    */
   T &operator * () const;
 
   /**
-   * Dereferencing operator. This
-   * operator throws an
-   * ExcNotInitialized if the
+   * Dereferencing operator. This operator throws an ExcNotInitialized if the
    * pointer is a null pointer.
    */
   T *operator -> () const;
 
   /**
-   * Exchange the pointers of this
-   * object and the argument. Since
-   * both the objects to which is
-   * pointed are subscribed to
-   * before and after, we do not
-   * have to change their
-   * subscription counters.
+   * Exchange the pointers of this object and the argument. Since both the
+   * objects to which is pointed are subscribed to before and after, we do not
+   * have to change their subscription counters.
    *
-   * Note that this function (with
-   * two arguments) and the
-   * respective functions where one
-   * of the arguments is a pointer
-   * and the other one is a C-style
-   * pointer are implemented in
-   * global namespace.
+   * Note that this function (with two arguments) and the respective functions
+   * where one of the arguments is a pointer and the other one is a C-style
+   * pointer are implemented in global namespace.
    */
   template <class Q>
   void swap (SmartPointer<T,Q> &tt);
 
   /**
-   * Swap pointers between this
-   * object and the pointer
-   * given. As this releases the
-   * object pointed to presently,
-   * we reduce its subscription
-   * count by one, and increase it
-   * at the object which we will
-   * point to in the future.
+   * Swap pointers between this object and the pointer given. As this releases
+   * the object pointed to presently, we reduce its subscription count by one,
+   * and increase it at the object which we will point to in the future.
    *
-   * Note that we indeed need a
-   * reference of a pointer, as we
-   * want to change the pointer
-   * variable which we are given.
+   * Note that we indeed need a reference of a pointer, as we want to change
+   * the pointer variable which we are given.
    */
   void swap (T *&tt);
 
   /**
-   * Return an estimate of the
-   * amount of memory (in bytes)
-   * used by this class. Note in
-   * particular, that this only
-   * includes the amount of memory
-   * used by <b>this</b> object, not
-   * by the object pointed to.
+   * Return an estimate of the amount of memory (in bytes) used by this class.
+   * Note in particular, that this only includes the amount of memory used by
+   * <b>this</b> object, not by the object pointed to.
    */
   std::size_t memory_consumption () const;
 
 private:
   /**
-   * Pointer to the object we want
-   * to subscribt to. Since it is
-   * often necessary to follow this
-   * pointer when debugging, we
-   * have deliberately chosen a
-   * short name.
+   * Pointer to the object we want to subscribt to. Since it is often
+   * necessary to follow this pointer when debugging, we have deliberately
+   * chosen a short name.
    */
   T *t;
 
   /**
-   * The identification for the
-   * subscriptor.
+   * The identification for the subscriptor.
    */
   const char *const id;
 };
@@ -482,9 +421,9 @@ SmartPointer<T,P>::memory_consumption () const
 // compiler.
 #ifndef _MSC_VER
 /**
- * Global function to swap the contents of two smart pointers. As both
- * objects to which the pointers point retain to be subscribed to, we
- * do not have to change their subscription count.
+ * Global function to swap the contents of two smart pointers. As both objects
+ * to which the pointers point retain to be subscribed to, we do not have to
+ * change their subscription count.
  */
 template <typename T, typename P, class Q>
 inline
@@ -496,11 +435,11 @@ void swap (SmartPointer<T,P> &t1, SmartPointer<T,Q> &t2)
 
 
 /**
- * Global function to swap the contents of a smart pointer and a
- * C-style pointer.
+ * Global function to swap the contents of a smart pointer and a C-style
+ * pointer.
  *
- * Note that we indeed need a reference of a pointer, as we want to
- * change the pointer variable which we are given.
+ * Note that we indeed need a reference of a pointer, as we want to change the
+ * pointer variable which we are given.
  */
 template <typename T, typename P>
 inline
@@ -512,11 +451,11 @@ void swap (SmartPointer<T,P> &t1, T *&t2)
 
 
 /**
- * Global function to swap the contents of a C-style pointer and a
- * smart pointer.
+ * Global function to swap the contents of a C-style pointer and a smart
+ * pointer.
  *
- * Note that we indeed need a reference of a pointer, as we want to
- * change the pointer variable which we are given.
+ * Note that we indeed need a reference of a pointer, as we want to change the
+ * pointer variable which we are given.
  */
 template <typename T, typename P>
 inline
index 557686184d35944a4e4097891f6bee7fc2c1026a..7c3b8dc67308b707cc25bbbb0d603857b06d68b9 100644 (file)
@@ -29,26 +29,26 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Handling of subscriptions.
  *
- * This class, as a base class, allows to keep track of other objects
- * using a specific object. It is used, when an object, given to a
- * constructor by reference, is stored. Then, the original object may
- * not be deleted before the dependent object is deleted. You can assert
- * this constraint by letting the object passed be derived from this class
- * and let the user subscribe() to this object. The destructor the used
- * object inherits from the Subscriptor class then will lead to an error
- * when destruction is attempted while there are still subscriptions.
+ * This class, as a base class, allows to keep track of other objects using a
+ * specific object. It is used, when an object, given to a constructor by
+ * reference, is stored. Then, the original object may not be deleted before
+ * the dependent object is deleted. You can assert this constraint by letting
+ * the object passed be derived from this class and let the user subscribe()
+ * to this object. The destructor the used object inherits from the
+ * Subscriptor class then will lead to an error when destruction is attempted
+ * while there are still subscriptions.
  *
- * The utility of this class is even enhanced by providing identifying
- * strings to the functions subscribe() and unsubscribe(). In case of
- * a hanging subscription during destruction, this string will be
- * listed in the exception's message. For reasons of efficiency, these
- * strings are handled as <tt>const char*</tt>. Therefore, the
- * pointers provided to subscribe() and to unsubscribe() must be the
- * same. Strings with equal contents will not be recognized to be the
- * same. The handling in SmartPointer will take care of this.
+ * The utility of this class is even enhanced by providing identifying strings
+ * to the functions subscribe() and unsubscribe(). In case of a hanging
+ * subscription during destruction, this string will be listed in the
+ * exception's message. For reasons of efficiency, these strings are handled
+ * as <tt>const char*</tt>. Therefore, the pointers provided to subscribe()
+ * and to unsubscribe() must be the same. Strings with equal contents will not
+ * be recognized to be the same. The handling in SmartPointer will take care
+ * of this.
  *
- * @note Due to a problem with <tt>volatile</tt> declarations, this
- * additional feature is switched off if multithreading is used.
+ * @note Due to a problem with <tt>volatile</tt> declarations, this additional
+ * feature is switched off if multithreading is used.
  *
  * @ingroup memory
  * @author Guido Kanschat, 1998 - 2005
@@ -64,57 +64,42 @@ public:
   /**
    * Copy-constructor.
    *
-   * The counter of the copy is zero,
-   * since references point to the
-   * original object.
+   * The counter of the copy is zero, since references point to the original
+   * object.
    */
   Subscriptor(const Subscriptor &);
 
   /**
-   * Destructor, asserting that the counter
-   * is zero.
+   * Destructor, asserting that the counter is zero.
    */
   virtual ~Subscriptor();
 
   /**
    * Assignment operator.
    *
-   * This has to be handled with
-   * care, too, because the counter
-   * has to remain the same. It therefore
-   * does nothing more than returning
-   * <tt>*this</tt>.
+   * This has to be handled with care, too, because the counter has to remain
+   * the same. It therefore does nothing more than returning <tt>*this</tt>.
    */
   Subscriptor &operator = (const Subscriptor &);
 
   /**
-   * Subscribes a user of the
-   * object. The subscriber may be
-   * identified by text supplied as
-   * <tt>identifier</tt>.
+   * Subscribes a user of the object. The subscriber may be identified by text
+   * supplied as <tt>identifier</tt>.
    */
   void subscribe (const char *identifier = 0) const;
 
   /**
-   * Unsubscribes a user from the
-   * object.
+   * Unsubscribes a user from the object.
    *
-   * @note The <tt>identifier</tt>
-   * must be the <b>same
-   * pointer</b> as the one
-   * supplied to subscribe(), not
-   * just the same text.
+   * @note The <tt>identifier</tt> must be the <b>same pointer</b> as the one
+   * supplied to subscribe(), not just the same text.
    */
   void unsubscribe (const char *identifier = 0) const;
 
   /**
-   * Return the present number of
-   * subscriptions to this object.
-   * This allows to use this class
-   * for reference counted lifetime
-   * determination where the last one
-   * to unsubscribe also deletes the
-   * object.
+   * Return the present number of subscriptions to this object. This allows to
+   * use this class for reference counted lifetime determination where the
+   * last one to unsubscribe also deletes the object.
    */
   unsigned int n_subscriptions () const;
 
@@ -123,13 +108,13 @@ public:
    */
   void list_subscribers () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
-   * Exception:
-   * Object may not be deleted, since
-   * it is used.
+   * Exception: Object may not be deleted, since it is used.
    */
   DeclException3(ExcInUse,
                  int, char *, std::string &,
@@ -141,10 +126,8 @@ public:
                  << "more information on what this error means.");
 
   /**
-   * A subscriber with the
-   * identification string given to
-   * Subscriptor::unsubscribe() did
-   * not subscribe to the object.
+   * A subscriber with the identification string given to
+   * Subscriptor::unsubscribe() did not subscribe to the object.
    */
   DeclException2(ExcNoSubscriber, char *, char *,
                  << "No subscriber with identifier \"" << arg2
@@ -152,97 +135,62 @@ public:
   //@}
 
   /**
-   * Read or write the data of this
-   * object to or from a stream for
-   * the purpose of serialization.
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization.
    *
-   * This function does not
-   * actually serialize any of the
-   * member variables of this
-   * class. The reason is that what
-   * this class stores is only who
-   * subscribes to this object, but
-   * who does so at the time of
-   * storing the contents of this
-   * object does not necessarily
-   * have anything to do with who
-   * subscribes to the object when
-   * it is restored. Consequently,
-   * we do not want to overwrite
-   * the subscribers at the time of
-   * restoring, and then there is
-   * no reason to write the
-   * subscribers out in the first
-   * place.
+   * This function does not actually serialize any of the member variables of
+   * this class. The reason is that what this class stores is only who
+   * subscribes to this object, but who does so at the time of storing the
+   * contents of this object does not necessarily have anything to do with who
+   * subscribes to the object when it is restored. Consequently, we do not
+   * want to overwrite the subscribers at the time of restoring, and then
+   * there is no reason to write the subscribers out in the first place.
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
 
 private:
   /**
-   * The data type used in
-   * #counter_map.
+   * The data type used in #counter_map.
    */
   typedef std::map<const char *, unsigned int>::value_type
   map_value_type;
 
   /**
-   * The iterator type used in
-   * #counter_map.
+   * The iterator type used in #counter_map.
    */
   typedef std::map<const char *, unsigned int>::iterator
   map_iterator;
 
   /**
-   * Store the number of objects
-   * which subscribed to this
-   * object. Initialally, this
-   * number is zero, and upon
-   * destruction it shall be zero
-   * again (i.e. all objects which
-   * subscribed should have
-   * unsubscribed again).
+   * Store the number of objects which subscribed to this object. Initialally,
+   * this number is zero, and upon destruction it shall be zero again (i.e.
+   * all objects which subscribed should have unsubscribed again).
    *
-   * The creator (and owner) of an
-   * object is counted in the map
-   * below if HE manages to supply
-   * identification.
+   * The creator (and owner) of an object is counted in the map below if HE
+   * manages to supply identification.
    *
-   * We use the <tt>mutable</tt> keyword
-   * in order to allow subscription
-   * to constant objects also.
+   * We use the <tt>mutable</tt> keyword in order to allow subscription to
+   * constant objects also.
    *
-   * In multithreaded mode, this
-   * counter may be modified by
-   * different threads. We thus
-   * have to mark it
-   * <tt>volatile</tt>. However, this is
-   * counter-productive in non-MT
-   * mode since it may pessimize
-   * code. So use the macro
-   * defined above to selectively
-   * add volatility.
+   * In multithreaded mode, this counter may be modified by different threads.
+   * We thus have to mark it <tt>volatile</tt>. However, this is counter-
+   * productive in non-MT mode since it may pessimize code. So use the macro
+   * defined above to selectively add volatility.
    */
   mutable DEAL_VOLATILE unsigned int counter;
 
   /**
-   * In this map, we count
-   * subscriptions for each
-   * different identification string
-   * supplied to subscribe().
+   * In this map, we count subscriptions for each different identification
+   * string supplied to subscribe().
    */
   mutable std::map<const char *, unsigned int> counter_map;
 
   /**
-   * Pointer to the typeinfo object
-   * of this object, from which we
-   * can later deduce the class
-   * name. Since this information
-   * on the derived class is
-   * neither available in the
-   * destructor, nor in the
-   * constructor, we obtain it in
-   * between and store it here.
+   * Pointer to the typeinfo object of this object, from which we can later
+   * deduce the class name. Since this information on the derived class is
+   * neither available in the destructor, nor in the constructor, we obtain it
+   * in between and store it here.
    */
   mutable const std::type_info *object_info;
 };
index 48a38aaefd2fc40c7db6111989a1453936bf24d0..63f4a025cca5cc489729ab4cd3b0e0583fced1ec 100644 (file)
@@ -46,21 +46,15 @@ determinant (const SymmetricTensor<2,dim,Number> &);
 namespace internal
 {
   /**
-   * A namespace for classes that are
-   * internal to how the SymmetricTensor
+   * A namespace for classes that are internal to how the SymmetricTensor
    * class works.
    */
   namespace SymmetricTensorAccessors
   {
     /**
-     * Create a TableIndices<2>
-     * object where the first entries
-     * up to <tt>position-1</tt> are
-     * taken from previous_indices,
-     * and new_index is put at
-     * position
-     * <tt>position</tt>. The
-     * remaining indices remain in
+     * Create a TableIndices<2> object where the first entries up to
+     * <tt>position-1</tt> are taken from previous_indices, and new_index is
+     * put at position <tt>position</tt>. The remaining indices remain in
      * invalid state.
      */
     inline
@@ -79,14 +73,9 @@ namespace internal
 
 
     /**
-     * Create a TableIndices<4>
-     * object where the first entries
-     * up to <tt>position-1</tt> are
-     * taken from previous_indices,
-     * and new_index is put at
-     * position
-     * <tt>position</tt>. The
-     * remaining indices remain in
+     * Create a TableIndices<4> object where the first entries up to
+     * <tt>position-1</tt> are taken from previous_indices, and new_index is
+     * put at position <tt>position</tt>. The remaining indices remain in
      * invalid state.
      */
     inline
@@ -119,16 +108,10 @@ namespace internal
 
 
     /**
-     * Typedef template magic
-     * denoting the result of a
-     * double contraction between two
-     * tensors or ranks rank1 and
-     * rank2. In general, this is a
-     * tensor of rank
-     * <tt>rank1+rank2-4</tt>, but if
-     * this is zero it is a single
-     * scalar Number. For this case,
-     * we have a specialization.
+     * Typedef template magic denoting the result of a double contraction
+     * between two tensors or ranks rank1 and rank2. In general, this is a
+     * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
+     * single scalar Number. For this case, we have a specialization.
      *
      * @author Wolfgang Bangerth, 2005
      */
@@ -140,16 +123,10 @@ namespace internal
 
 
     /**
-     * Typedef template magic
-     * denoting the result of a
-     * double contraction between two
-     * tensors or ranks rank1 and
-     * rank2. In general, this is a
-     * tensor of rank
-     * <tt>rank1+rank2-4</tt>, but if
-     * this is zero it is a single
-     * scalar Number. For this case,
-     * we have a specialization.
+     * Typedef template magic denoting the result of a double contraction
+     * between two tensors or ranks rank1 and rank2. In general, this is a
+     * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
+     * single scalar Number. For this case, we have a specialization.
      *
      * @author Wolfgang Bangerth, 2005
      */
@@ -162,45 +139,35 @@ namespace internal
 
 
     /**
-     * Declaration of typedefs for the type
-     * of data structures which are used to
-     * store symmetric tensors. For example,
-     * for rank-2 symmetric tensors, we use a
-     * flat vector to store all the
-     * elements. On the other hand, symmetric
-     * rank-4 tensors are mappings from
-     * symmetric rank-2 tensors into
-     * symmetric rank-2 tensors, so they can
-     * be represented as matrices, etc.
+     * Declaration of typedefs for the type of data structures which are used
+     * to store symmetric tensors. For example, for rank-2 symmetric tensors,
+     * we use a flat vector to store all the elements. On the other hand,
+     * symmetric rank-4 tensors are mappings from symmetric rank-2 tensors
+     * into symmetric rank-2 tensors, so they can be represented as matrices,
+     * etc.
      *
-     * This information is probably of little
-     * interest to all except the accessor
-     * classes that need it. In particular,
-     * you shouldn't make any assumptions
-     * about the storage format in your
-     * application programs.
+     * This information is probably of little interest to all except the
+     * accessor classes that need it. In particular, you shouldn't make any
+     * assumptions about the storage format in your application programs.
      */
     template <int rank, int dim, typename Number>
     struct StorageType;
 
     /**
-     * Specialization of StorageType for
-     * rank-2 tensors.
+     * Specialization of StorageType for rank-2 tensors.
      */
     template <int dim, typename Number>
     struct StorageType<2,dim,Number>
     {
       /**
-       * Number of independent components of a
-       * symmetric tensor of rank 2. We store
-       * only the upper right half of it.
+       * Number of independent components of a symmetric tensor of rank 2. We
+       * store only the upper right half of it.
        */
       static const unsigned int
       n_independent_components = (dim*dim + dim)/2;
 
       /**
-       * Declare the type in which we actually
-       * store the data.
+       * Declare the type in which we actually store the data.
        */
       typedef Tensor<1,n_independent_components,Number> base_tensor_type;
     };
@@ -208,38 +175,31 @@ namespace internal
 
 
     /**
-     * Specialization of StorageType for
-     * rank-4 tensors.
+     * Specialization of StorageType for rank-4 tensors.
      */
     template <int dim, typename Number>
     struct StorageType<4,dim,Number>
     {
       /**
-       * Number of independent components
-       * of a symmetric tensor of rank
-       * 2. Since rank-4 tensors are
-       * mappings between such objects, we
-       * need this information.
+       * Number of independent components of a symmetric tensor of rank 2.
+       * Since rank-4 tensors are mappings between such objects, we need this
+       * information.
        */
       static const unsigned int
       n_rank2_components = (dim*dim + dim)/2;
 
       /**
-       * Number of independent components of a
-       * symmetric tensor of rank 4.
+       * Number of independent components of a symmetric tensor of rank 4.
        */
       static const unsigned int
       n_independent_components = (n_rank2_components *
                                   StorageType<2,dim,Number>::n_independent_components);
 
       /**
-       * Declare the type in which we
-       * actually store the data. Symmetric
-       * rank-4 tensors are mappings
-       * between symmetric rank-2 tensors,
-       * so we can represent the data as a
-       * matrix if we represent the rank-2
-       * tensors as vectors.
+       * Declare the type in which we actually store the data. Symmetric
+       * rank-4 tensors are mappings between symmetric rank-2 tensors, so we
+       * can represent the data as a matrix if we represent the rank-2 tensors
+       * as vectors.
        */
       typedef Tensor<2,n_rank2_components,Number> base_tensor_type;
     };
@@ -247,19 +207,15 @@ namespace internal
 
 
     /**
-     * Switch type to select a tensor of
-     * rank 2 and dimension <tt>dim</tt>,
-     * switching on whether the tensor
-     * should be constant or not.
+     * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+     * switching on whether the tensor should be constant or not.
      */
     template <int rank, int dim, bool constness, typename Number>
     struct AccessorTypes;
 
     /**
-     * Switch type to select a tensor of
-     * rank 2 and dimension <tt>dim</tt>,
-     * switching on whether the tensor
-     * should be constant or not.
+     * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+     * switching on whether the tensor should be constant or not.
      *
      * Specialization for constant tensors.
      */
@@ -272,13 +228,10 @@ namespace internal
     };
 
     /**
-     * Switch type to select a tensor of
-     * rank 2 and dimension <tt>dim</tt>,
-     * switching on whether the tensor
-     * should be constant or not.
+     * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+     * switching on whether the tensor should be constant or not.
      *
-     * Specialization for non-constant
-     * tensors.
+     * Specialization for non-constant tensors.
      */
     template <int rank, int dim, typename Number>
     struct AccessorTypes<rank,dim,false,Number>
@@ -292,32 +245,31 @@ namespace internal
     /**
      * @internal
      *
-     * Class that acts as accessor to elements of type
-     * SymmetricTensor. The template parameter <tt>C</tt> may be either
-     * true or false, and indicates whether the objects worked on are
-     * constant or not (i.e. write access is only allowed if the value is
-     * false).
+     * Class that acts as accessor to elements of type SymmetricTensor. The
+     * template parameter <tt>C</tt> may be either true or false, and
+     * indicates whether the objects worked on are constant or not (i.e. write
+     * access is only allowed if the value is false).
      *
      * Since with <tt>N</tt> indices, the effect of applying
      * <tt>operator[]</tt> is getting access to something we <tt>N-1</tt>
-     * indices, we have to implement these accessor classes recursively,
-     * with stopping when we have only one index left. For the latter
-     * case, a specialization of this class is declared below, where
-     * calling <tt>operator[]</tt> gives you access to the objects
-     * actually stored by the tensor; the tensor class also makes sure
-     * that only those elements are actually accessed which we actually
-     * store, i.e. it reorders indices if necessary. The template
-     * parameter <tt>P</tt> indicates how many remaining indices there
-     * are. For a rank-2 tensor, <tt>P</tt> may be two, and when using
-     * <tt>operator[]</tt>, an object with <tt>P=1</tt> emerges.
+     * indices, we have to implement these accessor classes recursively, with
+     * stopping when we have only one index left. For the latter case, a
+     * specialization of this class is declared below, where calling
+     * <tt>operator[]</tt> gives you access to the objects actually stored by
+     * the tensor; the tensor class also makes sure that only those elements
+     * are actually accessed which we actually store, i.e. it reorders indices
+     * if necessary. The template parameter <tt>P</tt> indicates how many
+     * remaining indices there are. For a rank-2 tensor, <tt>P</tt> may be
+     * two, and when using <tt>operator[]</tt>, an object with <tt>P=1</tt>
+     * emerges.
      *
      * As stated for the entire namespace, you will not usually have to do
-     * with these classes directly, and should not try to use their
-     * interface directly as it may change without notice. In fact, since
-     * the constructors are made private, you will not even be able to
-     * generate objects of this class, as they are only thought as
-     * temporaries for access to elements of the table class, not for
-     * passing them around as arguments of functions, etc.
+     * with these classes directly, and should not try to use their interface
+     * directly as it may change without notice. In fact, since the
+     * constructors are made private, you will not even be able to generate
+     * objects of this class, as they are only thought as temporaries for
+     * access to elements of the table class, not for passing them around as
+     * arguments of functions, etc.
      *
      * This class is an adaptation of a similar class used for the Table
      * class.
@@ -329,67 +281,40 @@ namespace internal
     {
     public:
       /**
-       * Import two typedefs from the
-       * switch class above.
+       * Import two typedefs from the switch class above.
        */
       typedef typename AccessorTypes<rank,dim,constness,Number>::reference reference;
       typedef typename AccessorTypes<rank,dim,constness,Number>::tensor_type tensor_type;
 
     private:
       /**
-       * Constructor. Take a
-       * reference to the tensor
-       * object which we will
+       * Constructor. Take a reference to the tensor object which we will
        * access.
        *
-       * The second argument
-       * denotes the values of
-       * previous indices into the
-       * tensor. For example, for a
-       * rank-4 tensor, if P=2,
-       * then we will already have
-       * had two successive element
-       * selections (e.g. through
-       * <tt>tensor[1][2]</tt>),
-       * and the two index values
-       * have to be stored
-       * somewhere. This class
-       * therefore only makes use
-       * of the first rank-P
-       * elements of this array,
-       * but passes it on to the
-       * next level with P-1 which
-       * fills the next entry, and
-       * so on.
+       * The second argument denotes the values of previous indices into the
+       * tensor. For example, for a rank-4 tensor, if P=2, then we will
+       * already have had two successive element selections (e.g. through
+       * <tt>tensor[1][2]</tt>), and the two index values have to be stored
+       * somewhere. This class therefore only makes use of the first rank-P
+       * elements of this array, but passes it on to the next level with P-1
+       * which fills the next entry, and so on.
        *
-       * The constructor is made
-       * private in order to prevent
-       * you having such objects
-       * around. The only way to
-       * create such objects is via
-       * the <tt>Table</tt> class, which
-       * only generates them as
-       * temporary objects. This
-       * guarantees that the accessor
-       * objects go out of scope
-       * earlier than the mother
-       * object, avoid problems with
-       * data consistency.
+       * The constructor is made private in order to prevent you having such
+       * objects around. The only way to create such objects is via the
+       * <tt>Table</tt> class, which only generates them as temporary objects.
+       * This guarantees that the accessor objects go out of scope earlier
+       * than the mother object, avoid problems with data consistency.
        */
       Accessor (tensor_type              &tensor,
                 const TableIndices<rank> &previous_indices);
 
       /**
-       * Default constructor. Not
-       * needed, and invisible, so
-       * private.
+       * Default constructor. Not needed, and invisible, so private.
        */
       Accessor ();
 
       /**
-       * Copy constructor. Not
-       * needed, and invisible, so
-       * private.
+       * Copy constructor. Not needed, and invisible, so private.
        */
       Accessor (const Accessor &a);
 
@@ -402,8 +327,7 @@ namespace internal
 
     private:
       /**
-       * Store the data given to the
-       * constructor.
+       * Store the data given to the constructor.
        */
       tensor_type             &tensor;
       const TableIndices<rank> previous_indices;
@@ -424,12 +348,11 @@ namespace internal
 
 
     /**
-     * @internal
-     * Accessor class for SymmetricTensor. This is the specialization for the last
-     * index, which actually allows access to the elements of the table,
-     * rather than recursively returning access objects for further
-     * subsets. The same holds for this specialization as for the general
-     * template; see there for more information.
+     * @internal Accessor class for SymmetricTensor. This is the
+     * specialization for the last index, which actually allows access to the
+     * elements of the table, rather than recursively returning access objects
+     * for further subsets. The same holds for this specialization as for the
+     * general template; see there for more information.
      *
      * @author Wolfgang Bangerth, 2002, 2005
      */
@@ -438,72 +361,43 @@ namespace internal
     {
     public:
       /**
-       * Import two typedefs from the
-       * switch class above.
+       * Import two typedefs from the switch class above.
        */
       typedef typename AccessorTypes<rank,dim,constness,Number>::reference reference;
       typedef typename AccessorTypes<rank,dim,constness,Number>::tensor_type tensor_type;
 
     private:
       /**
-       * Constructor. Take a
-       * reference to the tensor
-       * object which we will
+       * Constructor. Take a reference to the tensor object which we will
        * access.
        *
-       * The second argument
-       * denotes the values of
-       * previous indices into the
-       * tensor. For example, for a
-       * rank-4 tensor, if P=2,
-       * then we will already have
-       * had two successive element
-       * selections (e.g. through
-       * <tt>tensor[1][2]</tt>),
-       * and the two index values
-       * have to be stored
-       * somewhere. This class
-       * therefore only makes use
-       * of the first rank-P
-       * elements of this array,
-       * but passes it on to the
-       * next level with P-1 which
-       * fills the next entry, and
-       * so on.
+       * The second argument denotes the values of previous indices into the
+       * tensor. For example, for a rank-4 tensor, if P=2, then we will
+       * already have had two successive element selections (e.g. through
+       * <tt>tensor[1][2]</tt>), and the two index values have to be stored
+       * somewhere. This class therefore only makes use of the first rank-P
+       * elements of this array, but passes it on to the next level with P-1
+       * which fills the next entry, and so on.
        *
-       * For this particular
-       * specialization, i.e. for
-       * P==1, all but the last
+       * For this particular specialization, i.e. for P==1, all but the last
        * index are already filled.
        *
-       * The constructor is made
-       * private in order to prevent
-       * you having such objects
-       * around. The only way to
-       * create such objects is via
-       * the <tt>Table</tt> class, which
-       * only generates them as
-       * temporary objects. This
-       * guarantees that the accessor
-       * objects go out of scope
-       * earlier than the mother
-       * object, avoid problems with
-       * data consistency.
+       * The constructor is made private in order to prevent you having such
+       * objects around. The only way to create such objects is via the
+       * <tt>Table</tt> class, which only generates them as temporary objects.
+       * This guarantees that the accessor objects go out of scope earlier
+       * than the mother object, avoid problems with data consistency.
        */
       Accessor (tensor_type              &tensor,
                 const TableIndices<rank> &previous_indices);
 
       /**
-       * Default constructor. Not
-       * needed, and invisible, so
-       * private.
+       * Default constructor. Not needed, and invisible, so private.
        */
       Accessor ();
 
       /**
-       * Copy constructor. Not
-       * needed, and invisible, so
-       * private.
+       * Copy constructor. Not needed, and invisible, so private.
        */
       Accessor (const Accessor &a);
 
@@ -516,8 +410,7 @@ namespace internal
 
     private:
       /**
-       * Store the data given to the
-       * constructor.
+       * Store the data given to the constructor.
        */
       tensor_type             &tensor;
       const TableIndices<rank> previous_indices;
@@ -557,25 +450,23 @@ namespace internal
  * example for the 3x3x3x3 tensors of rank 4, only 36 instead of the full 81
  * entries have to be stored.
  *
- * While the definition of a symmetric rank-2 tensor is obvious,
- * tensors of rank 4 are considered symmetric if they are operators
- * mapping symmetric rank-2 tensors onto symmetric rank-2
- * tensors. This entails certain symmetry properties on the elements
- * in their 4-dimensional index space, in particular that
- * <tt>C<sub>ijkl</sub>=C<sub>jikl</sub>=C<sub>ijlk</sub></tt>. However,
- * it does not imply the relation
- * <tt>C<sub>ijkl</sub>=C<sub>klij</sub></tt>. Consequently, symmetric
- * tensors of rank 4 as understood here are only tensors that map
- * symmetric tensors onto symmetric tensors, but they do not
- * necessarily induce a symmetric scalar product <tt>a:C:b=b:C:a</tt>
- * or even a positive (semi-)definite form <tt>a:C:a</tt>, where
- * <tt>a,b</tt> are symmetric rank-2 tensors and the colon indicates
- * the common double-index contraction that acts as a product for
- * symmetric tensors.
+ * While the definition of a symmetric rank-2 tensor is obvious, tensors of
+ * rank 4 are considered symmetric if they are operators mapping symmetric
+ * rank-2 tensors onto symmetric rank-2 tensors. This entails certain symmetry
+ * properties on the elements in their 4-dimensional index space, in
+ * particular that
+ * <tt>C<sub>ijkl</sub>=C<sub>jikl</sub>=C<sub>ijlk</sub></tt>. However, it
+ * does not imply the relation <tt>C<sub>ijkl</sub>=C<sub>klij</sub></tt>.
+ * Consequently, symmetric tensors of rank 4 as understood here are only
+ * tensors that map symmetric tensors onto symmetric tensors, but they do not
+ * necessarily induce a symmetric scalar product <tt>a:C:b=b:C:a</tt> or even
+ * a positive (semi-)definite form <tt>a:C:a</tt>, where <tt>a,b</tt> are
+ * symmetric rank-2 tensors and the colon indicates the common double-index
+ * contraction that acts as a product for symmetric tensors.
  *
  * Symmetric tensors are most often used in structural and fluid mechanics,
- * where strains and stresses are usually symmetric tensors, and the
- * stress-strain relationship is given by a symmetric rank-4 tensor.
+ * where strains and stresses are usually symmetric tensors, and the stress-
+ * strain relationship is given by a symmetric rank-4 tensor.
  *
  * Note that symmetric tensors only exist with even numbers of indices. In
  * other words, the only objects that you can use are
@@ -586,21 +477,19 @@ namespace internal
  *
  * <h3>Accessing elements</h3>
  *
- * The elements of a tensor <tt>t</tt> can be accessed using the
- * bracket operator, i.e. for a tensor of rank 4,
- * <tt>t[0][1][0][1]</tt> accesses the element
- * <tt>t<sub>0101</sub></tt>. This access can be used for both reading
- * and writing (if the tensor is non-constant at least). You may also
- * perform other operations on it, although that may lead to confusing
- * situations because several elements of the tensor are stored at the
- * same location. For example, for a rank-2 tensor that is assumed to
- * be zero at the beginning, writing <tt>t[0][1]+=1; t[1][0]+=1;</tt>
- * will lead to the same element being increased by one
- * <em>twice</em>, because even though the accesses use different
- * indices, the elements that are accessed are symmetric and therefore
- * stored at the same location. It may therefore be useful in
- * application programs to restrict operations on individual elements
- * to simple reads or writes.
+ * The elements of a tensor <tt>t</tt> can be accessed using the bracket
+ * operator, i.e. for a tensor of rank 4, <tt>t[0][1][0][1]</tt> accesses the
+ * element <tt>t<sub>0101</sub></tt>. This access can be used for both reading
+ * and writing (if the tensor is non-constant at least). You may also perform
+ * other operations on it, although that may lead to confusing situations
+ * because several elements of the tensor are stored at the same location. For
+ * example, for a rank-2 tensor that is assumed to be zero at the beginning,
+ * writing <tt>t[0][1]+=1; t[1][0]+=1;</tt> will lead to the same element
+ * being increased by one <em>twice</em>, because even though the accesses use
+ * different indices, the elements that are accessed are symmetric and
+ * therefore stored at the same location. It may therefore be useful in
+ * application programs to restrict operations on individual elements to
+ * simple reads or writes.
  *
  * @ingroup geomprimitives
  * @author Wolfgang Bangerth, 2005
@@ -610,340 +499,232 @@ class SymmetricTensor
 {
 public:
   /**
-   * Provide a way to get the
-   * dimension of an object without
-   * explicit knowledge of it's
-   * data type. Implementation is
-   * this way instead of providing
-   * a function <tt>dimension()</tt>
-   * because now it is possible to
-   * get the dimension at compile
-   * time without the expansion and
-   * preevaluation of an inlined
-   * function; the compiler may
-   * therefore produce more
-   * efficient code and you may use
-   * this value to declare other
-   * data types.
+   * Provide a way to get the dimension of an object without explicit
+   * knowledge of it's data type. Implementation is this way instead of
+   * providing a function <tt>dimension()</tt> because now it is possible to
+   * get the dimension at compile time without the expansion and preevaluation
+   * of an inlined function; the compiler may therefore produce more efficient
+   * code and you may use this value to declare other data types.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * An integer denoting the number of
-   * independent components that fully
-   * describe a symmetric tensor. In $d$
-   * space dimensions, this number equals
-   * $\frac 12 (d^2+d)$ for symmetric
-   * tensors of rank 2.
+   * An integer denoting the number of independent components that fully
+   * describe a symmetric tensor. In $d$ space dimensions, this number equals
+   * $\frac 12 (d^2+d)$ for symmetric tensors of rank 2.
    */
   static const unsigned int n_independent_components
     = internal::SymmetricTensorAccessors::StorageType<rank,dim,Number>::
       n_independent_components;
 
   /**
-   * Default constructor. Creates a zero
-   * tensor.
+   * Default constructor. Creates a zero tensor.
    */
   SymmetricTensor ();
 
   /**
-   * Constructor. Generate a symmetric
-   * tensor from a general one. Assumes
-   * that @p t is already symmetric, and in
-   * debug mode this is in fact
-   * checked. Note that no provision is
-   * made to assure that the tensor is
-   * symmetric only up to round-off error:
-   * if the incoming tensor is not exactly
-   * symmetric, then an exception is
-   * thrown. If you know that incoming
-   * tensor is symmetric only up to
-   * round-off, then you may want to call
-   * the <tt>symmetrize</tt> function
-   * first. If you aren't sure, it is good
-   * practice to check before calling
-   * <tt>symmetrize</tt>.
+   * Constructor. Generate a symmetric tensor from a general one. Assumes that
+   * @p t is already symmetric, and in debug mode this is in fact checked.
+   * Note that no provision is made to assure that the tensor is symmetric
+   * only up to round-off error: if the incoming tensor is not exactly
+   * symmetric, then an exception is thrown. If you know that incoming tensor
+   * is symmetric only up to round-off, then you may want to call the
+   * <tt>symmetrize</tt> function first. If you aren't sure, it is good
+   * practice to check before calling <tt>symmetrize</tt>.
    */
   SymmetricTensor (const Tensor<2,dim,Number> &t);
 
   /**
-   * A constructor that creates a
-   * symmetric tensor from an array
-   * holding its independent
-   * elements. Using this
-   * constructor assumes that the
-   * caller knows the order in
-   * which elements are stored in
-   * symmetric tensors; its use is
-   * therefore discouraged, but if
-   * you think you want to use it
-   * anyway you can query the order
-   * of elements using the
-   * unrolled_index() function.
+   * A constructor that creates a symmetric tensor from an array holding its
+   * independent elements. Using this constructor assumes that the caller
+   * knows the order in which elements are stored in symmetric tensors; its
+   * use is therefore discouraged, but if you think you want to use it anyway
+   * you can query the order of elements using the unrolled_index() function.
    *
-   * This constructor is currently only
-   * implemented for symmetric tensors of
+   * This constructor is currently only implemented for symmetric tensors of
    * rank 2.
    *
-   * The size of the array passed
-   * is equal to
-   * SymmetricTensor<rank,dim>::n_independent_component;
-   * the reason for using the
-   * object from the internal
-   * namespace is to work around
-   * bugs in some older compilers.
+   * The size of the array passed is equal to
+   * SymmetricTensor<rank,dim>::n_independent_component; the reason for using
+   * the object from the internal namespace is to work around bugs in some
+   * older compilers.
    */
   SymmetricTensor (const Number (&array) [n_independent_components]);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   SymmetricTensor &operator = (const SymmetricTensor &);
 
   /**
-   * This operator assigns a scalar
-   * to a tensor. To avoid
-   * confusion with what exactly it
-   * means to assign a scalar value
-   * to a tensor, zero is the only
-   * value allowed for <tt>d</tt>,
-   * allowing the intuitive
-   * notation <tt>t=0</tt> to reset
-   * all elements of the tensor to
-   * zero.
+   * This operator assigns a scalar to a tensor. To avoid confusion with what
+   * exactly it means to assign a scalar value to a tensor, zero is the only
+   * value allowed for <tt>d</tt>, allowing the intuitive notation
+   * <tt>t=0</tt> to reset all elements of the tensor to zero.
    */
   SymmetricTensor &operator = (const Number d);
 
   /**
-   * Convert the present symmetric tensor
-   * into a full tensor with the same
-   * elements, but using the different
-   * storage scheme of full tensors.
+   * Convert the present symmetric tensor into a full tensor with the same
+   * elements, but using the different storage scheme of full tensors.
    */
   operator Tensor<rank,dim,Number> () const;
 
   /**
-   *  Test for equality of two tensors.
+   * Test for equality of two tensors.
    */
   bool operator == (const SymmetricTensor &) const;
 
   /**
-   *  Test for inequality of two tensors.
+   * Test for inequality of two tensors.
    */
   bool operator != (const SymmetricTensor &) const;
 
   /**
-   *  Add another tensor.
+   * Add another tensor.
    */
   SymmetricTensor &operator += (const SymmetricTensor &);
 
   /**
-   *  Subtract another tensor.
+   * Subtract another tensor.
    */
   SymmetricTensor &operator -= (const SymmetricTensor &);
 
   /**
-   *  Scale the tensor by <tt>factor</tt>,
-   *  i.e. multiply all components by
-   *  <tt>factor</tt>.
+   * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
+   * <tt>factor</tt>.
    */
   SymmetricTensor &operator *= (const Number factor);
 
   /**
-   *  Scale the vector by
-   *  <tt>1/factor</tt>.
+   * Scale the vector by <tt>1/factor</tt>.
    */
   SymmetricTensor &operator /= (const Number factor);
 
   /**
-   *  Add two tensors. If possible, you
-   *  should use <tt>operator +=</tt>
-   *  instead since this does not need the
-   *  creation of a temporary.
+   * Add two tensors. If possible, you should use <tt>operator +=</tt> instead
+   * since this does not need the creation of a temporary.
    */
   SymmetricTensor   operator + (const SymmetricTensor &s) const;
 
   /**
-   *  Subtract two tensors. If possible,
-   *  you should use <tt>operator -=</tt>
-   *  instead since this does not need the
-   *  creation of a temporary.
+   * Subtract two tensors. If possible, you should use <tt>operator -=</tt>
+   * instead since this does not need the creation of a temporary.
    */
   SymmetricTensor   operator - (const SymmetricTensor &s) const;
 
   /**
-   * Unary minus operator. Negate all
-   * entries of a tensor.
+   * Unary minus operator. Negate all entries of a tensor.
    */
   SymmetricTensor   operator - () const;
 
   /**
-   * Product between the present
-   * symmetric tensor and a tensor
-   * of rank 2. For example, if the
-   * present object is also a
-   * rank-2 tensor, then this is
-   * the scalar-product double
-   * contraction
-   * <tt>a<sub>ij</sub>b<sub>ij</sub></tt>
-   * over all indices
-   * <tt>i,j</tt>. In this case,
-   * the return value evaluates to
-   * a single scalar. While it is
-   * possible to define other
-   * scalar product (and associated
-   * induced norms), this one seems
-   * to be the most appropriate
+   * Product between the present symmetric tensor and a tensor of rank 2. For
+   * example, if the present object is also a rank-2 tensor, then this is the
+   * scalar-product double contraction <tt>a<sub>ij</sub>b<sub>ij</sub></tt>
+   * over all indices <tt>i,j</tt>. In this case, the return value evaluates
+   * to a single scalar. While it is possible to define other scalar product
+   * (and associated induced norms), this one seems to be the most appropriate
    * one.
    *
-   * If the present object is a
-   * rank-4 tensor, then the result
-   * is a rank-2 tensor, i.e., the
-   * operation contracts over the
-   * last two indices of the
-   * present object and the indices
-   * of the argument, and the
-   * result is a tensor of rank 2.
+   * If the present object is a rank-4 tensor, then the result is a rank-2
+   * tensor, i.e., the operation contracts over the last two indices of the
+   * present object and the indices of the argument, and the result is a
+   * tensor of rank 2.
    *
-   * Note that the multiplication
-   * operator for symmetrict
-   * tensors is defined to be a
-   * double contraction over two
-   * indices, while it is defined
-   * as a single contraction over
-   * only one index for regular
-   * <tt>Tensor</tt> objects. For
-   * symmetric tensors it therefore
-   * acts in a way that is commonly
-   * denoted by a "colon
-   * multiplication" in the
-   * mathematica literature.
+   * Note that the multiplication operator for symmetrict tensors is defined
+   * to be a double contraction over two indices, while it is defined as a
+   * single contraction over only one index for regular <tt>Tensor</tt>
+   * objects. For symmetric tensors it therefore acts in a way that is
+   * commonly denoted by a "colon multiplication" in the mathematica
+   * literature.
    *
-   * There are global functions
-   * <tt>double_contract</tt> that
-   * do the same work as this
-   * operator, but rather than
-   * returning the result as a
-   * return value, they write it
-   * into the first argument to the
-   * function.
+   * There are global functions <tt>double_contract</tt> that do the same work
+   * as this operator, but rather than returning the result as a return value,
+   * they write it into the first argument to the function.
    */
   typename internal::SymmetricTensorAccessors::double_contraction_result<rank,2,dim,Number>::type
   operator * (const SymmetricTensor<2,dim,Number> &s) const;
 
   /**
-   * Contraction over two indices
-   * of the present object with the
-   * rank-4 symmetric tensor given
-   * as argument.
+   * Contraction over two indices of the present object with the rank-4
+   * symmetric tensor given as argument.
    */
   typename internal::SymmetricTensorAccessors::double_contraction_result<rank,4,dim,Number>::type
   operator * (const SymmetricTensor<4,dim,Number> &s) const;
 
   /**
-   * Return a read-write reference
-   * to the indicated element.
+   * Return a read-write reference to the indicated element.
    */
   Number &operator() (const TableIndices<rank> &indices);
 
   /**
-   * Return the value of the
-   * indicated element as a
-   * read-only reference.
+   * Return the value of the indicated element as a read-only reference.
    *
-   * We return the requested value
-   * as a constant reference rather
-   * than by value since this
-   * object may hold data types
-   * that may be large, and we
-   * don't know here whether
-   * copying is expensive or not.
+   * We return the requested value as a constant reference rather than by
+   * value since this object may hold data types that may be large, and we
+   * don't know here whether copying is expensive or not.
    */
   Number operator() (const TableIndices<rank> &indices) const;
 
   /**
-   * Access the elements of a row of this
-   * symmetric tensor. This function is
+   * Access the elements of a row of this symmetric tensor. This function is
    * called for constant tensors.
    */
   internal::SymmetricTensorAccessors::Accessor<rank,dim,true,rank-1,Number>
   operator [] (const unsigned int row) const;
 
   /**
-   * Access the elements of a row of this
-   * symmetric tensor. This function is
+   * Access the elements of a row of this symmetric tensor. This function is
    * called for non-constant tensors.
    */
   internal::SymmetricTensorAccessors::Accessor<rank,dim,false,rank-1,Number>
   operator [] (const unsigned int row);
 
   /**
-   * Access to an element where you
-   * specify the entire set of
-   * indices.
+   * Access to an element where you specify the entire set of indices.
    */
   Number
   operator [] (const TableIndices<rank> &indices) const;
 
   /**
-   * Access to an element where you
-   * specify the entire set of
-   * indices.
+   * Access to an element where you specify the entire set of indices.
    */
   Number &
   operator [] (const TableIndices<rank> &indices);
 
   /**
-   * Access to an element according
-   * to unrolled index. The
-   * function
-   * <tt>s.access_raw_entry(i)</tt>
-   * does the same as
-   * <tt>s[s.unrolled_to_component_indices(i)]</tt>,
-   * but more efficiently.
+   * Access to an element according to unrolled index. The function
+   * <tt>s.access_raw_entry(i)</tt> does the same as
+   * <tt>s[s.unrolled_to_component_indices(i)]</tt>, but more efficiently.
    */
   Number
   access_raw_entry (const unsigned int unrolled_index) const;
 
   /**
-   * Access to an element according
-   * to unrolled index. The
-   * function
-   * <tt>s.access_raw_entry(i)</tt>
-   * does the same as
-   * <tt>s[s.unrolled_to_component_indices(i)]</tt>,
-   * but more efficiently.
+   * Access to an element according to unrolled index. The function
+   * <tt>s.access_raw_entry(i)</tt> does the same as
+   * <tt>s[s.unrolled_to_component_indices(i)]</tt>, but more efficiently.
    */
   Number &
   access_raw_entry (const unsigned int unrolled_index);
 
   /**
-   * Return the Frobenius-norm of a tensor,
-   * i.e. the square root of the sum of
-   * squares of all entries. This norm is
-   * induced by the scalar product defined
-   * above for two symmetric tensors. Note
-   * that it includes <i>all</i> entries of
-   * the tensor, counting symmetry, not
-   * only the unique ones (for example, for
-   * rank-2 tensors, this norm includes
-   * adding up the squares of upper right
-   * as well as lower left entries, not
-   * just one of them, although they are
-   * equal for symmetric tensors).
+   * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+   * squares of all entries. This norm is induced by the scalar product
+   * defined above for two symmetric tensors. Note that it includes <i>all</i>
+   * entries of the tensor, counting symmetry, not only the unique ones (for
+   * example, for rank-2 tensors, this norm includes adding up the squares of
+   * upper right as well as lower left entries, not just one of them, although
+   * they are equal for symmetric tensors).
    */
   Number norm () const;
 
   /**
-   * Tensors can be unrolled by
-   * simply pasting all elements
-   * into one long vector, but for
-   * this an order of elements has
-   * to be defined. For symmetric
-   * tensors, this function returns
-   * which index within the range
-   * <code>[0,n_independent_components)</code>
-   * the given entry in a symmetric
+   * Tensors can be unrolled by simply pasting all elements into one long
+   * vector, but for this an order of elements has to be defined. For
+   * symmetric tensors, this function returns which index within the range
+   * <code>[0,n_independent_components)</code> the given entry in a symmetric
    * tensor has.
    */
   static
@@ -951,14 +732,9 @@ public:
   component_to_unrolled_index (const TableIndices<rank> &indices);
 
   /**
-   * The opposite of the previous
-   * function: given an index $i$
-   * in the unrolled form of the
-   * tensor, return what set of
-   * indices $(k,l)$ (for rank-2
-   * tensors) or $(k,l,m,n)$ (for
-   * rank-4 tensors) corresponds to
-   * it.
+   * The opposite of the previous function: given an index $i$ in the unrolled
+   * form of the tensor, return what set of indices $(k,l)$ (for rank-2
+   * tensors) or $(k,l,m,n)$ (for rank-4 tensors) corresponds to it.
    */
   static
   TableIndices<rank>
@@ -967,56 +743,45 @@ public:
   /**
    * Reset all values to zero.
    *
-   * Note that this is partly inconsistent
-   * with the semantics of the @p clear()
-   * member functions of the STL and of
-   * several other classes within deal.II
-   * which not only reset the values of
-   * stored elements to zero, but release
-   * all memory and return the object into
-   * a virginial state. However, since the
-   * size of objects of the present type is
-   * determined by its template parameters,
-   * resizing is not an option, and indeed
-   * the state where all elements have a
-   * zero value is the state right after
+   * Note that this is partly inconsistent with the semantics of the @p
+   * clear() member functions of the STL and of several other classes within
+   * deal.II which not only reset the values of stored elements to zero, but
+   * release all memory and return the object into a virginial state. However,
+   * since the size of objects of the present type is determined by its
+   * template parameters, resizing is not an option, and indeed the state
+   * where all elements have a zero value is the state right after
    * construction of such an object.
    */
   void clear ();
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
+   * Determine an estimate for the memory consumption (in bytes) of this
    * object.
    */
   static std::size_t memory_consumption ();
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
 
 private:
   /**
-   * A structure that describes
-   * properties of the base tensor.
+   * A structure that describes properties of the base tensor.
    */
   typedef
   internal::SymmetricTensorAccessors::StorageType<rank,dim,Number>
   base_tensor_descriptor;
 
   /**
-   * Data storage type for a
-   * symmetric tensor.
+   * Data storage type for a symmetric tensor.
    */
   typedef typename base_tensor_descriptor::base_tensor_type base_tensor_type;
 
   /**
-   * The place where we store the
-   * data of the tensor.
+   * The place where we store the data of the tensor.
    */
   base_tensor_type data;
 
@@ -2282,8 +2047,8 @@ SymmetricTensor<rank,dim,Number>::serialize(Archive &ar, const unsigned int)
 /* ----------------- Non-member functions operating on tensors. ------------ */
 
 /**
- * Compute the determinant of a tensor or rank 2. The determinant is
- * also commonly referred to as the third invariant of rank-2 tensors.
+ * Compute the determinant of a tensor or rank 2. The determinant is also
+ * commonly referred to as the third invariant of rank-2 tensors.
  *
  * For a one-dimensional tensor, the determinant equals the only element and
  * is therefore equivalent to the trace.
@@ -2340,9 +2105,8 @@ double third_invariant (const SymmetricTensor<2,dim,Number> &t)
 
 
 /**
- * Compute and return the trace of a tensor of rank 2, i.e. the sum of
- * its diagonal entries. The trace is the first invariant of a rank-2
- * tensor.
+ * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
+ * diagonal entries. The trace is the first invariant of a rank-2 tensor.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2358,9 +2122,9 @@ Number trace (const SymmetricTensor<2,dim,Number> &d)
 
 
 /**
- * Compute the trace of a tensor or rank 2. This function therefore
- * computes the same value as the <tt>trace()</tt> functions and is only
- * provided for greater notational simplicity (since there are also functions
+ * Compute the trace of a tensor or rank 2. This function therefore computes
+ * the same value as the <tt>trace()</tt> functions and is only provided for
+ * greater notational simplicity (since there are also functions
  * <tt>second_invariant</tt> and <tt>third_invariant</tt>).
  *
  * @relates SymmetricTensor
@@ -2470,8 +2234,8 @@ deviator (const SymmetricTensor<2,dim,Number> &t)
 
 
 /**
- * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim
- * identity matrix.
+ * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim identity
+ * matrix.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2505,9 +2269,9 @@ unit_symmetric_tensor ()
 
 
 /**
- * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim
- * identity matrix. This specialization of the function uses
- * <code>double</code> as the data type for the elements.
+ * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim identity
+ * matrix. This specialization of the function uses <code>double</code> as the
+ * data type for the elements.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2524,8 +2288,8 @@ unit_symmetric_tensor ()
 
 /**
  * Return the tensor of rank 4 that, when multiplied by a symmetric rank 2
- * tensor <tt>t</tt> returns the deviator $\textrm{dev}\ t$. It is the operator
- * representation of the linear deviator operator.
+ * tensor <tt>t</tt> returns the deviator $\textrm{dev}\ t$. It is the
+ * operator representation of the linear deviator operator.
  *
  * For every tensor <tt>t</tt>, there holds the identity
  * <tt>deviator(t)==deviator_tensor&lt;dim&gt;()*t</tt>, up to numerical
@@ -2595,14 +2359,14 @@ deviator_tensor ()
  * form, and in particular does not only consist of zeros and ones. For
  * example, for <tt>dim=2</tt>, the identity tensor has all zero entries
  * except for <tt>id[0][0][0][0]=id[1][1][1][1]=1</tt> and
- * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>. To
- * see why this factor of 1/2 is necessary, consider computing <tt>A=Id
- * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
+ * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>.
+ * To see why this factor of 1/2 is necessary, consider computing <tt>A=Id :
+ * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
  * id_0111 b_11 + id_0101 b_01 + id_0110 b_10</tt>. On the other hand, we need
  * to have <tt>a_01=b_01</tt>, and symmetry implies <tt>b_01=b_10</tt>,
  * leading to <tt>a_01=(id_0101+id_0110) b_01</tt>, or, again by symmetry,
- * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the
- * three-dimensional case.
+ * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the three-
+ * dimensional case.
  *
  * This issue is also explained in the introduction to step-44.
  *
@@ -2644,14 +2408,14 @@ identity_tensor ()
  * form, and in particular does not only consist of zeros and ones. For
  * example, for <tt>dim=2</tt>, the identity tensor has all zero entries
  * except for <tt>id[0][0][0][0]=id[1][1][1][1]=1</tt> and
- * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>. To
- * see why this factor of 1/2 is necessary, consider computing <tt>A=Id
- * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
+ * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>.
+ * To see why this factor of 1/2 is necessary, consider computing <tt>A=Id .
+ * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
  * id_0111 b_11 + id_0101 b_01 + id_0110 b_10</tt>. On the other hand, we need
  * to have <tt>a_01=b_01</tt>, and symmetry implies <tt>b_01=b_10</tt>,
  * leading to <tt>a_01=(id_0101+id_0110) b_01</tt>, or, again by symmetry,
- * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the
- * three-dimensional case.
+ * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the three-
+ * dimensional case.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2668,9 +2432,9 @@ identity_tensor ()
 
 /**
  * Invert a symmetric rank-4 tensor. Since symmetric rank-4 tensors are
- * mappings from and to symmetric rank-2 tensors, they can have an
- * inverse. This function computes it, if it exists, for the case that the
- * dimension equals either 1 or 2.
+ * mappings from and to symmetric rank-2 tensors, they can have an inverse.
+ * This function computes it, if it exists, for the case that the dimension
+ * equals either 1 or 2.
  *
  * If a tensor is not invertible, then the result is unspecified, but will
  * likely contain the results of a division by zero or a very small number at
@@ -2763,9 +2527,9 @@ invert (const SymmetricTensor<4,dim,Number> &t)
 
 /**
  * Invert a symmetric rank-4 tensor. Since symmetric rank-4 tensors are
- * mappings from and to symmetric rank-2 tensors, they can have an
- * inverse. This function computes it, if it exists, for the case that the
- * dimension equals 3.
+ * mappings from and to symmetric rank-2 tensors, they can have an inverse.
+ * This function computes it, if it exists, for the case that the dimension
+ * equals 3.
  *
  * If a tensor is not invertible, then the result is unspecified, but will
  * likely contain the results of a division by zero or a very small number at
@@ -2783,14 +2547,14 @@ invert (const SymmetricTensor<4,3,double> &t);
 
 /**
  * Return the tensor of rank 4 that is the outer product of the two tensors
- * given as arguments, i.e. the result $T=t1 \otimes t2$ satisfies
- * <tt>T phi = t1 (t2 : phi)</tt> for all symmetric tensors <tt>phi</tt>.
+ * given as arguments, i.e. the result $T=t1 \otimes t2$ satisfies <tt>T phi =
+ * t1 (t2 : phi)</tt> for all symmetric tensors <tt>phi</tt>.
  *
  * For example, the deviator tensor can be computed as
  * <tt>identity_tensor<dim,Number>() -
  * 1/d*outer_product(unit_symmetric_tensor<dim,Number>(),
- * unit_symmetric_tensor<dim,Number>())</tt>, since the (double) contraction with the
- * unit tensor yields the trace of a symmetric tensor.
+ * unit_symmetric_tensor<dim,Number>())</tt>, since the (double) contraction
+ * with the unit tensor yields the trace of a symmetric tensor.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2816,9 +2580,9 @@ outer_product (const SymmetricTensor<2,dim,Number> &t1,
 
 
 /**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==1.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==1.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2836,9 +2600,9 @@ symmetrize (const Tensor<2,1,Number> &t)
 
 
 /**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==2.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==2.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2856,9 +2620,9 @@ symmetrize (const Tensor<2,2,Number> &t)
 
 
 /**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==3.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==3.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -2880,8 +2644,8 @@ symmetrize (const Tensor<2,3,Number> &t)
 
 
 /**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the right.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * right.
  *
  * @relates SymmetricTensor
  */
@@ -2899,8 +2663,8 @@ operator * (const SymmetricTensor<rank,dim,Number> &t,
 
 
 /**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the left.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * left.
  *
  * @relates SymmetricTensor
  */
@@ -2936,8 +2700,8 @@ operator / (const SymmetricTensor<rank,dim,Number> &t,
 
 
 /**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the right.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * right.
  *
  * @relates SymmetricTensor
  */
@@ -2955,8 +2719,8 @@ operator * (const SymmetricTensor<rank,dim> &t,
 
 
 /**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the left.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * left.
  *
  * @relates SymmetricTensor
  */
@@ -2993,8 +2757,8 @@ operator / (const SymmetricTensor<rank,dim> &t,
  * Compute the scalar product $a:b=\sum_{i,j} a_{ij}b_{ij}$ between two
  * tensors $a,b$ of rank 2. In the current case where both arguments are
  * symmetric tensors, this is equivalent to calling the expression
- * <code>t1*t2</code> which uses the overloaded <code>operator*</code>
- * between two symmetric tensors of rank 2.
+ * <code>t1*t2</code> which uses the overloaded <code>operator*</code> between
+ * two symmetric tensors of rank 2.
  *
  * @relates SymmetricTensor
  */
@@ -3015,8 +2779,7 @@ scalar_product (const SymmetricTensor<2,dim,Number> &t1,
  * the contraction over the last index of the first tensor and the first index
  * of the second tensor, for example $(a\cdot b)_{ij}=\sum_k a_{ik}b_{kj}$.
  *
- * @relates Tensor
- * @relates SymmetricTensor
+ * @relates Tensor @relates SymmetricTensor
  */
 template <int dim, typename Number>
 inline
@@ -3039,8 +2802,7 @@ scalar_product (const SymmetricTensor<2,dim,Number> &t1,
  * the contraction over the last index of the first tensor and the first index
  * of the second tensor, for example $(a\cdot b)_{ij}=\sum_k a_{ik}b_{kj}$.
  *
- * @relates Tensor
- * @relates SymmetricTensor
+ * @relates Tensor @relates SymmetricTensor
  */
 template <int dim, typename Number>
 inline
@@ -3054,15 +2816,15 @@ scalar_product (const Tensor<2,dim,Number> &t1,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3081,15 +2843,15 @@ double_contract (SymmetricTensor<2,1,Number> &tmp,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3108,15 +2870,15 @@ double_contract (SymmetricTensor<2,1,Number> &tmp,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor @author Wolfgang Bangerth, 2005
  */
@@ -3140,15 +2902,15 @@ double_contract (SymmetricTensor<2,2,Number> &tmp,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3173,15 +2935,15 @@ double_contract (SymmetricTensor<2,2,Number> &tmp,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3209,15 +2971,15 @@ double_contract (SymmetricTensor<2,3,Number> &tmp,
 
 /**
  * Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
  *
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
  *
  * @related SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3244,17 +3006,16 @@ double_contract (SymmetricTensor<2,3,Number> &tmp,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
index 8c1f71b306af2d59f95c3dd7702c360005639795..348ca61aa8baaf9785b502bea09fa2730d1d8a75 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * A class that represents a set of
- * iterators each of which are
- * incremented by one at the same
- * time. This is typically used in calls
- * like <code>std::transform(a.begin(),
- * a.end(), b.begin(), functor);</code>
- * where we have synchronous iterators
- * marching through the containers
- * <code>a,b</code>. If an object of this
- * type represents the end of a range,
- * only the first element is considered
- * (we only have <code>a.end()</code>,
+ * A class that represents a set of iterators each of which are incremented by
+ * one at the same time. This is typically used in calls like
+ * <code>std::transform(a.begin(), a.end(), b.begin(), functor);</code> where
+ * we have synchronous iterators marching through the containers
+ * <code>a,b</code>. If an object of this type represents the end of a range,
+ * only the first element is considered (we only have <code>a.end()</code>,
  * not <code>b.end()</code>)
  *
- * The template argument of the current
- * class shall be of type
- * <code>std_cxx11::tuple</code> with
- * arguments equal to the iterator types.
+ * The template argument of the current class shall be of type
+ * <code>std_cxx11::tuple</code> with arguments equal to the iterator types.
  *
- * This type, and the helper functions
- * associated with it, are used as the
- * Value concept for the blocked_range
- * type of the Threading Building Blocks.
+ * This type, and the helper functions associated with it, are used as the
+ * Value concept for the blocked_range type of the Threading Building Blocks.
  *
  * @author Wolfgang Bangerth, 2008
  */
@@ -67,8 +57,7 @@ struct SynchronousIterators
   SynchronousIterators (const SynchronousIterators &i);
 
   /**
-   * Storage for the iterators
-   * represented by the current class.
+   * Storage for the iterators represented by the current class.
    */
   Iterators iterators;
 };
@@ -95,12 +84,9 @@ SynchronousIterators (const SynchronousIterators &i)
 
 
 /**
- * Return whether the first element of
- * the first argument is less than the
- * first element of the second
- * argument. Since the objects compared
- * march forward all elements at the same
- * time, comparing the first element is
+ * Return whether the first element of the first argument is less than the
+ * first element of the second argument. Since the objects compared march
+ * forward all elements at the same time, comparing the first element is
  * sufficient.
  */
 template <typename Iterators>
@@ -115,12 +101,9 @@ operator< (const SynchronousIterators<Iterators> &a,
 
 
 /**
- * Return the distance between the first
- * and the second argument. Since the
- * objects compared march forward all
- * elements at the same time,
- * differencing the first element is
- * sufficient.
+ * Return the distance between the first and the second argument. Since the
+ * objects compared march forward all elements at the same time, differencing
+ * the first element is sufficient.
  */
 template <typename Iterators>
 inline
@@ -218,8 +201,7 @@ void advance_by_one (std_cxx11::tuple<I1,I2,I3,I4> &t)
 
 
 /**
- * Advance the elements of this iterator
- * by $n$.
+ * Advance the elements of this iterator by $n$.
  */
 template <typename Iterators>
 inline
@@ -233,8 +215,7 @@ operator + (const SynchronousIterators<Iterators> &a,
 }
 
 /**
- * Advance the elements of this iterator
- * by 1.
+ * Advance the elements of this iterator by 1.
  */
 template <typename Iterators>
 inline
@@ -247,10 +228,8 @@ operator ++ (SynchronousIterators<Iterators> &a)
 
 
 /**
- * Compare synch iterators for
- * inequality. Since they march in synch,
- * comparing only the first element is
- * sufficient.
+ * Compare synch iterators for inequality. Since they march in synch,
+ * comparing only the first element is sufficient.
  */
 template <typename Iterators>
 inline
index 31e31972db5d227f488824763e3e55dfb27e325a..d877ee9e1bf8d02ff6b6b2186f7c7f8b59721183 100644 (file)
@@ -44,41 +44,37 @@ namespace internal
 {
 
   /**
-   * @internal
-   * Have a namespace in which we declare some classes that are used to
-   * access the elements of tables using the <tt>operator[]</tt>. These are
-   * quite technical, since they have to do their work recursively (due
-   * to the fact that the number of indices is not known, we have to
-   * return an iterator into the next lower dimension object if we
-   * access one object, until we are on the lowest level and can
-   * actually return a reference to the stored data type itself).  This
-   * is so technical that you will not usually want to look at these
-   * classes at all, except possibly for educational reasons.  None of
-   * the classes herein has a interface that you should use explicitly
-   * in your programs (except, of course, through access to the elements
-   * of tables with <tt>operator[]</tt>, which generates temporary objects of
-   * the types of this namespace).
+   * @internal Have a namespace in which we declare some classes that are used
+   * to access the elements of tables using the <tt>operator[]</tt>. These are
+   * quite technical, since they have to do their work recursively (due to the
+   * fact that the number of indices is not known, we have to return an
+   * iterator into the next lower dimension object if we access one object,
+   * until we are on the lowest level and can actually return a reference to
+   * the stored data type itself).  This is so technical that you will not
+   * usually want to look at these classes at all, except possibly for
+   * educational reasons.  None of the classes herein has a interface that you
+   * should use explicitly in your programs (except, of course, through access
+   * to the elements of tables with <tt>operator[]</tt>, which generates
+   * temporary objects of the types of this namespace).
    *
    * @author Wolfgang Bangerth, 2002
    */
   namespace TableBaseAccessors
   {
     /**
-     * @internal
-     * Have a class which declares some nested typedefs, depending on its
-     * template parameters. The general template declares nothing, but
+     * @internal Have a class which declares some nested typedefs, depending
+     * on its template parameters. The general template declares nothing, but
      * there are more useful specializations regaring the last parameter
-     * indicating constness of the table for which accessor objects are to
-     * be generated in this namespace.
+     * indicating constness of the table for which accessor objects are to be
+     * generated in this namespace.
      */
     template <int N, typename T, bool Constness>
     struct Types
     {};
 
     /**
-     * @internal
-     * Have a class which declares some nested typedefs, depending on its
-     * template parameters. Specialization for accessors to constant
+     * @internal Have a class which declares some nested typedefs, depending
+     * on its template parameters. Specialization for accessors to constant
      * objects.
      */
     template <int N, typename T> struct Types<N,T,true>
@@ -94,10 +90,9 @@ namespace internal
     };
 
     /**
-     * @internal
-     * Have a class which declares some nested typedefs, depending on its
-     * template parameters. Specialization for accessors to non-constant
-     * objects.
+     * @internal Have a class which declares some nested typedefs, depending
+     * on its template parameters. Specialization for accessors to non-
+     * constant objects.
      */
     template <int N, typename T> struct Types<N,T,false>
     {
@@ -113,41 +108,40 @@ namespace internal
 
 
     /**
-     * @internal
-     * Class that acts as accessor to subobjects of tables of type
-     * <tt>Table<N,T></tt>. The template parameter <tt>C</tt> may be either true or
-     * false, and indicates whether the objects worked on are constant or
-     * not (i.e. write access is only allowed if the value is false).
+     * @internal Class that acts as accessor to subobjects of tables of type
+     * <tt>Table<N,T></tt>. The template parameter <tt>C</tt> may be either
+     * true or false, and indicates whether the objects worked on are constant
+     * or not (i.e. write access is only allowed if the value is false).
      *
-     * Since with <tt>N</tt> indices, the effect of applying <tt>operator[]</tt> is
-     * getting access to something we <tt>N-1</tt> indices, we have to
-     * implement these accessor classes recursively, with stopping when we
-     * have only one index left. For the latter case, a specialization of
-     * this class is declared below, where calling <tt>operator[]</tt> gives
-     * you access to the objects actually stored by the table. In the
-     * value given to the index operator needs to be checked whether it is
-     * inside its bounds, for which we need to know which index of the
-     * table we are actually accessing presently. This is done through the
-     * template parameter <tt>P</tt>: it indicates, how many remaining indices
-     * there are. For a vector, <tt>P</tt> may only be one (and then the
-     * specialization below is used). For a table this value may be two,
-     * and when using <tt>operator[]</tt>, an object with <tt>P=1</tt> emerges.
+     * Since with <tt>N</tt> indices, the effect of applying
+     * <tt>operator[]</tt> is getting access to something we <tt>N-1</tt>
+     * indices, we have to implement these accessor classes recursively, with
+     * stopping when we have only one index left. For the latter case, a
+     * specialization of this class is declared below, where calling
+     * <tt>operator[]</tt> gives you access to the objects actually stored by
+     * the table. In the value given to the index operator needs to be checked
+     * whether it is inside its bounds, for which we need to know which index
+     * of the table we are actually accessing presently. This is done through
+     * the template parameter <tt>P</tt>: it indicates, how many remaining
+     * indices there are. For a vector, <tt>P</tt> may only be one (and then
+     * the specialization below is used). For a table this value may be two,
+     * and when using <tt>operator[]</tt>, an object with <tt>P=1</tt>
+     * emerges.
      *
      * The value of <tt>P</tt> is also used to determine the stride: this
      * object stores a pointer indicating the beginning of the range of
      * objects that it may access. When we apply <tt>operator[]</tt> on this
-     * object, the resulting new accessor may only access a subset of
-     * these elements, and to know which subset we need to know the
-     * dimensions of the table and the present index, which is indicated
-     * by <tt>P</tt>.
+     * object, the resulting new accessor may only access a subset of these
+     * elements, and to know which subset we need to know the dimensions of
+     * the table and the present index, which is indicated by <tt>P</tt>.
      *
      * As stated for the entire namespace, you will not usually have to do
-     * with these classes directly, and should not try to use their
-     * interface directly as it may change without notice. In fact, since
-     * the constructors are made private, you will not even be able to
-     * generate objects of this class, as they are only thought as
-     * temporaries for access to elements of the table class, not for
-     * passing them around as arguments of functions, etc.
+     * with these classes directly, and should not try to use their interface
+     * directly as it may change without notice. In fact, since the
+     * constructors are made private, you will not even be able to generate
+     * objects of this class, as they are only thought as temporaries for
+     * access to elements of the table class, not for passing them around as
+     * arguments of functions, etc.
      *
      * @author Wolfgang Bangerth, 2002
      */
@@ -162,51 +156,37 @@ namespace internal
 
     private:
       /**
-       * Constructor. Take a pointer
-       * to the table object to know
-       * about the sizes of the
-       * various dimensions, and a
-       * pointer to the subset of
-       * data we may access.
+       * Constructor. Take a pointer to the table object to know about the
+       * sizes of the various dimensions, and a pointer to the subset of data
+       * we may access.
        */
       Accessor (const TableType &table,
                 const iterator    data);
 
       /**
-       * Default constructor. Not
-       * needed, and invisible, so
-       * private.
+       * Default constructor. Not needed, and invisible, so private.
        */
       Accessor ();
 
     public:
 
       /**
-       * Copy constructor. This constructor
-       * is public so that one can pass
-       * sub-tables to functions as
-       * arguments, as in
-       * <code>f(table[i])</code>.
+       * Copy constructor. This constructor is public so that one can pass
+       * sub-tables to functions as arguments, as in <code>f(table[i])</code>.
        *
-       * Using this constructor is risky if
-       * accessors are stored longer than
-       * the table it points to. Don't do
-       * this.
+       * Using this constructor is risky if accessors are stored longer than
+       * the table it points to. Don't do this.
        */
       Accessor (const Accessor &a);
 
       /**
-       * Index operator. Performs a
-       * range check.
+       * Index operator. Performs a range check.
        */
       Accessor<N,T,C,P-1> operator [] (const unsigned int i) const;
 
       /**
-       * Exception for range
-       * check. Do not use global
-       * exception since this way we
-       * can output which index is
-       * the wrong one.
+       * Exception for range check. Do not use global exception since this way
+       * we can output which index is the wrong one.
        */
       DeclException3 (ExcIndexRange, int, int, int,
                       << "Index " << N-P+1 << "has a value of "
@@ -214,12 +194,9 @@ namespace internal
                       << arg2 << "," << arg3 << "[");
     private:
       /**
-       * Store the data given to the
-       * constructor. There are no
-       * non-const member functions
-       * of this class, so there is
-       * no reason not to make these
-       * elements constant.
+       * Store the data given to the constructor. There are no non-const
+       * member functions of this class, so there is no reason not to make
+       * these elements constant.
        */
       const TableType &table;
       const iterator   data;
@@ -240,12 +217,11 @@ namespace internal
 
 
     /**
-     * @internal
-     * Accessor class for tables. This is the specialization for the last
-     * index, which actually allows access to the elements of the table,
-     * rather than recursively returning access objects for further
-     * subsets. The same holds for this specialization as for the general
-     * template; see there for more information.
+     * @internal Accessor class for tables. This is the specialization for the
+     * last index, which actually allows access to the elements of the table,
+     * rather than recursively returning access objects for further subsets.
+     * The same holds for this specialization as for the general template; see
+     * there for more information.
      *
      * @author Wolfgang Bangerth, 2002
      */
@@ -254,13 +230,9 @@ namespace internal
     {
     public:
       /**
-       * Typedef constant and
-       * non-constant iterator
-       * types to the elements of
-       * this row, as well as all
-       * the other types usually
-       * required for the standard
-       * library algorithms.
+       * Typedef constant and non-constant iterator types to the elements of
+       * this row, as well as all the other types usually required for the
+       * standard library algorithms.
        */
       typedef typename Types<N,T,C>::value_type value_type;
 
@@ -274,98 +246,68 @@ namespace internal
       typedef ptrdiff_t difference_type;
 
       /**
-       * Import a typedef from the
-       * switch class above.
+       * Import a typedef from the switch class above.
        */
       typedef typename Types<N,T,C>::TableType    TableType;
 
     private:
 
       /**
-       * Constructor. Take an iterator
-       * to the table object to know
-       * about the sizes of the
-       * various dimensions, and a
-       * iterator to the subset of
-       * data we may access (which in
-       * this particular case is only
-       * one row).
+       * Constructor. Take an iterator to the table object to know about the
+       * sizes of the various dimensions, and a iterator to the subset of data
+       * we may access (which in this particular case is only one row).
        *
-       * The constructor is made
-       * private in order to prevent
-       * you having such objects
-       * around. The only way to
-       * create such objects is via
-       * the <tt>Table</tt> class, which
-       * only generates them as
-       * temporary objects. This
-       * guarantees that the accessor
-       * objects go out of scope
-       * earlier than the mother
-       * object, avoid problems with
-       * data consistency.
+       * The constructor is made private in order to prevent you having such
+       * objects around. The only way to create such objects is via the
+       * <tt>Table</tt> class, which only generates them as temporary objects.
+       * This guarantees that the accessor objects go out of scope earlier
+       * than the mother object, avoid problems with data consistency.
        */
       Accessor (const TableType &table,
                 const iterator    data);
 
       /**
-       * Default constructor. Not needed,
-       * so private.
+       * Default constructor. Not needed, so private.
        */
       Accessor ();
 
     public:
       /**
-       * Copy constructor. This constructor
-       * is public so that one can pass
-       * sub-tables to functions as
-       * arguments, as in
-       * <code>f(table[i])</code>.
+       * Copy constructor. This constructor is public so that one can pass
+       * sub-tables to functions as arguments, as in <code>f(table[i])</code>.
        *
-       * Using this constructor is risky if
-       * accessors are stored longer than
-       * the table it points to. Don't do
-       * this.
+       * Using this constructor is risky if accessors are stored longer than
+       * the table it points to. Don't do this.
        */
       Accessor (const Accessor &a);
 
 
       /**
-       * Index operator. Performs a
-       * range check.
+       * Index operator. Performs a range check.
        */
       reference operator [] (const unsigned int) const;
 
       /**
-       * Return the length of one row,
-       * i.e. the number of elements
-       * corresponding to the last
-       * index of the table object.
+       * Return the length of one row, i.e. the number of elements
+       * corresponding to the last index of the table object.
        */
       unsigned int size () const;
 
       /**
-       * Return an iterator to the
-       * first element of this
-       * row.
+       * Return an iterator to the first element of this row.
        */
       iterator begin () const;
 
       /**
-       * Return an interator to the
-       * element past the end of
-       * this row.
+       * Return an interator to the element past the end of this row.
        */
       iterator end () const;
 
     private:
       /**
-       * Store the data given to the
-       * constructor. There are no
-       * non-const member functions
-       * of this class, so there is
-       * no reason not to make these
-       * elements constant.
+       * Store the data given to the constructor. There are no non-const
+       * member functions of this class, so there is no reason not to make
+       * these elements constant.
        */
       const TableType &table;
       const iterator   data;
@@ -390,75 +332,67 @@ namespace internal
 
 
 /**
- * General class holding an array of objects of templated type in
- * multiple dimensions. If the template parameter indicating the
- * number of dimensions is one, then this is more or less a vector, if
- * it is two then it is a matrix, and so on.
+ * General class holding an array of objects of templated type in multiple
+ * dimensions. If the template parameter indicating the number of dimensions
+ * is one, then this is more or less a vector, if it is two then it is a
+ * matrix, and so on.
  *
- * Previously, this data type was emulated in this library by
- * constructs like <tt>std::vector<std::vector<T>></tt>, or even higher
- * nested constructs.  However, this has the disadvantage that it is
- * hard to initialize, and most importantly that it is very
- * inefficient if all rows have the same size (which is the usual
- * case), since then the memory for each row is allocated
+ * Previously, this data type was emulated in this library by constructs like
+ * <tt>std::vector<std::vector<T>></tt>, or even higher nested constructs.
+ * However, this has the disadvantage that it is hard to initialize, and most
+ * importantly that it is very inefficient if all rows have the same size
+ * (which is the usual case), since then the memory for each row is allocated
  * independently, both wasting time and memory. This can be made more
- * efficient by allocating only one chunk of memory for the entire
- * object.
+ * efficient by allocating only one chunk of memory for the entire object.
  *
- * Therefore, this data type was invented. Its implementation is
- * rather straightforward, with two exceptions. The first thing to
- * think about is how to pass the size in each of the coordinate
- * directions to the object; this is done using the TableIndices
- * class. Second, how to access the individual elements. The basic
- * problem here is that we would like to make the number of arguments
- * to be passed to the constructor as well as the access functions
- * dependent on the template parameter <tt>N</tt> indicating the number of
- * dimensions. Of course, this is not possible.
+ * Therefore, this data type was invented. Its implementation is rather
+ * straightforward, with two exceptions. The first thing to think about is how
+ * to pass the size in each of the coordinate directions to the object; this
+ * is done using the TableIndices class. Second, how to access the individual
+ * elements. The basic problem here is that we would like to make the number
+ * of arguments to be passed to the constructor as well as the access
+ * functions dependent on the template parameter <tt>N</tt> indicating the
+ * number of dimensions. Of course, this is not possible.
  *
- * The way out of the first problem (and partly the second one as
- * well) is to have a common base class TableBase and a derived class
- * for each value of <tt>N</tt>.  This derived class has a constructor
- * with the correct number of arguments, namely <tt>N</tt>. These then
- * transform their arguments into the data type the base class (this
- * class in fact) uses in the constructor as well as in
- * element access through operator() functions.
+ * The way out of the first problem (and partly the second one as well) is to
+ * have a common base class TableBase and a derived class for each value of
+ * <tt>N</tt>.  This derived class has a constructor with the correct number
+ * of arguments, namely <tt>N</tt>. These then transform their arguments into
+ * the data type the base class (this class in fact) uses in the constructor
+ * as well as in element access through operator() functions.
  *
- * The second problem is that we would like to allow access through a
- * sequence of <tt>operator[]</tt> calls. This mostly because, as said,
- * this class is a replacement for previous use of nested
- * <tt>std::vector</tt> objects, where we had to use the <tt>operator[]</tt>
- * access function recursively until we were at the innermost
- * object. Emulating this behavior without losing the ability to do
- * index checks, and in particular without losing performance is
- * possible but nontrivial, and done in the TableBaseAccessors
- * namespace.
+ * The second problem is that we would like to allow access through a sequence
+ * of <tt>operator[]</tt> calls. This mostly because, as said, this class is a
+ * replacement for previous use of nested <tt>std::vector</tt> objects, where
+ * we had to use the <tt>operator[]</tt> access function recursively until we
+ * were at the innermost object. Emulating this behavior without losing the
+ * ability to do index checks, and in particular without losing performance is
+ * possible but nontrivial, and done in the TableBaseAccessors namespace.
  *
  *
  * <h3>Comparison with the Tensor class</h3>
  *
- * In some way, this class is similar to the Tensor class, in
- * that it templatizes on the number of dimensions. However, there are
- * two major differences. The first is that the Tensor class
- * stores only numeric values (as <tt>double</tt>s), while the Table
- * class stores arbitrary objects. The second is that the Tensor
- * class has fixed dimensions, also given as a template argument, while
- * this class can handle arbitrary dimensions, which may also be
- * different between different indices.
+ * In some way, this class is similar to the Tensor class, in that it
+ * templatizes on the number of dimensions. However, there are two major
+ * differences. The first is that the Tensor class stores only numeric values
+ * (as <tt>double</tt>s), while the Table class stores arbitrary objects. The
+ * second is that the Tensor class has fixed dimensions, also given as a
+ * template argument, while this class can handle arbitrary dimensions, which
+ * may also be different between different indices.
  *
- * This has two consequences. First, since the size is not known at
- * compile time, it has to do explicit memory allocating. Second, the
- * layout of individual elements is not known at compile time, so
- * access is slower than for the Tensor class where the number
- * of elements are their location is known at compile time and the
- * compiler can optimize with this knowledge (for example when
- * unrolling loops). On the other hand, this class is of course more
- * flexible, for example when you want a two-dimensional table with
- * the number of rows equal to the number of degrees of freedom on a
- * cell, and the number of columns equal to the number of quadrature
- * points. Both numbers may only be known at run-time, so a flexible
- * table is needed here. Furthermore, you may want to store, say, the
- * gradients of shape functions, so the data type is not a single
- * scalar value, but a tensor itself.
+ * This has two consequences. First, since the size is not known at compile
+ * time, it has to do explicit memory allocating. Second, the layout of
+ * individual elements is not known at compile time, so access is slower than
+ * for the Tensor class where the number of elements are their location is
+ * known at compile time and the compiler can optimize with this knowledge
+ * (for example when unrolling loops). On the other hand, this class is of
+ * course more flexible, for example when you want a two-dimensional table
+ * with the number of rows equal to the number of degrees of freedom on a
+ * cell, and the number of columns equal to the number of quadrature points.
+ * Both numbers may only be known at run-time, so a flexible table is needed
+ * here. Furthermore, you may want to store, say, the gradients of shape
+ * functions, so the data type is not a single scalar value, but a tensor
+ * itself.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002.
@@ -468,25 +402,20 @@ class TableBase : public Subscriptor
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   TableBase ();
 
   /**
-   * Constructor. Initialize the
-   * array with the given
-   * dimensions in each index
+   * Constructor. Initialize the array with the given dimensions in each index
    * component.
    */
   TableBase (const TableIndices<N> &sizes);
 
   /**
-   * Constructor. Initialize the
-   * array with the given
-   * dimensions in each index
-   * component, and then initialize the elements of the table using the
-   * second and third argument by calling fill(entries,C_style_indexing).
+   * Constructor. Initialize the array with the given dimensions in each index
+   * component, and then initialize the elements of the table using the second
+   * and third argument by calling fill(entries,C_style_indexing).
    */
   template <typename InputIterator>
   TableBase (const TableIndices<N> &sizes,
@@ -494,15 +423,13 @@ public:
              const bool      C_style_indexing = true);
 
   /**
-   * Copy constructor. Performs a
-   * deep copy.
+   * Copy constructor. Performs a deep copy.
    */
   TableBase (const TableBase<N,T> &src);
 
   /**
-   * Copy constructor. Performs a
-   * deep copy from a table object
-   * storing some other data type.
+   * Copy constructor. Performs a deep copy from a table object storing some
+   * other data type.
    */
   template <typename T2>
   TableBase (const TableBase<N,T2> &src);
@@ -513,156 +440,124 @@ public:
   ~TableBase ();
 
   /**
-   * Assignment operator.
-   * Copy all elements of <tt>src</tt>
-   * into the matrix. The size is
-   * adjusted if needed.
+   * Assignment operator. Copy all elements of <tt>src</tt> into the matrix.
+   * The size is adjusted if needed.
    *
-   * We can't use the other, templatized
-   * version since if we don't declare
-   * this one, the compiler will happily
-   * generate a predefined copy
-   * operator which is not what we want.
+   * We can't use the other, templatized version since if we don't declare
+   * this one, the compiler will happily generate a predefined copy operator
+   * which is not what we want.
    */
   TableBase<N,T> &operator = (const TableBase<N,T> &src);
 
   /**
-   * Copy operator.
-   * Copy all elements of <tt>src</tt>
-   * into the array. The size is
-   * adjusted if needed.
+   * Copy operator. Copy all elements of <tt>src</tt> into the array. The size
+   * is adjusted if needed.
    *
-   * This function requires that the
-   * type <tt>T2</tt> is convertible to
+   * This function requires that the type <tt>T2</tt> is convertible to
    * <tt>T</tt>.
    */
   template<typename T2>
   TableBase<N,T> &operator = (const TableBase<N,T2> &src);
 
   /**
-   *  Test for equality of two tables.
+   * Test for equality of two tables.
    */
   bool operator == (const TableBase<N,T> &T2)  const;
 
   /**
-   * Set all entries to their
-   * default value (i.e. copy them
-   * over with default constructed
-   * objects). Do not change the
-   * size of the table, though.
+   * Set all entries to their default value (i.e. copy them over with default
+   * constructed objects). Do not change the size of the table, though.
    */
   void reset_values ();
 
   /**
-   * Set the dimensions of this object to
-   * the sizes given in the argument, and
-   * newly allocate the required
-   * memory. If <tt>fast</tt> is set to
-   * <tt>false</tt>, previous content is
-   * deleted, otherwise the memory is not
+   * Set the dimensions of this object to the sizes given in the argument, and
+   * newly allocate the required memory. If <tt>fast</tt> is set to
+   * <tt>false</tt>, previous content is deleted, otherwise the memory is not
    * touched.
    */
   void reinit (const TableIndices<N> &new_size,
                const bool             fast = false);
 
   /**
-   * Size of the table in direction
-   * <tt>i</tt>.
+   * Size of the table in direction <tt>i</tt>.
    */
   unsigned int size (const unsigned int i) const;
 
   /**
-   * Return the sizes of this
-   * object in each direction.
+   * Return the sizes of this object in each direction.
    */
   const TableIndices<N> &size () const;
 
   /**
-   * Return the number of elements
-   * stored in this object, which
-   * is the product of the
-   * extensions in each dimension.
+   * Return the number of elements stored in this object, which is the product
+   * of the extensions in each dimension.
    */
   unsigned int n_elements () const;
 
   /**
-   * Return whether the object is
-   * empty, i.e. one of the
-   * directions is zero. This is
-   * equivalent to
-   * <tt>n_elements()==0</tt>.
+   * Return whether the object is empty, i.e. one of the directions is zero.
+   * This is equivalent to <tt>n_elements()==0</tt>.
    */
   bool empty () const;
 
   /**
-   * Fill this table (which is assumed to already have the correct
-   * size) from a source given by dereferencing the given forward
-   * iterator (which could, for example, be a pointer to the first
-   * element of an array, or an inserting std::istream_iterator). The
-   * second argument denotes whether the elements pointed to are
-   * arranged in a way that corresponds to the last index running
-   * fastest or slowest. The default is to use C-style indexing
-   * where the last index runs fastest (as opposed to Fortran-style
-   * where the first index runs fastest when traversing multidimensional
-   * arrays. For example, if you try to fill an object of type
-   * Table<2,T>, then calling this function with the default
-   * value for the second argument will result in the equivalent of
-   * doing
+   * Fill this table (which is assumed to already have the correct size) from
+   * a source given by dereferencing the given forward iterator (which could,
+   * for example, be a pointer to the first element of an array, or an
+   * inserting std::istream_iterator). The second argument denotes whether the
+   * elements pointed to are arranged in a way that corresponds to the last
+   * index running fastest or slowest. The default is to use C-style indexing
+   * where the last index runs fastest (as opposed to Fortran-style where the
+   * first index runs fastest when traversing multidimensional arrays. For
+   * example, if you try to fill an object of type Table<2,T>, then calling
+   * this function with the default value for the second argument will result
+   * in the equivalent of doing
    * @code
    *   Table<2,T> t;
    *   for (unsigned int i=0; i<t.sizes()[0]; ++i)
    *     for (unsigned int j=0; j<t.sizes()[1]; ++j)
    *       t[i][j] = *entries++;
    * @endcode
-   * On the other hand, if the second argument to this function is false,
-   * then this would result in code of the following form:
+   * On the other hand, if the second argument to this function is false, then
+   * this would result in code of the following form:
    * @code
    *   Table<2,T> t;
    *   for (unsigned int j=0; j<t.sizes()[1]; ++j)
    *     for (unsigned int i=0; i<t.sizes()[0]; ++i)
    *       t[i][j] = *entries++;
    * @endcode
-   * Note the switched order in which we fill the table elements by
-   * traversing the given set of iterators.
+   * Note the switched order in which we fill the table elements by traversing
+   * the given set of iterators.
    *
-   * @param entries An iterator to a set of elements from which to
-   *   initialize this table. It is assumed that iterator can be
-   *   incremented and dereferenced a sufficient number of times
-   *   to fill this table.
-   * @param C_style_indexing If true, run over elements of the
-   *   table with the last index changing fastest as we dereference
-   *   subsequent elements of the input range. If false, change
-   *   the first index fastest.
+   * @param entries An iterator to a set of elements from which to initialize
+   * this table. It is assumed that iterator can be incremented and
+   * dereferenced a sufficient number of times to fill this table.
+   * @param C_style_indexing If true, run over elements of the table with the
+   * last index changing fastest as we dereference subsequent elements of the
+   * input range. If false, change the first index fastest.
    */
   template <typename InputIterator>
   void fill (InputIterator entries,
              const bool      C_style_indexing = true);
 
   /**
-   * Fill all table entries with
-   * the same value.
+   * Fill all table entries with the same value.
    */
   void fill (const T &value);
 
   /**
-   * Return a read-write reference
-   * to the indicated element.
+   * Return a read-write reference to the indicated element.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<N> &indices);
 
   /**
-   * Return the value of the
-   * indicated element as a
-   * read-only reference.
+   * Return the value of the indicated element as a read-only reference.
    *
-   * We return the requested value
-   * as a constant reference rather
-   * than by value since this
-   * object may hold data types
-   * that may be large, and we
-   * don't know here whether
-   * copying is expensive or not.
+   * We return the requested value as a constant reference rather than by
+   * value since this object may hold data types that may be large, and we
+   * don't know here whether copying is expensive or not.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<N> &indices) const;
@@ -695,56 +590,36 @@ public:
 
 protected:
   /**
-   * Return the position of the
-   * indicated element within the
-   * array of elements stored one
-   * after the other. This function
-   * does no index checking.
+   * Return the position of the indicated element within the array of elements
+   * stored one after the other. This function does no index checking.
    */
   unsigned int position (const TableIndices<N> &indices) const;
 
   /**
-   * Return a read-write reference
-   * to the indicated element.
+   * Return a read-write reference to the indicated element.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    */
   typename AlignedVector<T>::reference el (const TableIndices<N> &indices);
 
   /**
-   * Return the value of the
-   * indicated element as a
-   * read-only reference.
+   * Return the value of the indicated element as a read-only reference.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    *
-   * We return the requested value
-   * as a constant reference rather
-   * than by value since this
-   * object may hold data types
-   * that may be large, and we
-   * don't know here whether
-   * copying is expensive or not.
+   * We return the requested value as a constant reference rather than by
+   * value since this object may hold data types that may be large, and we
+   * don't know here whether copying is expensive or not.
    */
   typename AlignedVector<T>::const_reference el (const TableIndices<N> &indices) const;
 
   /**
-   * @deprecated This function
-   * accesses data directly and
-   * should not be used!
+   * @deprecated This function accesses data directly and should not be used!
    *
-   * Direct read-only access to
-   * data field. Used by
-   * <tt>FullMatrix</tt> of the LAC
-   * sublibrary (there even with a
-   * cast from const), otherwise,
-   * keep away!
+   * Direct read-only access to data field. Used by <tt>FullMatrix</tt> of the
+   * LAC sublibrary (there even with a cast from const), otherwise, keep away!
    */
   typename AlignedVector<T>::const_pointer data () const DEAL_II_DEPRECATED;
 
@@ -755,29 +630,26 @@ protected:
   AlignedVector<T> values;
 
   /**
-   * Size in each direction of the
-   * table.
+   * Size in each direction of the table.
    */
   TableIndices<N> table_size;
 
   /**
-   * Make all other table classes
-   * friends.
+   * Make all other table classes friends.
    */
   template <int, typename> friend class TableBase;
 };
 
 
 /**
- * A class representing a table with arbitrary but fixed number of
- * indices. This general template implements some additional functions
- * over those provided by the TableBase class, such as indexing
- * functions taking the correct number of arguments, etc.
+ * A class representing a table with arbitrary but fixed number of indices.
+ * This general template implements some additional functions over those
+ * provided by the TableBase class, such as indexing functions taking the
+ * correct number of arguments, etc.
  *
- * Rather than this general template, these functions are implemented
- * in partial specializations of this class, with fixed numbers of
- * dimensions. See there, and in the documentation of the base class
- * for more information.
+ * Rather than this general template, these functions are implemented in
+ * partial specializations of this class, with fixed numbers of dimensions.
+ * See there, and in the documentation of the base class for more information.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -789,14 +661,13 @@ class Table : public TableBase<N,T>
 
 
 /**
- * A class representing a one-dimensional table, i.e. a vector-like
- * class. Since the C++ library has a vector class, there is probably
- * not much need for this particular class, but since it is so simple
- * to implement on top of the template base class, we provide it
- * anyway.
+ * A class representing a one-dimensional table, i.e. a vector-like class.
+ * Since the C++ library has a vector class, there is probably not much need
+ * for this particular class, but since it is so simple to implement on top of
+ * the template base class, we provide it anyway.
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -806,21 +677,18 @@ class Table<1,T> : public TableBase<1,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimension to the base
-   * class.
+   * Constructor. Pass down the given dimension to the base class.
    */
   Table (const unsigned int size);
 
   /**
-   * Constructor. Create a table with a given size and initialize it from
-   * set of iterators.
+   * Constructor. Create a table with a given size and initialize it from a
+   * set of iterators.
    *
    * This function is entirely equivalent to creating a table <code>t</code>
    * of the given size and then calling
@@ -830,8 +698,8 @@ public:
    * on it, using the TableBase::fill() function where the arguments are
    * explained in more detail. The point, however, is that that is only
    * possible if the table can be changed after running the constructor,
-   * whereas calling the current constructor allows sizing and initializing
-   * an object right away so that it can be marked const.
+   * whereas calling the current constructor allows sizing and initializing an
+   * object right away so that it can be marked const.
    *
    * Using this constructor, you can do things like this:
    * @code
@@ -848,14 +716,12 @@ public:
    *
    *
    * @param size The size of this one-dimensional table.
-   * @param entries An iterator to a set of elements from which to
-   *   initialize this table. It is assumed that iterator can be
-   *   incremented and dereferenced a sufficient number of times
-   *   to fill this table.
-   * @param C_style_indexing If true, run over elements of the
-   *   table with the last index changing fastest as we dereference
-   *   subsequent elements of the input range. If false, change
-   *   the first index fastest.
+   * @param entries An iterator to a set of elements from which to initialize
+   * this table. It is assumed that iterator can be incremented and
+   * dereferenced a sufficient number of times to fill this table.
+   * @param C_style_indexing If true, run over elements of the table with the
+   * last index changing fastest as we dereference subsequent elements of the
+   * input range. If false, change the first index fastest.
    */
   template <typename InputIterator>
   Table (const unsigned int size,
@@ -863,59 +729,43 @@ public:
          const bool      C_style_indexing = true);
 
   /**
-   * Access operator. Since this is
-   * a one-dimensional object, this
-   * simply accesses the requested
-   * data element. Returns a
-   * read-only reference.
+   * Access operator. Since this is a one-dimensional object, this simply
+   * accesses the requested data element. Returns a read-only reference.
    */
   typename AlignedVector<T>::const_reference
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Since this is
-   * a one-dimensional object, this
-   * simply accesses the requested
-   * data element. Returns a
-   * read-write reference.
+   * Access operator. Since this is a one-dimensional object, this simply
+   * accesses the requested data element. Returns a read-write reference.
    */
   typename AlignedVector<T>::reference
   operator [] (const unsigned int i);
 
   /**
-   * Access operator. Since this is
-   * a one-dimensional object, this
-   * simply accesses the requested
-   * data element. Returns a
-   * read-only reference.
+   * Access operator. Since this is a one-dimensional object, this simply
+   * accesses the requested data element. Returns a read-only reference.
    */
   typename AlignedVector<T>::const_reference
   operator () (const unsigned int i) const;
 
   /**
-   * Access operator. Since this is
-   * a one-dimensional object, this
-   * simply accesses the requested
-   * data element. Returns a
-   * read-write reference.
+   * Access operator. Since this is a one-dimensional object, this simply
+   * accesses the requested data element. Returns a read-write reference.
    */
   typename AlignedVector<T>::reference
   operator () (const unsigned int i);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<1> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<1> &indices) const;
@@ -924,14 +774,14 @@ public:
 
 
 /**
- * A class representing a two-dimensional table, i.e. a matrix of
- * objects (not necessarily only numbers).
+ * A class representing a two-dimensional table, i.e. a matrix of objects (not
+ * necessarily only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class. Since this serves as the base class
- * of the full matrix classes in this library, and to keep a minimal
- * compatibility with a predecessor class (<tt>vector2d</tt>), some
- * additional functions are provided.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class. Since this serves as the base class of the full matrix
+ * classes in this library, and to keep a minimal compatibility with a
+ * predecessor class (<tt>vector2d</tt>), some additional functions are
+ * provided.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -941,22 +791,19 @@ class Table<2,T> : public TableBase<2,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2);
 
   /**
-   * Constructor. Create a table with a given size and initialize it from
-   * set of iterators.
+   * Constructor. Create a table with a given size and initialize it from a
+   * set of iterators.
    *
    * This function is entirely equivalent to creating a table <code>t</code>
    * of the given size and then calling
@@ -966,8 +813,8 @@ public:
    * on it, using the TableBase::fill() function where the arguments are
    * explained in more detail. The point, however, is that that is only
    * possible if the table can be changed after running the constructor,
-   * whereas calling the current constructor allows sizing and initializing
-   * an object right away so that it can be marked const.
+   * whereas calling the current constructor allows sizing and initializing an
+   * object right away so that it can be marked const.
    *
    * Using this constructor, you can do things like this:
    * @code
@@ -985,14 +832,12 @@ public:
    *
    * @param size1 The size of this table in the first dimension.
    * @param size2 The size of this table in the second dimension.
-   * @param entries An iterator to a set of elements from which to
-   *   initialize this table. It is assumed that iterator can be
-   *   incremented and dereferenced a sufficient number of times
-   *   to fill this table.
-   * @param C_style_indexing If true, run over elements of the
-   *   table with the last index changing fastest as we dereference
-   *   subsequent elements of the input range. If false, change
-   *   the first index fastest.
+   * @param entries An iterator to a set of elements from which to initialize
+   * this table. It is assumed that iterator can be incremented and
+   * dereferenced a sufficient number of times to fill this table.
+   * @param C_style_indexing If true, run over elements of the table with the
+   * last index changing fastest as we dereference subsequent elements of the
+   * input range. If false, change the first index fastest.
    */
   template <typename InputIterator>
   Table (const unsigned int size1,
@@ -1001,53 +846,37 @@ public:
          const bool      C_style_indexing = true);
 
   /**
-   * Reinitialize the object. This
-   * function is mostly here for
-   * compatibility with the earlier
-   * <tt>vector2d</tt> class. Passes
-   * down to the base class by
-   * converting the arguments to
-   * the data type requested by the
-   * base class.
+   * Reinitialize the object. This function is mostly here for compatibility
+   * with the earlier <tt>vector2d</tt> class. Passes down to the base class
+   * by converting the arguments to the data type requested by the base class.
    */
   void reinit (const unsigned int size1,
                const unsigned int size2,
                const bool         fast = false);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested row of this
-   * two-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested row of
+   * this two-dimensional table. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<2,T,true,1>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested row of this
-   * two-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested row of
+   * this two-dimensional table. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<2,T,false,1>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference
   operator () (const unsigned int i,
@@ -1055,95 +884,69 @@ public:
 
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference
   operator () (const unsigned int i,
                const unsigned int j);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<2> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<2> &indices) const;
 
 
   /**
-   * Number of rows. This function
-   * really makes only sense since
-   * we have a two-dimensional
-   * object here.
+   * Number of rows. This function really makes only sense since we have a
+   * two-dimensional object here.
    */
   unsigned int n_rows () const;
 
   /**
-   * Number of columns. This function
-   * really makes only sense since
-   * we have a two-dimensional
-   * object here.
+   * Number of columns. This function really makes only sense since we have a
+   * two-dimensional object here.
    */
   unsigned int n_cols () const;
 
 protected:
   /**
-   * Return a read-write reference
-   * to the element <tt>(i,j)</tt>.
+   * Return a read-write reference to the element <tt>(i,j)</tt>.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    *
-   * These functions are mainly
-   * here for compatibility with a
-   * former implementation of these
-   * table classes for 2d arrays,
-   * then called <tt>vector2d</tt>.
+   * These functions are mainly here for compatibility with a former
+   * implementation of these table classes for 2d arrays, then called
+   * <tt>vector2d</tt>.
    */
   typename AlignedVector<T>::reference el (const unsigned int i,
                                            const unsigned int j);
 
   /**
-   * Return the value of the
-   * element <tt>(i,j)</tt> as a
-   * read-only reference.
+   * Return the value of the element <tt>(i,j)</tt> as a read-only reference.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    *
-   * We return the requested value
-   * as a constant reference rather
-   * than by value since this
-   * object may hold data types
-   * that may be large, and we
-   * don't know here whether
-   * copying is expensive or not.
+   * We return the requested value as a constant reference rather than by
+   * value since this object may hold data types that may be large, and we
+   * don't know here whether copying is expensive or not.
    *
-   * These functions are mainly
-   * here for compatibility with a
-   * former implementation of these
-   * table classes for 2d arrays,
-   * then called <tt>vector2d</tt>.
+   * These functions are mainly here for compatibility with a former
+   * implementation of these table classes for 2d arrays, then called
+   * <tt>vector2d</tt>.
    */
   typename AlignedVector<T>::const_reference el (const unsigned int i,
                                                  const unsigned int j) const;
@@ -1152,11 +955,11 @@ protected:
 
 
 /**
- * A class representing a three-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a three-dimensional table of objects (not necessarily
+ * only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -1166,23 +969,20 @@ class Table<3,T> : public TableBase<3,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2,
          const unsigned int size3);
 
   /**
-   * Constructor. Create a table with a given size and initialize it from
-   * set of iterators.
+   * Constructor. Create a table with a given size and initialize it from a
+   * set of iterators.
    *
    * This function is entirely equivalent to creating a table <code>t</code>
    * of the given size and then calling
@@ -1192,11 +992,11 @@ public:
    * on it, using the TableBase::fill() function where the arguments are
    * explained in more detail. The point, however, is that that is only
    * possible if the table can be changed after running the constructor,
-   * whereas calling the current constructor allows sizing and initializing
-   * an object right away so that it can be marked const.
+   * whereas calling the current constructor allows sizing and initializing an
+   * object right away so that it can be marked const.
    *
-   * Using this constructor, you can do things like this (shown here for
-   * two-dimensional table, but the same works for the current class):
+   * Using this constructor, you can do things like this (shown here for a
+   * two-dimensional table, but the same works for the current class):
    * @code
    *   const double values[] = { 1, 2, 3, 4, 5, 6 };
    *   const Table<2,double> t(2, 3, entries, true);
@@ -1213,14 +1013,12 @@ public:
    * @param size1 The size of this table in the first dimension.
    * @param size2 The size of this table in the second dimension.
    * @param size3 The size of this table in the third dimension.
-   * @param entries An iterator to a set of elements from which to
-   *   initialize this table. It is assumed that iterator can be
-   *   incremented and dereferenced a sufficient number of times
-   *   to fill this table.
-   * @param C_style_indexing If true, run over elements of the
-   *   table with the last index changing fastest as we dereference
-   *   subsequent elements of the input range. If false, change
-   *   the first index fastest.
+   * @param entries An iterator to a set of elements from which to initialize
+   * this table. It is assumed that iterator can be incremented and
+   * dereferenced a sufficient number of times to fill this table.
+   * @param C_style_indexing If true, run over elements of the table with the
+   * last index changing fastest as we dereference subsequent elements of the
+   * input range. If false, change the first index fastest.
    */
   template <typename InputIterator>
   Table (const unsigned int size1,
@@ -1230,41 +1028,30 @@ public:
          const bool      C_style_indexing = true);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested two-dimensional
-   * subobject of this
-   * three-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested two-
+   * dimensional subobject of this three-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<3,T,true,2>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested two-dimensional
-   * subobject of this
-   * three-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested two-
+   * dimensional subobject of this three-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<3,T,false,2>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j,
@@ -1272,31 +1059,24 @@ public:
 
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j,
                                                     const unsigned int k);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference operator () (const TableIndices<3> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference operator () (const TableIndices<3> &indices) const;
 };
@@ -1304,11 +1084,11 @@ public:
 
 
 /**
- * A class representing a four-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a four-dimensional table of objects (not necessarily
+ * only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -1318,15 +1098,12 @@ class Table<4,T> : public TableBase<4,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2,
@@ -1334,41 +1111,30 @@ public:
          const unsigned int size4);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested three-dimensional
-   * subobject of this
-   * four-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested three-
+   * dimensional subobject of this four-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<4,T,true,3>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested three-dimensional
-   * subobject of this
-   * four-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested three-
+   * dimensional subobject of this four-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<4,T,false,3>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j,
@@ -1377,13 +1143,10 @@ public:
 
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j,
@@ -1391,19 +1154,15 @@ public:
                                                     const unsigned int l);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<4> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<4> &indices) const;
@@ -1412,11 +1171,11 @@ public:
 
 
 /**
- * A class representing a five-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a five-dimensional table of objects (not necessarily
+ * only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -1426,15 +1185,12 @@ class Table<5,T> : public TableBase<5,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2,
@@ -1443,41 +1199,30 @@ public:
          const unsigned int size5);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested four-dimensional
-   * subobject of this
-   * five-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested four-
+   * dimensional subobject of this five-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<5,T,true,4>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested four-dimensional
-   * subobject of this
-   * five-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested four-
+   * dimensional subobject of this five-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<5,T,false,4>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j,
@@ -1486,13 +1231,10 @@ public:
                                                           const unsigned int m) const;
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j,
@@ -1501,19 +1243,15 @@ public:
                                                     const unsigned int m);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<5> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<5> &indices) const;
@@ -1522,11 +1260,11 @@ public:
 
 
 /**
- * A class representing a six-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a six-dimensional table of objects (not necessarily
+ * only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -1536,15 +1274,12 @@ class Table<6,T> : public TableBase<6,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2,
@@ -1554,41 +1289,30 @@ public:
          const unsigned int size6);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested five-dimensional
-   * subobject of this
-   * six-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested five-
+   * dimensional subobject of this six-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<6,T,true,5>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested five-dimensional
-   * subobject of this
-   * six-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested five-
+   * dimensional subobject of this six-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<6,T,false,5>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j,
@@ -1598,13 +1322,10 @@ public:
                                                           const unsigned int n) const;
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j,
@@ -1614,19 +1335,15 @@ public:
                                                     const unsigned int n);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<6> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<6> &indices) const;
@@ -1634,11 +1351,11 @@ public:
 
 
 /**
- * A class representing a seven-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a seven-dimensional table of objects (not necessarily
+ * only numbers).
  *
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002, Ralf Hartmann 2004
@@ -1648,15 +1365,12 @@ class Table<7,T> : public TableBase<7,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   Table ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   Table (const unsigned int size1,
          const unsigned int size2,
@@ -1667,41 +1381,30 @@ public:
          const unsigned int size7);
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested six-dimensional
-   * subobject of this
-   * seven-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested six-
+   * dimensional subobject of this seven-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   dealii::internal::TableBaseAccessors::Accessor<7,T,true,6>
   operator [] (const unsigned int i) const;
 
   /**
-   * Access operator. Generate an
-   * object that accesses the
-   * requested six-dimensional
-   * subobject of this
-   * seven-dimensional table. Range
-   * checks are performed.
+   * Access operator. Generate an object that accesses the requested six-
+   * dimensional subobject of this seven-dimensional table. Range checks are
+   * performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   dealii::internal::TableBaseAccessors::Accessor<7,T,false,6>
   operator [] (const unsigned int i);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j,
@@ -1712,13 +1415,10 @@ public:
                                                           const unsigned int o) const;
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j,
@@ -1729,19 +1429,15 @@ public:
                                                     const unsigned int o);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::reference
   operator () (const TableIndices<7> &indices);
 
   /**
-   * Make the corresponding
-   * operator () from the TableBase
-   * base class available also in
-   * this class.
+   * Make the corresponding operator () from the TableBase base class
+   * available also in this class.
    */
   typename AlignedVector<T>::const_reference
   operator () (const TableIndices<7> &indices) const;
@@ -1755,9 +1451,9 @@ public:
  * convention). The only real difference is therefore really in the storage
  * format.
  *
- * This class copies the functions of Table<2,T>, but the element
- * access and the dimensions will be for the transpose ordering of the
- * data field in TableBase.
+ * This class copies the functions of Table<2,T>, but the element access and
+ * the dimensions will be for the transpose ordering of the data field in
+ * TableBase.
  *
  * @ingroup data
  * @author Guido Kanschat, 2005
@@ -1767,115 +1463,82 @@ class TransposeTable : public TableBase<2,T>
 {
 public:
   /**
-   * Default constructor. Set all
-   * dimensions to zero.
+   * Default constructor. Set all dimensions to zero.
    */
   TransposeTable ();
 
   /**
-   * Constructor. Pass down the
-   * given dimensions to the base
-   * class.
+   * Constructor. Pass down the given dimensions to the base class.
    */
   TransposeTable (const unsigned int size1,
                   const unsigned int size2);
 
   /**
-   * Reinitialize the object. This
-   * function is mostly here for
-   * compatibility with the earlier
-   * <tt>vector2d</tt> class. Passes
-   * down to the base class by
-   * converting the arguments to
-   * the data type requested by the
-   * base class.
+   * Reinitialize the object. This function is mostly here for compatibility
+   * with the earlier <tt>vector2d</tt> class. Passes down to the base class
+   * by converting the arguments to the data type requested by the base class.
    */
   void reinit (const unsigned int size1,
                const unsigned int size2,
                const bool         fast = false);
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * only allows read access.
+   * This version of the function only allows read access.
    */
   typename AlignedVector<T>::const_reference operator () (const unsigned int i,
                                                           const unsigned int j) const;
 
   /**
-   * Direct access to one element
-   * of the table by specifying all
-   * indices at the same time. Range
-   * checks are performed.
+   * Direct access to one element of the table by specifying all indices at
+   * the same time. Range checks are performed.
    *
-   * This version of the function
-   * allows read-write access.
+   * This version of the function allows read-write access.
    */
   typename AlignedVector<T>::reference operator () (const unsigned int i,
                                                     const unsigned int j);
 
   /**
-   * Number of rows. This function
-   * really makes only sense since
-   * we have a two-dimensional
-   * object here.
+   * Number of rows. This function really makes only sense since we have a
+   * two-dimensional object here.
    */
   unsigned int n_rows () const;
 
   /**
-   * Number of columns. This function
-   * really makes only sense since
-   * we have a two-dimensional
-   * object here.
+   * Number of columns. This function really makes only sense since we have a
+   * two-dimensional object here.
    */
   unsigned int n_cols () const;
 
 protected:
   /**
-   * Return a read-write reference
-   * to the element <tt>(i,j)</tt>.
+   * Return a read-write reference to the element <tt>(i,j)</tt>.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    *
-   * These functions are mainly
-   * here for compatibility with a
-   * former implementation of these
-   * table classes for 2d arrays,
-   * then called <tt>vector2d</tt>.
+   * These functions are mainly here for compatibility with a former
+   * implementation of these table classes for 2d arrays, then called
+   * <tt>vector2d</tt>.
    */
   typename AlignedVector<T>::reference el (const unsigned int i,
                                            const unsigned int j);
 
   /**
-   * Return the value of the
-   * element <tt>(i,j)</tt> as a
-   * read-only reference.
+   * Return the value of the element <tt>(i,j)</tt> as a read-only reference.
    *
-   * This function does no bounds
-   * checking and is only to be
-   * used internally and in
-   * functions already checked.
+   * This function does no bounds checking and is only to be used internally
+   * and in functions already checked.
    *
-   * We return the requested value
-   * as a constant reference rather
-   * than by value since this
-   * object may hold data types
-   * that may be large, and we
-   * don't know here whether
-   * copying is expensive or not.
+   * We return the requested value as a constant reference rather than by
+   * value since this object may hold data types that may be large, and we
+   * don't know here whether copying is expensive or not.
    *
-   * These functions are mainly
-   * here for compatibility with a
-   * former implementation of these
-   * table classes for 2d arrays,
-   * then called <tt>vector2d</tt>.
+   * These functions are mainly here for compatibility with a former
+   * implementation of these table classes for 2d arrays, then called
+   * <tt>vector2d</tt>.
    */
   typename AlignedVector<T>::const_reference el (const unsigned int i,
                                                  const unsigned int j) const;
@@ -3460,9 +3123,9 @@ Table<7,T>::operator () (const TableIndices<7> &indices)
 
 
 /**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two tables.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two tables.
  *
  * @author Martin Kronbichler, 2013
  */
index 38bcd79db3b0d11b5a5c480d0f759a362364e446..61bc88062a4589f56c72022e35616e0acd45c472 100644 (file)
@@ -41,13 +41,12 @@ class TableHandler;
 namespace internal
 {
   /**
-   * A <tt>TableEntry</tt> stores the value of a table entry.
-   * It can either be of type int, unsigned int, double or std::string.
-   * In essence, this structure is the same as
-   * <code>boost::variant@<int,unsigned int,double,std::string@></code>
-   * but we wrap this object in a structure for which we can write
-   * a function that can serialize it. This is also why the function
-   * is not in fact of type boost::any.
+   * A <tt>TableEntry</tt> stores the value of a table entry. It can either be
+   * of type int, unsigned int, double or std::string. In essence, this
+   * structure is the same as <code>boost::variant@<int,unsigned
+   * int,double,std::string@></code> but we wrap this object in a structure
+   * for which we can write a function that can serialize it. This is also why
+   * the function is not in fact of type boost::any.
    */
   struct TableEntry
   {
@@ -58,61 +57,61 @@ namespace internal
     TableEntry ();
 
     /**
-     * Constructor. Initialize this table element with the value <code>t</code>.
+     * Constructor. Initialize this table element with the value
+     * <code>t</code>.
      */
     template <typename T>
     TableEntry (const T &t);
 
     /**
-     * Return the value stored by this object. The template type
-     * T must be one of <code>int,unsigned int,double,std::string</code>
-     * and it must match the data type of the object originally stored
-     * in this TableEntry object.
+     * Return the value stored by this object. The template type T must be one
+     * of <code>int,unsigned int,double,std::string</code> and it must match
+     * the data type of the object originally stored in this TableEntry
+     * object.
      */
     template <typename T>
     T get () const;
 
     /**
-     * Return the numeric value of this object if data has been stored in
-     * it either as an integer, an unsigned integer, or a double.
+     * Return the numeric value of this object if data has been stored in it
+     * either as an integer, an unsigned integer, or a double.
      *
      * @return double
-     **/
+     */
     double get_numeric_value () const;
 
     /**
-     * Cache the contained value with the given formatting and return it. The given parameters
-     * from the column definition are used for the formatting. The value
-     * is cached as a string internally in cached_value. The cache needs to be invalidated with this routine
-     * if the formatting of the column changes.
+     * Cache the contained value with the given formatting and return it. The
+     * given parameters from the column definition are used for the
+     * formatting. The value is cached as a string internally in cached_value.
+     * The cache needs to be invalidated with this routine if the formatting
+     * of the column changes.
      */
     void cache_string(bool scientific, unsigned int precision) const;
 
     /**
-     * Return the value cached using cache_string(). This is just a wrapper around cached_value.
+     * Return the value cached using cache_string(). This is just a wrapper
+     * around cached_value.
      */
     const std::string &get_cached_string() const;
 
 
     /**
-     * Return a TableEntry object that has the same data type
-     * of the stored value but with a value that is default
-     * constructed for this data type. This is used to pad
-     * columns below previously set ones.
+     * Return a TableEntry object that has the same data type of the stored
+     * value but with a value that is default constructed for this data type.
+     * This is used to pad columns below previously set ones.
      */
     TableEntry get_default_constructed_copy() const;
 
     /**
-     * Write the data of this object to a
-     * stream for the purpose of
+     * Write the data of this object to a stream for the purpose of
      * serialization.
      */
     template <class Archive>
     void save (Archive &ar, const unsigned int version) const;
 
     /**
-     * Read the data of this object from a
-     * stream for the purpose of
+     * Read the data of this object from a stream for the purpose of
      * serialization.
      */
     template <class Archive>
@@ -142,10 +141,9 @@ namespace internal
 
 
 /**
- * The TableHandler stores TableEntries of arbitrary value
- * type and writes the table as text or in tex format to an output
- * stream. The value type actually may vary from column to column and
- * from row to row.
+ * The TableHandler stores TableEntries of arbitrary value type and writes the
+ * table as text or in tex format to an output stream. The value type actually
+ * may vary from column to column and from row to row.
  *
  * <h3>Usage</h3>
  *
@@ -155,15 +153,14 @@ namespace internal
  * exist and adds the given value of type <tt>T</tt> (which must be one of
  * <tt>int</tt>, <tt>unsigned int</tt>, <tt>double</tt>, <tt>std::string</tt>)
  * to this column.  After the table is complete there are different
- * possibilities of output, e.g., into a latex file with write_tex() or as text
- * with write_text().
+ * possibilities of output, e.g., into a latex file with write_tex() or as
+ * text with write_text().
  *
- * Two (or more) columns may be merged into a "supercolumn" by twice
- * (or multiple) calling add_column_to_supercolumn(), see
- * there. Additionally there is a function to set for each column the
- * precision of the output of numbers, and there are several functions
- * to prescribe the format and the captions the columns are written
- * with in tex mode.
+ * Two (or more) columns may be merged into a "supercolumn" by twice (or
+ * multiple) calling add_column_to_supercolumn(), see there. Additionally
+ * there is a function to set for each column the precision of the output of
+ * numbers, and there are several functions to prescribe the format and the
+ * captions the columns are written with in tex mode.
  *
  * A detailed explanation of this class is also given in the step-13 tutorial
  * program.
@@ -171,13 +168,13 @@ namespace internal
  *
  * <h3>Example</h3>
  *
- * This is a simple example demonstrating the usage of this class. The
- * first column includes the numbers <tt>i=1..n</tt>, the second
- * $1^2$...$n^2$, the third $sqrt(1)...sqrt(n)$, where the second and
- * third columns are merged into one supercolumn with the superkey
- * <tt>squares and roots</tt>. Additionally the first column is aligned to
- * the right (the default was <tt>centered</tt>) and the precision of the
- * square roots are set to be 6 (instead of 4 as default).
+ * This is a simple example demonstrating the usage of this class. The first
+ * column includes the numbers <tt>i=1..n</tt>, the second $1^2$...$n^2$, the
+ * third $sqrt(1)...sqrt(n)$, where the second and third columns are merged
+ * into one supercolumn with the superkey <tt>squares and roots</tt>.
+ * Additionally the first column is aligned to the right (the default was
+ * <tt>centered</tt>) and the precision of the square roots are set to be 6
+ * (instead of 4 as default).
  *
  * @code
  * TableHandler table;
@@ -205,57 +202,59 @@ namespace internal
  *
  * <h3>Dealing with sparse data: auto-fill mode</h3>
  *
- * When generating output, TableHandler expects that all columns have the exact
- * same number of elements in it so that the result is in fact a table. This
- * assumes that in each of the iterations (time steps, nonlinear iterations, etc)
- * you fill every single column. On the other hand, this may not always be what
- * you want to do. For example, it could be that the function that computes the
- * nonlinear residual is only called every few time steps; or, a function computing
- * statistics of the mesh is only called whenever the mesh is in fact refined.
- * In these cases, the add_value() function will be called less often for some
- * columns and the column would therefore have fewer elements; furthermore, these
- * elements would not be aligned with the rows that contain the other data elements
- * that were produced during this iteration.
- * An entirely different scenario is that the table is filled and at a later time
- * we use the data in there to compute the elements of other rows; the ConvergenceTable
- * class does something like this.
+ * When generating output, TableHandler expects that all columns have the
+ * exact same number of elements in it so that the result is in fact a table.
+ * This assumes that in each of the iterations (time steps, nonlinear
+ * iterations, etc) you fill every single column. On the other hand, this may
+ * not always be what you want to do. For example, it could be that the
+ * function that computes the nonlinear residual is only called every few time
+ * steps; or, a function computing statistics of the mesh is only called
+ * whenever the mesh is in fact refined. In these cases, the add_value()
+ * function will be called less often for some columns and the column would
+ * therefore have fewer elements; furthermore, these elements would not be
+ * aligned with the rows that contain the other data elements that were
+ * produced during this iteration. An entirely different scenario is that the
+ * table is filled and at a later time we use the data in there to compute the
+ * elements of other rows; the ConvergenceTable class does something like
+ * this.
  *
- * To support both scenarios, the TableHandler class has a property called
- * <i>auto-fill mode</i>. By default, auto-fill mode is off, but it can be
- * enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled
- * we use the following algorithm:
- * - When calling <code>add_value(key, value)</code>, we count the number of elements
- *   in the column corresponding to <code>key</code>. Let's call this number $m$.
- * - We also determine the maximal number of elements in the other columns; call
- *   it $n$.
- * - If $m < n-1$ then we add $n-m-1$ copies of the object <code>T()</code>
- *   to this column. Here, <code>T</code> is the data type of the given <code>value</code>.
- *   For example, if <code>T</code> is a numeric type, then <code>T()</code> is
- *   the number zero; if <code>T</code> is <code>std::string</code>, then
- *   <code>T()</code> is the empty string <code>""</code>.
- * - Add the given value to this column.
+ * To support both scenarios, the TableHandler class has a property called <i
+ * >auto-fill mode</i>. By default, auto-fill mode is off, but it can be
+ * enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled we
+ * use the following algorithm: - When calling <code>add_value(key,
+ * value)</code>, we count the number of elements in the column corresponding
+ * to <code>key</code>. Let's call this number $m$. - We also determine the
+ * maximal number of elements in the other columns; call it $n$. - If $m <
+ * n-1$ then we add $n-m-1$ copies of the object <code>T()</code> to this
+ * column. Here, <code>T</code> is the data type of the given
+ * <code>value</code>. For example, if <code>T</code> is a numeric type, then
+ * <code>T()</code> is the number zero; if <code>T</code> is
+ * <code>std::string</code>, then <code>T()</code> is the empty string
+ * <code>""</code>. - Add the given value to this column.
  *
- * Padding the column with default elements makes sure that after the addition the
- * column has as many entries as the longest other column. In other words, if
- * we have skipped previous invokations of add_value() for a given key, then the
- * padding will enter default values into this column.
+ * Padding the column with default elements makes sure that after the addition
+ * the column has as many entries as the longest other column. In other words,
+ * if we have skipped previous invokations of add_value() for a given key,
+ * then the padding will enter default values into this column.
  *
- * The algorithm as described will fail if you try to skip adding values for a key
- * if adding an element for this key is the first thing you want to do for a given
- * iteration or time step, since we would then pad to the length of the longest
- * column of the <i>previous</i> iteration or time step. You may have to re-order
- * adding to this column to a different spot in your program, after adding to
- * a column that will always be added to; or, you may want to start every iteration
- * by adding the number of the iteration to the table, for example in column 1.
+ * The algorithm as described will fail if you try to skip adding values for a
+ * key if adding an element for this key is the first thing you want to do for
+ * a given iteration or time step, since we would then pad to the length of
+ * the longest column of the <i>previous</i> iteration or time step. You may
+ * have to re-order adding to this column to a different spot in your program,
+ * after adding to a column that will always be added to; or, you may want to
+ * start every iteration by adding the number of the iteration to the table,
+ * for example in column 1.
  *
- * In the case above, we have always padded columns <b>above</b> the element that
- * is being added to a column. However, there is also a case where we have to pad
- * <b>below</b>. Namely, if a previous row has been completely filled using
- * TableHandler::add_value(), subsequent rows have been filled partially, and we
- * then ask for output via write_text() or write_tex(). In that case, the last
- * few rows that have been filled only partially need to be padded below the last
- * element that has been added to them. As before, we do that by using default
- * constructed objects of the same type as the last element of that column.
+ * In the case above, we have always padded columns <b>above</b> the element
+ * that is being added to a column. However, there is also a case where we
+ * have to pad <b>below</b>. Namely, if a previous row has been completely
+ * filled using TableHandler::add_value(), subsequent rows have been filled
+ * partially, and we then ask for output via write_text() or write_tex(). In
+ * that case, the last few rows that have been filled only partially need to
+ * be padded below the last element that has been added to them. As before, we
+ * do that by using default constructed objects of the same type as the last
+ * element of that column.
  *
  * @ingroup textoutput
  * @author Ralf Hartmann, 1999; Wolfgang Bangerth, 2011
@@ -264,14 +263,13 @@ class TableHandler
 {
 public:
   /**
-   * Set of options how a table should be formatted when output with
-   * the write_text() function. The following possibilities exist:
+   * Set of options how a table should be formatted when output with the
+   * write_text() function. The following possibilities exist:
    *
    * - <code>table_with_headers</code>: The table is formatted in such a way
-   *   that the contents are aligned under the key of each column, i.e. the
-   *   key sits atop each column. This is suitable for tables with few columns
-   *   where the entire table can be displayed on the screen. Output looks
-   *   like this:
+   * that the contents are aligned under the key of each column, i.e. the key
+   * sits atop each column. This is suitable for tables with few columns where
+   * the entire table can be displayed on the screen. Output looks like this:
    *   @code
    *     key1 key2 key3
    *     0    0    ""
@@ -280,14 +278,14 @@ public:
    *     1    0    ""
    *   @endcode
    * - <code>table_with_separate_column_description</code>: This is a better
-   *   format when there are many columns and the table as a whole can not
-   *   be displayed on the screen. Here, the column keys are first listed
-   *   one-by-one on lines of their own, and are numbered for better readability.
-   *   In addition, each of these description lines are prefixed by '#' to mark
-   *   these lines as comments for programs that want to read the following
-   *   table as data and should ignore these descriptive lines. GNUPLOT is
-   *   one such program that will automatically ignore lines so prefixed.
-   *   Output with this option looks like this:
+   * format when there are many columns and the table as a whole can not be
+   * displayed on the screen. Here, the column keys are first listed one-by-
+   * one on lines of their own, and are numbered for better readability. In
+   * addition, each of these description lines are prefixed by '#' to mark
+   * these lines as comments for programs that want to read the following
+   * table as data and should ignore these descriptive lines. GNUPLOT is one
+   * such program that will automatically ignore lines so prefixed. Output
+   * with this option looks like this:
    *   @code
    *     # 1: key1
    *     # 2: key2
@@ -298,9 +296,10 @@ public:
    *     1 0  ""
    *   @endcode
    * - <code>simple_table_with_separate_column_description</code>: This format
-   *   is very similar to <code>table_with_separate_column_description</code>,
-   *   but it skips aligning the columns with additional white space. This
-   *   increases the performance o fwrite_text() for large tables. Example output:
+   * is very similar to <code>table_with_separate_column_description</code>,
+   * but it skips aligning the columns with additional white space. This
+   * increases the performance o fwrite_text() for large tables. Example
+   * output:
    *   @code
    *     # 1: key1
    *     # 2: key2
@@ -310,9 +309,9 @@ public:
    *     2 13 a
    *     1 0 ""
    *   @endcode
-   * - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/) table
-   *   format. It is easy to convert org-mode tables to HTML/LaTeX/csv.
-   *   Example output:
+   * - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/)
+   * table format. It is easy to convert org-mode tables to HTML/LaTeX/csv.
+   * Example output:
    *   @code
    *   | key1 | key2 | key3 |
    *   | 0    | 0    | ""   |
@@ -335,201 +334,143 @@ public:
   TableHandler ();
 
   /**
-   * Adds a column (if not yet existent)
-   * with the key <tt>key</tt> and adds the
-   * value of type <tt>T</tt> to the
-   * column. Values of type <tt>T</tt> must
-   * be convertible to one of <code>int,
-   * unsigned int, double,
-   * std::string</code> or a compiler error
-   * will result.
+   * Adds a column (if not yet existent) with the key <tt>key</tt> and adds
+   * the value of type <tt>T</tt> to the column. Values of type <tt>T</tt>
+   * must be convertible to one of <code>int, unsigned int, double,
+   * std::string</code> or a compiler error will result.
    */
   template <typename T>
   void add_value (const std::string &key,
                   const T            value);
 
   /**
-   * Switch auto-fill mode on or off. See the general documentation
-   * of this class for a description of what auto-fill mode does.
+   * Switch auto-fill mode on or off. See the general documentation of this
+   * class for a description of what auto-fill mode does.
    */
   void set_auto_fill_mode (const bool state);
 
   /**
-   * Creates a supercolumn (if not
-   * yet existent) and includes
-   * column to it.  The keys of the
-   * column and the supercolumn are
-   * <tt>key</tt> and <tt>superkey</tt>,
-   * respectively.  To merge two
-   * columns <tt>c1</tt> and <tt>c2</tt> to a
-   * supercolumn <tt>sc</tt> hence call
-   * <tt>add_column_to_supercolumn(c1,sc)</tt>
-   * and
+   * Creates a supercolumn (if not yet existent) and includes column to it.
+   * The keys of the column and the supercolumn are <tt>key</tt> and
+   * <tt>superkey</tt>, respectively.  To merge two columns <tt>c1</tt> and
+   * <tt>c2</tt> to a supercolumn <tt>sc</tt> hence call
+   * <tt>add_column_to_supercolumn(c1,sc)</tt> and
    * <tt>add_column_to_supercolumn(c2,sc)</tt>.
    *
-   * Concerning the order of the
-   * columns, the supercolumn
-   * replaces the first column that
-   * is added to the supercolumn.
-   * Within the supercolumn the
-   * order of output follows the
-   * order the columns are added to
-   * the supercolumn.
+   * Concerning the order of the columns, the supercolumn replaces the first
+   * column that is added to the supercolumn. Within the supercolumn the order
+   * of output follows the order the columns are added to the supercolumn.
    */
   void add_column_to_supercolumn (const std::string &key,
                                   const std::string &superkey);
 
   /**
-   * Change the order of columns and
-   * supercolumns in the table.
+   * Change the order of columns and supercolumns in the table.
    *
-   * <tt>new_order</tt> includes the
-   * keys and superkeys of the
-   * columns and supercolumns in
-   * the order the user would like them to be output.
-   * If a superkey is included the
-   * keys of the subcolumns need
-   * not be explicitly
-   * mentioned in this vector.  The
-   * order of subcolumns within a
-   * supercolumn is not changeable
-   * and remains in the order in which
-   * the columns are added to the
-   * supercolumn.
+   * <tt>new_order</tt> includes the keys and superkeys of the columns and
+   * supercolumns in the order the user would like them to be output. If a
+   * superkey is included the keys of the subcolumns need not be explicitly
+   * mentioned in this vector.  The order of subcolumns within a supercolumn
+   * is not changeable and remains in the order in which the columns are added
+   * to the supercolumn.
    *
-   * This function may also be used
-   * to break big tables with too
-   * many columns into smaller
-   * ones. For example, you can call this function with
-   * the first five columns
-   * and then call one of the <tt>write_*</tt> functions,
-   * then call this function
-   * with the next five
-   * columns and again <tt>write_*</tt>,
+   * This function may also be used to break big tables with too many columns
+   * into smaller ones. For example, you can call this function with the first
+   * five columns and then call one of the <tt>write_*</tt> functions, then
+   * call this function with the next five columns and again <tt>write_*</tt>,
    * and so on.
    */
   void set_column_order (const std::vector<std::string> &new_order);
 
   /**
-   * Sets the <tt>precision</tt>
-   * e.g. double or float variables
-   * are written
-   * with. <tt>precision</tt> is the
-   * same as in calling
+   * Sets the <tt>precision</tt> e.g. double or float variables are written
+   * with. <tt>precision</tt> is the same as in calling
    * <tt>out<<setprecision(precision)</tt>.
    */
   void set_precision (const std::string &key,
                       const unsigned int precision);
 
   /**
-   * Sets the
-   * <tt>scientific_flag</tt>. True
-   * means scientific, false means
+   * Sets the <tt>scientific_flag</tt>. True means scientific, false means
    * fixed point notation.
    */
   void set_scientific (const std::string &key,
                        const bool         scientific);
 
   /**
-   * Sets the caption of the column
-   * <tt>key</tt> for tex output. You
-   * may want to chose this
-   * different from <tt>key</tt>, if it
-   * contains formulas or similar
-   * constructs.
+   * Sets the caption of the column <tt>key</tt> for tex output. You may want
+   * to chose this different from <tt>key</tt>, if it contains formulas or
+   * similar constructs.
    */
   void set_tex_caption (const std::string &key,
                         const std::string &tex_caption);
 
   /**
-    * Sets the tex caption of the entire
-    * <tt>table</tt> for tex output.
-    */
+   * Sets the tex caption of the entire <tt>table</tt> for tex output.
+   */
   void set_tex_table_caption (const std::string &table_caption);
 
   /**
-   * Sets the label of this
-   * <tt>table</tt> for tex output.
+   * Sets the label of this <tt>table</tt> for tex output.
    */
   void set_tex_table_label (const std::string &table_label);
 
   /**
-   * Sets the caption the the
-   * supercolumn <tt>superkey</tt> for
-   * tex output. You may want to
-   * chose this different from
-   * <tt>superkey</tt>, if it contains
-   * formulas or similar
-   * constructs.
+   * Sets the caption the the supercolumn <tt>superkey</tt> for tex output.
+   * You may want to chose this different from <tt>superkey</tt>, if it
+   * contains formulas or similar constructs.
    */
   void set_tex_supercaption (const std::string &superkey,
                              const std::string &tex_supercaption);
 
   /**
-   * Sets the tex output format of
-   * a column, e.g. <tt>c</tt>, <tt>r</tt>,
-   * <tt>l</tt>, or <tt>p{3cm}</tt>. The
-   * default is <tt>c</tt>. Also if this
-   * function is not called for a
-   * column, the default is preset
-   * to be <tt>c</tt>.
+   * Sets the tex output format of a column, e.g. <tt>c</tt>, <tt>r</tt>,
+   * <tt>l</tt>, or <tt>p{3cm}</tt>. The default is <tt>c</tt>. Also if this
+   * function is not called for a column, the default is preset to be
+   * <tt>c</tt>.
    */
   void set_tex_format (const std::string &key,
                        const std::string &format="c");
 
   /**
-   * Write table as formatted text to the
-   * given stream. The text is formatted in
-   * such as way that it represents data as
-   * formatted columns of text. To avoid
-   * problems when reading these tables
-   * automatically, for example for
-   * postprocessing, if an entry in a cell
-   * of this table is empty (i.e. it has
-   * been created by calling the
-   * add_value() function with an empty
-   * string), then the entry of the table
-   * is printed as <code>""</code>.
+   * Write table as formatted text to the given stream. The text is formatted
+   * in such as way that it represents data as formatted columns of text. To
+   * avoid problems when reading these tables automatically, for example for
+   * postprocessing, if an entry in a cell of this table is empty (i.e. it has
+   * been created by calling the add_value() function with an empty string),
+   * then the entry of the table is printed as <code>""</code>.
    *
-   * The second argument indicates how
-   * column keys are to be displayed. See
-   * the description of TextOutputFormat
-   * for more information
+   * The second argument indicates how column keys are to be displayed. See
+   * the description of TextOutputFormat for more information
    */
   void write_text (std::ostream &out,
                    const TextOutputFormat format = table_with_headers) const;
 
   /**
-   * Write table as a tex file. If
-   * with_header is set to false
-   * (it is true by default), then
-   * no "\documentclass{...}",
-   * "\begin{document}" and
-   * "\end{document}" are used. In
-   * this way the file can be
-   * included into an existing tex
-   * file using a command like
-   * "\input{table_file}".
+   * Write table as a tex file. If with_header is set to false (it is true by
+   * default), then no "\documentclass{...}", "\begin{document}" and
+   * "\end{document}" are used. In this way the file can be included into an
+   * existing tex file using a command like "\input{table_file}".
    */
   void write_tex (std::ostream &file, const bool with_header=true) const;
 
   /**
-   * Clears the rows of the table,
-   * i.e. calls clear() on all the
-   * underlying storage data structures.
+   * Clears the rows of the table, i.e. calls clear() on all the underlying
+   * storage data structures.
    */
   void clear ();
 
   /**
-   * Read or write the data of this
-   * object to or from a stream for
-   * the purpose of serialization.
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization.
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -570,9 +511,8 @@ public:
 protected:
 
   /**
-   * Structure encapsulating all the data
-   * that is needed to describe one column
-   * of a table.
+   * Structure encapsulating all the data that is needed to describe one
+   * column of a table.
    */
   struct Column
   {
@@ -587,15 +527,14 @@ protected:
     Column (const std::string &tex_caption);
 
     /**
-     * Pad this column with default constructed elements to the
-     * number of rows given by the argument.
+     * Pad this column with default constructed elements to the number of rows
+     * given by the argument.
      */
     void pad_column_below (const unsigned int length);
 
     /**
-     * Read or write the data of this
-     * object to or from a stream for
-     * the purpose of serialization.
+     * Read or write the data of this object to or from a stream for the
+     * purpose of serialization.
      */
     template <class Archive>
     void save(Archive &ar, const unsigned int version) const;
@@ -605,152 +544,109 @@ protected:
 
 
     /**
-     * Invalidates the string cache of all the entries and recomputes
-     * the maximum length max_length.
+     * Invalidates the string cache of all the entries and recomputes the
+     * maximum length max_length.
      */
     void invalidate_cache();
 
     /**
-     * List of entries within
-     * this column. Values are
-     * always immediately
-     * converted to strings to
-     * provide a uniform method
-     * of lookup.
+     * List of entries within this column. Values are always immediately
+     * converted to strings to provide a uniform method of lookup.
      */
     std::vector<internal::TableEntry> entries;
 
     /**
-     * The caption of the column
-     * in tex output.  By
-     * default, this is the key
-     * string that is given to
-     * the <tt>TableHandler</tt> by
-     * <tt>TableHandler::add_value(...)</tt>. This
-     * may be changed by calling
+     * The caption of the column in tex output.  By default, this is the key
+     * string that is given to the <tt>TableHandler</tt> by
+     * <tt>TableHandler::add_value(...)</tt>. This may be changed by calling
      * <tt>TableHandler::set_tex_caption(...)</tt>.
      */
     std::string tex_caption;
 
     /**
-     * The column format in tex
-     * output.  By default, this
-     * is <tt>"c"</tt>, meaning
-     * `centered'. This may be
-     * changed by calling
-     * <tt>TableHandler::set_tex_format(...)</tt>
-     * with <tt>"c", "r", "l"</tt> for
-     * centered, right or left.
+     * The column format in tex output.  By default, this is <tt>"c"</tt>,
+     * meaning `centered'. This may be changed by calling
+     * <tt>TableHandler::set_tex_format(...)</tt> with <tt>"c", "r", "l"</tt>
+     * for centered, right or left.
      */
 
     std::string tex_format;
 
     /**
-     * Double or float entries
-     * are written with this
-     * precision (set by the
+     * Double or float entries are written with this precision (set by the
      * user).  The default is 4.
      */
     unsigned int precision;
 
     /**
-     * <tt>scientific</tt>=false means
-     * fixed point notation.
+     * <tt>scientific</tt>=false means fixed point notation.
      */
     bool scientific;
 
     /**
-     * Flag that may be used by
-     * derived classes for
-     * arbitrary purposes.
+     * Flag that may be used by derived classes for arbitrary purposes.
      *
-     * In particular, the
-     * ConvergenceTable class uses the
-     * flag to denote columns for which
-     * convergence information has
-     * already been computed, or should
-     * not be computed at all.
+     * In particular, the ConvergenceTable class uses the flag to denote
+     * columns for which convergence information has already been computed, or
+     * should not be computed at all.
      */
     unsigned int flag;
 
     /**
-     * This entry caches the maximum length in characters for all entries in this table.
+     * This entry caches the maximum length in characters for all entries in
+     * this table.
      */
     unsigned int max_length;
   };
 
   /**
-   * Help function that gives a
-   * vector of the keys of all
-   * columns that are mentioned in
-   * <tt>column_order</tt>, where each
-   * supercolumn key is replaced by
-   * its subcolumn keys.
+   * Help function that gives a vector of the keys of all columns that are
+   * mentioned in <tt>column_order</tt>, where each supercolumn key is
+   * replaced by its subcolumn keys.
    *
-   * This function implicitly
-   * checks the consistency of the
-   * data. The result is returned
-   * in <tt>sel_columns</tt>.
+   * This function implicitly checks the consistency of the data. The result
+   * is returned in <tt>sel_columns</tt>.
    */
   void get_selected_columns (std::vector<std::string> &sel_columns) const;
 
   /**
-   * Builtin function, that gives
-   * the number of rows in the
-   * table and that checks if the
-   * number of rows is equal in
-   * every column. This function is
-   * e.g. called before writing
-   * output.
+   * Builtin function, that gives the number of rows in the table and that
+   * checks if the number of rows is equal in every column. This function is
+   * e.g. called before writing output.
    */
   unsigned int n_rows() const;
 
   /**
-   * Stores the column and
-   * supercolumn keys in the order
-   * desired by the user.  By
-   * default this is the order of
-   * adding the columns. This order
-   * may be changed by
-   * <tt>set_column_order(...)</tt>.
+   * Stores the column and supercolumn keys in the order desired by the user.
+   * By default this is the order of adding the columns. This order may be
+   * changed by <tt>set_column_order(...)</tt>.
    */
   std::vector<std::string> column_order;
 
   /**
-   * Maps the column keys to the
-   * columns (not supercolumns).
+   * Maps the column keys to the columns (not supercolumns).
    *
-   * The field is declared mutable so
-   * that the write_text() and write_tex()
-   * functions can be const, even though they
-   * may pad columns below if auto_fill_mode
-   * is on.
+   * The field is declared mutable so that the write_text() and write_tex()
+   * functions can be const, even though they may pad columns below if
+   * auto_fill_mode is on.
    */
   mutable std::map<std::string,Column> columns;
 
   /**
-   * Maps each supercolumn key to
-   * the the keys of its subcolumns
-   * in the right order.  It is
-   * allowed that a supercolumn has
-   * got the same key as a column.
+   * Maps each supercolumn key to the the keys of its subcolumns in the right
+   * order.  It is allowed that a supercolumn has got the same key as a
+   * column.
    *
-   * Note that we do not use a <tt>multimap</tt>
-   * here since the order of column
-   * keys for each supercolumn key is
-   * relevant.
+   * Note that we do not use a <tt>multimap</tt> here since the order of
+   * column keys for each supercolumn key is relevant.
    */
   std::map<std::string, std::vector<std::string> > supercolumns;
 
   /**
-   * Maps the supercolumn keys to
-   * the captions of the
-   * supercolumns that are used in
-   * tex output.
+   * Maps the supercolumn keys to the captions of the supercolumns that are
+   * used in tex output.
    *
-   * By default these are just the
-   * supercolumn keys but they may
-   * be changed by
+   * By default these are just the supercolumn keys but they may be changed by
    * <tt>set_tex_supercaptions(...)</tt>.
    */
   std::map<std::string, std::string> tex_supercaptions;
index 8e24045b89885116e40c27df091b670131677b4d..a9e024f66576f2123aa3d798ee466a2839809e32 100644 (file)
@@ -41,40 +41,34 @@ class TableIndicesBase
 {
 public:
   /**
-   * Access the value of the
-   * <tt>i</tt>th index.
+   * Access the value of the <tt>i</tt>th index.
    */
   unsigned int operator[] (const unsigned int i) const;
 
   /**
-   * Write access the value of the
-   * <tt>i</tt>th index.
+   * Write access the value of the <tt>i</tt>th index.
    */
   unsigned int &operator[] (const unsigned int i);
 
   /**
-   * Compare two index fields for
-   * equality.
+   * Compare two index fields for equality.
    */
   bool operator == (const TableIndicesBase<N> &other) const;
 
   /**
-   * Compare two index fields for
-   * inequality.
+   * Compare two index fields for inequality.
    */
   bool operator != (const TableIndicesBase<N> &other) const;
 
   /**
-   * Sort the indices in ascending
-   * order. While this operation is not
-   * very useful for Table objects, it is
-   * used for the SymmetricTensor class.
+   * Sort the indices in ascending order. While this operation is not very
+   * useful for Table objects, it is used for the SymmetricTensor class.
    */
   void sort ();
 
   /**
-   * Write or read the data of this object to or
-   * from a stream for the purpose of serialization.
+   * Write or read the data of this object to or from a stream for the purpose
+   * of serialization.
    */
   template <class Archive>
   void serialize (Archive &ar, const unsigned int version);
@@ -88,16 +82,14 @@ protected:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the general template, and has no implementation. There are
- * a number of specializations that are actually implemented (one for
- * each used value of <tt>N</tt>), which only differ in the way they
- * implement their constructors (they take <tt>N</tt> arguments, something
- * that cannot be represented by a general template). Actual storage
- * of and access to data is done by the TableIndicesBase base
- * class of a specializations.
+ * This is the general template, and has no implementation. There are a number
+ * of specializations that are actually implemented (one for each used value
+ * of <tt>N</tt>), which only differ in the way they implement their
+ * constructors (they take <tt>N</tt> arguments, something that cannot be
+ * represented by a general template). Actual storage of and access to data is
+ * done by the TableIndicesBase base class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -106,15 +98,12 @@ template <int N>
 class TableIndices : public TableIndicesBase<N>
 {
   /**
-   * Standard constructor, setting
-   * all indices to zero.
+   * Standard constructor, setting all indices to zero.
    */
   TableIndices();
   /**
-   * The actual constructor, taking
-   * @p N arguments of type
-   * <tt>unsigned int</tt> to
-   * initialize the index object.
+   * The actual constructor, taking @p N arguments of type <tt>unsigned
+   * int</tt> to initialize the index object.
    */
   TableIndices(...);
 };
@@ -122,14 +111,12 @@ class TableIndices : public TableIndicesBase<N>
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a one-dimensional table, i.e. a
- * vector. This class only differs in the non-default constructors
- * from the other specializations. Actual storage of and access to
- * data is done by the TableIndicesBase base class of a
- * specializations.
+ * This is the specialization for a one-dimensional table, i.e. a vector. This
+ * class only differs in the non-default constructors from the other
+ * specializations. Actual storage of and access to data is done by the
+ * TableIndicesBase base class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -139,14 +126,12 @@ class TableIndices<1> : public TableIndicesBase<1>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    */
   TableIndices (const unsigned int index1);
 };
@@ -155,13 +140,12 @@ public:
 //the constructors into the class template
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a two-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a two-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -171,25 +155,17 @@ class TableIndices<2> : public TableIndicesBase<2>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int);
@@ -198,13 +174,12 @@ public:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a three-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a three-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002
@@ -214,25 +189,17 @@ class TableIndices<3> : public TableIndicesBase<3>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int,
@@ -241,13 +208,12 @@ public:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a four-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a four-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -257,25 +223,17 @@ class TableIndices<4> : public TableIndicesBase<4>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int,
@@ -285,13 +243,12 @@ public:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a five-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a five-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -301,25 +258,17 @@ class TableIndices<5> : public TableIndicesBase<5>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int,
@@ -330,13 +279,12 @@ public:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a six-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a six-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, Ralf Hartmann 2002
@@ -346,25 +294,17 @@ class TableIndices<6> : public TableIndicesBase<6>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int,
@@ -376,13 +316,12 @@ public:
 
 
 /**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
  *
- * This is the specialization for a seven-dimensional table. This
- * class only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a seven-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
  *
  * @ingroup data
  * @author Wolfgang Bangerth, 2002, Ralf Hartmann 2004
@@ -392,25 +331,17 @@ class TableIndices<7> : public TableIndicesBase<7>
 {
 public:
   /**
-   * Default constructor. Set all
-   * indices to zero.
+   * Default constructor. Set all indices to zero.
    */
   TableIndices ();
 
   /**
-   * Constructor. Set indices to
-   * the given values.
+   * Constructor. Set indices to the given values.
    *
-   * The default values for the
-   * second and subsequent
-   * arguments are necessary for
-   * some neat template tricks in
-   * SymmetricTensor where we only
-   * want to set the first index
-   * and construct the subsequent
-   * ones later on, i.e. for the
-   * moment we don't care about the
-   * later indices.
+   * The default values for the second and subsequent arguments are necessary
+   * for some neat template tricks in SymmetricTensor where we only want to
+   * set the first index and construct the subsequent ones later on, i.e. for
+   * the moment we don't care about the later indices.
    */
   TableIndices (const unsigned int index1,
                 const unsigned int index2 = numbers::invalid_unsigned_int,
index af080c4dcc6ae58541a436685a1f4f5566465b3a..4bc75b0ee8858306c642e23f2e691108dcb5edc5 100644 (file)
@@ -25,32 +25,31 @@ template <bool, typename> struct constraint_and_return_value;
 
 
 /**
- * This specialization of the general template for the case of a
- * <tt>true</tt> first template argument declares a local typedef <tt>type</tt>
- * to the second template argument. It is used in order to construct
- * constraints on template arguments in template (and member template)
- * functions. The negative specialization is missing.
+ * This specialization of the general template for the case of a <tt>true</tt>
+ * first template argument declares a local typedef <tt>type</tt> to the
+ * second template argument. It is used in order to construct constraints on
+ * template arguments in template (and member template) functions. The
+ * negative specialization is missing.
  *
- * Here's how the trick works, called SFINAE (substitution failure is
- * not an error): The C++ standard prescribes that a template function
- * is only considered in a call, if all parts of its signature can be
- * instantiated with the template parameter replaced by the respective
- * types/values in this particular call. Example:
+ * Here's how the trick works, called SFINAE (substitution failure is not an
+ * error): The C++ standard prescribes that a template function is only
+ * considered in a call, if all parts of its signature can be instantiated
+ * with the template parameter replaced by the respective types/values in this
+ * particular call. Example:
  * @code
  *   template <typename T>
  *   typename T::type  foo(T) {...};
  *   ...
  *   foo(1);
  * @endcode
- * The compiler should detect that in this call, the template
- * parameter T must be identified with the type "int". However,
- * the return type T::type does not exist. The trick now is
- * that this is not considered an error: this template is simply
- * not considered, the compiler keeps on looking for another
- * possible function foo.
+ * The compiler should detect that in this call, the template parameter T must
+ * be identified with the type "int". However, the return type T::type does
+ * not exist. The trick now is that this is not considered an error: this
+ * template is simply not considered, the compiler keeps on looking for
+ * another possible function foo.
  *
- * The idea is then to make the return type un-instantiatable if
- * certain constraints on the template types are not satisfied:
+ * The idea is then to make the return type un-instantiatable if certain
+ * constraints on the template types are not satisfied:
  * @code
  *   template <bool, typename> struct constraint_and_return_value;
  *   template <typename T> struct constraint_and_return_value<true,T> {
@@ -72,11 +71,11 @@ template <bool, typename> struct constraint_and_return_value;
  *   typename constraint_and_return_value<int_or_double<T>::value,void>::type
  *   f (T);
  * @endcode
- * which can only be instantiated if T=int or T=double. A call to
- * f('c') will just fail with a compiler error: "no instance of
- * f(char) found". On the other hand, if the predicate in the first
- * argument to the constraint_and_return_value template is true, then
- * the return type is just the second type in the template.
+ * which can only be instantiated if T=int or T=double. A call to f('c') will
+ * just fail with a compiler error: "no instance of f(char) found". On the
+ * other hand, if the predicate in the first argument to the
+ * constraint_and_return_value template is true, then the return type is just
+ * the second type in the template.
  *
  * @author Wolfgang Bangerth, 2003
  */
@@ -95,14 +94,14 @@ template <typename T> struct constraint_and_return_value<true,T>
  *   template <typename T> void f(T, T);
  * @endcode
  * then it can't be called in an expression like <code>f(1, 3.141)</code>
- * because the type <code>T</code> of the template can not be deduced
- * in a unique way from the types of the arguments. However, if the
- * template is written as
+ * because the type <code>T</code> of the template can not be deduced in a
+ * unique way from the types of the arguments. However, if the template is
+ * written as
  * @code
  *   template <typename T> void f(T, typename identity<T>::type);
  * @endcode
- * then the call becomes valid: the type <code>T</code> is not deducible
- * from the second argument to the function, so only the first argument
+ * then the call becomes valid: the type <code>T</code> is not deducible from
+ * the second argument to the function, so only the first argument
  * participates in template type resolution.
  *
  * The context for this feature is as follows: consider
@@ -121,9 +120,9 @@ template <typename T> struct constraint_and_return_value<true,T>
  * template type <code>A</code> should be <code>double</code> (from the
  * signature of the function given as first argument to
  * <code>forward_call</code>, or <code>int</code> because the expression
- * <code>1</code> has that type. Of course, what we would like the compiler
- * to do is simply cast the <code>1</code> to <code>double</code>. We can
- * achieve this by writing the code as follows:
+ * <code>1</code> has that type. Of course, what we would like the compiler to
+ * do is simply cast the <code>1</code> to <code>double</code>. We can achieve
+ * this by writing the code as follows:
  * @code
  * template <typename RT, typename A>
  * void forward_call(RT (*p) (A), typename identity<A>::type a)  { p(a); }
@@ -167,21 +166,17 @@ struct identity
 struct PointerComparison
 {
   /**
-   * Comparison function for pointers of
-   * the same type. Returns @p true if the
+   * Comparison function for pointers of the same type. Returns @p true if the
    * two pointers are equal.
    */
   template <typename T>
   static bool equal (const T *p1, const T *p2);
 
   /**
-   * Comparison function for pointers of
-   * different types. The C++ language does
-   * not allow comparing these pointers
-   * using <tt>operator==</tt>. However,
-   * since the two pointers have different
-   * types, we know that they can't be the
-   * same, so we always return @p false.
+   * Comparison function for pointers of different types. The C++ language
+   * does not allow comparing these pointers using <tt>operator==</tt>.
+   * However, since the two pointers have different types, we know that they
+   * can't be the same, so we always return @p false.
    */
   template <typename T, typename U>
   static bool equal (const T *, const U *);
@@ -192,8 +187,8 @@ struct PointerComparison
 namespace internal
 {
   /**
-   * A type that is sometimes used for template tricks. For example, in
-   * some situations one would like to do this:
+   * A type that is sometimes used for template tricks. For example, in some
+   * situations one would like to do this:
    *
    * @code
    *   template <int dim>
@@ -214,8 +209,8 @@ namespace internal
    * @endcode
    *
    * The problem is: the language doesn't allow us to specialize
-   * <code>X::f()</code> without specializing the outer class first. One
-   * of the common tricks is therefore to use something like this:
+   * <code>X::f()</code> without specializing the outer class first. One of
+   * the common tricks is therefore to use something like this:
    *
    * @code
    *   template <int N> struct int2type {};
@@ -243,9 +238,9 @@ namespace internal
    * @endcode
    *
    * Note that we have replaced specialization of <code>X::f()</code> by
-   * overloading, but that from inside the function <code>g()</code>, we
-   * can still select which of the different <code>X::f()</code> we want
-   * based on the <code>subdim</code> template argument.
+   * overloading, but that from inside the function <code>g()</code>, we can
+   * still select which of the different <code>X::f()</code> we want based on
+   * the <code>subdim</code> template argument.
    *
    * @author Wolfgang Bangerth, 2006
    */
@@ -267,8 +262,8 @@ namespace internal
 
 
 /**
- * A type that can be used to determine whether two types are equal.
- * It allows to write code like
+ * A type that can be used to determine whether two types are equal. It allows
+ * to write code like
  * @code
  *   template <typename T>
  *   void Vector<T>::some_operation () {
@@ -290,9 +285,9 @@ struct types_are_equal
 
 
 /**
- * Partial specialization of the general template for the case that
- * both template arguments are equal. See the documentation of the
- * general template for more information.
+ * Partial specialization of the general template for the case that both
+ * template arguments are equal. See the documentation of the general template
+ * for more information.
  */
 template <typename T>
 struct types_are_equal<T,T>
index 8f60a691398334f6944eec91027a390b4820bbcb..88eea12d674af7ede57e4b8c51cf7c03ebd11475 100644 (file)
@@ -26,17 +26,16 @@ template <int rank_, int dim, typename Number> class Tensor;
 template <int dim, typename Number> class Tensor<1,dim,Number>;
 
 /**
- * Provide a general tensor class with an arbitrary rank, i.e. with
- * an arbitrary number of indices. The Tensor class provides an
- * indexing operator and a bit of infrastructure, but most
- * functionality is recursively handed down to tensors of rank 1 or
- * put into external templated functions, e.g. the <tt>contract</tt> family.
- *
- * Using this tensor class for objects of rank 2 has advantages over
- * matrices in many cases since the dimension is known to the compiler
- * as well as the location of the data. It is therefore possible to
- * produce far more efficient code than for matrices with
- * runtime-dependent dimension.
+ * Provide a general tensor class with an arbitrary rank, i.e. with an
+ * arbitrary number of indices. The Tensor class provides an indexing operator
+ * and a bit of infrastructure, but most functionality is recursively handed
+ * down to tensors of rank 1 or put into external templated functions, e.g.
+ * the <tt>contract</tt> family.
+ *
+ * Using this tensor class for objects of rank 2 has advantages over matrices
+ * in many cases since the dimension is known to the compiler as well as the
+ * location of the data. It is therefore possible to produce far more
+ * efficient code than for matrices with runtime-dependent dimension.
  *
  * This class provides an optional template argument for the type of the
  * underlying data. It defaults to @p double values. It can be used to base
@@ -51,89 +50,65 @@ class Tensor
 {
 public:
   /**
-   * Provide a way to get the
-   * dimension of an object without
-   * explicit knowledge of it's
-   * data type. Implementation is
-   * this way instead of providing
-   * a function <tt>dimension()</tt>
-   * because now it is possible to
-   * get the dimension at compile
-   * time without the expansion and
-   * preevaluation of an inlined
-   * function; the compiler may
-   * therefore produce more
-   * efficient code and you may use
-   * this value to declare other
-   * data types.
+   * Provide a way to get the dimension of an object without explicit
+   * knowledge of it's data type. Implementation is this way instead of
+   * providing a function <tt>dimension()</tt> because now it is possible to
+   * get the dimension at compile time without the expansion and preevaluation
+   * of an inlined function; the compiler may therefore produce more efficient
+   * code and you may use this value to declare other data types.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Publish the rank of this tensor to
-   * the outside world.
+   * Publish the rank of this tensor to the outside world.
    */
   static const unsigned int rank      = rank_;
 
   /**
-   * Number of independent components of a
-   * tensor of current rank. This is dim times the
-   * number of independent components of each sub-tensor.
+   * Number of independent components of a tensor of current rank. This is dim
+   * times the number of independent components of each sub-tensor.
    */
   static const unsigned int
   n_independent_components = Tensor<rank_-1,dim>::n_independent_components *dim;
 
   /**
-   * Type of stored objects. This
-   * is a tensor of lower rank.
+   * Type of stored objects. This is a tensor of lower rank.
    */
   typedef Tensor<rank_-1,dim,Number> value_type;
 
   /**
-   * Declare a type that has holds
-   * real-valued numbers with the same
-   * precision as the template argument to
-   * this class. For std::complex<number>,
-   * this corresponds to type number, and
-   * it is equal to Number for all other
-   * cases. See also the respective field
-   * in Vector<Number>.
+   * Declare a type that has holds real-valued numbers with the same precision
+   * as the template argument to this class. For std::complex<number>, this
+   * corresponds to type number, and it is equal to Number for all other
+   * cases. See also the respective field in Vector<Number>.
    *
-   * This typedef is used to
-   * represent the return type of
-   * norms.
+   * This typedef is used to represent the return type of norms.
    */
   typedef typename numbers::NumberTraits<Number>::real_type real_type;
 
   /**
-   * Declare an array type which
-   * can be used to initialize an
-   * object of this type
-   * statically.
+   * Declare an array type which can be used to initialize an object of this
+   * type statically.
    */
   typedef typename Tensor<rank_-1,dim,Number>::array_type array_type[dim];
 
   /**
-   * Constructor. Initialize all entries
-   * to zero.
+   * Constructor. Initialize all entries to zero.
    */
   Tensor ();
 
   /**
-   * Copy constructor, where the data is
-   * copied from a C-style array.
+   * Copy constructor, where the data is copied from a C-style array.
    */
   Tensor (const array_type &initializer);
 
   /**
-   * Conversion operator from tensor of
-   * tensors.
+   * Conversion operator from tensor of tensors.
    */
   Tensor (const Tensor<1,dim,Tensor<rank_-1,dim,Number> > &tensor_in);
 
   /**
-   * Conversion operator to tensor of
-   * tensors.
+   * Conversion operator to tensor of tensors.
    */
   operator Tensor<1,dim,Tensor<rank_-1,dim,Number> > () const;
 
@@ -158,125 +133,102 @@ public:
   Number &operator [](const TableIndices<rank_> &indices);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   Tensor &operator = (const Tensor<rank_,dim,Number> &);
 
   /**
-   * This operator assigns a scalar
-   * to a tensor. To avoid
-   * confusion with what exactly it
-   * means to assign a scalar value
-   * to a tensor, zero is the only
-   * value allowed for <tt>d</tt>,
-   * allowing the intuitive
-   * notation <tt>t=0</tt> to reset
-   * all elements of the tensor to
-   * zero.
+   * This operator assigns a scalar to a tensor. To avoid confusion with what
+   * exactly it means to assign a scalar value to a tensor, zero is the only
+   * value allowed for <tt>d</tt>, allowing the intuitive notation
+   * <tt>t=0</tt> to reset all elements of the tensor to zero.
    */
   Tensor<rank_,dim,Number> &operator = (const Number d);
 
   /**
-   *  Test for equality of two tensors.
+   * Test for equality of two tensors.
    */
   bool operator == (const Tensor<rank_,dim,Number> &) const;
 
   /**
-   *  Test for inequality of two tensors.
+   * Test for inequality of two tensors.
    */
   bool operator != (const Tensor<rank_,dim,Number> &) const;
 
   /**
-   *  Add another tensor.
+   * Add another tensor.
    */
   Tensor<rank_,dim,Number> &operator += (const Tensor<rank_,dim,Number> &);
 
   /**
-   *  Subtract another tensor.
+   * Subtract another tensor.
    */
   Tensor<rank_,dim,Number> &operator -= (const Tensor<rank_,dim,Number> &);
 
   /**
-   *  Scale the tensor by <tt>factor</tt>,
-   *  i.e. multiply all components by
-   *  <tt>factor</tt>.
+   * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
+   * <tt>factor</tt>.
    */
   Tensor<rank_,dim,Number> &operator *= (const Number factor);
 
   /**
-   *  Scale the vector by
-   *  <tt>1/factor</tt>.
+   * Scale the vector by <tt>1/factor</tt>.
    */
   Tensor<rank_,dim,Number> &operator /= (const Number factor);
 
   /**
-   *  Add two tensors. If possible, you
-   *  should use <tt>operator +=</tt>
-   *  instead since this does not need the
-   *  creation of a temporary.
+   * Add two tensors. If possible, you should use <tt>operator +=</tt> instead
+   * since this does not need the creation of a temporary.
    */
   Tensor<rank_,dim,Number>   operator + (const Tensor<rank_,dim,Number> &) const;
 
   /**
-   *  Subtract two tensors. If possible,
-   *  you should use <tt>operator -=</tt>
-   *  instead since this does not need the
-   *  creation of a temporary.
+   * Subtract two tensors. If possible, you should use <tt>operator -=</tt>
+   * instead since this does not need the creation of a temporary.
    */
   Tensor<rank_,dim,Number>   operator - (const Tensor<rank_,dim,Number> &) const;
 
   /**
-   * Unary minus operator. Negate all
-   * entries of a tensor.
+   * Unary minus operator. Negate all entries of a tensor.
    */
   Tensor<rank_,dim,Number>   operator - () const;
 
   /**
-   * Return the Frobenius-norm of a tensor,
-   * i.e. the square root of the sum of
+   * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
    * squares of all entries.
    */
   real_type norm () const;
 
   /**
-   * Return the square of the
-   * Frobenius-norm of a tensor,
-   * i.e. the
-   * sum of squares of all entries.
+   * Return the square of the Frobenius-norm of a tensor, i.e. the sum of
+   * squares of all entries.
    *
-   * This function mainly exists
-   * because it makes computing the
-   * norm simpler recursively, but
-   * may also be useful in other
-   * contexts.
+   * This function mainly exists because it makes computing the norm simpler
+   * recursively, but may also be useful in other contexts.
    */
   real_type norm_square () const;
 
   /**
    * Fill a vector with all tensor elements.
    *
-   * This function unrolls all
-   * tensor entries into a single,
-   * linearly numbered vector. As
-   * usual in C++, the rightmost
-   * index of the tensor marches fastest.
+   * This function unrolls all tensor entries into a single, linearly numbered
+   * vector. As usual in C++, the rightmost index of the tensor marches
+   * fastest.
    */
   template <typename Number2>
   void unroll (Vector<Number2> &result) const;
 
   /**
-   * Returns an unrolled index in
-   * the range [0,dim^rank-1] for the element of the tensor indexed by
-   * the argument to the function.
+   * Returns an unrolled index in the range [0,dim^rank-1] for the element of
+   * the tensor indexed by the argument to the function.
    */
   static
   unsigned int
   component_to_unrolled_index(const TableIndices<rank_> &indices);
 
   /**
-   * Opposite of  component_to_unrolled_index: For an index in the
-   * range [0,dim^rank-1], return which set of indices it would
-   * correspond to.
+   * Opposite of  component_to_unrolled_index: For an index in the range
+   * [0,dim^rank-1], return which set of indices it would correspond to.
    */
   static
   TableIndices<rank_> unrolled_to_component_indices(const unsigned int i);
@@ -286,27 +238,20 @@ public:
   /**
    * Reset all values to zero.
    *
-   * Note that this is partly inconsistent
-   * with the semantics of the @p clear()
-   * member functions of the STL and of
-   * several other classes within deal.II
-   * which not only reset the values of
-   * stored elements to zero, but release
-   * all memory and return the object into
-   * a virginial state. However, since the
-   * size of objects of the present type is
-   * determined by its template parameters,
-   * resizing is not an option, and indeed
-   * the state where all elements have a
-   * zero value is the state right after
+   * Note that this is partly inconsistent with the semantics of the @p
+   * clear() member functions of the STL and of several other classes within
+   * deal.II which not only reset the values of stored elements to zero, but
+   * release all memory and return the object into a virginial state. However,
+   * since the size of objects of the present type is determined by its
+   * template parameters, resizing is not an option, and indeed the state
+   * where all elements have a zero value is the state right after
    * construction of such an object.
    */
   void clear ();
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   static std::size_t memory_consumption ();
 
@@ -318,16 +263,15 @@ public:
                   << "Invalid tensor index " << arg1);
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
 
 private:
   /**
-   * Array of tensors holding the
-   * subelements.
+   * Array of tensors holding the subelements.
    */
   Tensor<rank_-1,dim,Number> subtensor[dim];
 
@@ -712,9 +656,9 @@ Tensor<rank_,dim,Number>::serialize(Archive &ar, const unsigned int)
 
 
 /**
- * Output operator for tensors. Print the elements consecutively, with
- * a space in between, two spaces between rank 1 subtensors, three
- * between rank 2 and so on.
+ * Output operator for tensors. Print the elements consecutively, with a space
+ * in between, two spaces between rank 1 subtensors, three between rank 2 and
+ * so on.
  *
  * @relates Tensor
  */
@@ -767,17 +711,16 @@ Number contract (const Tensor<1,dim,Number> &src1,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -793,8 +736,8 @@ operator * (const Tensor<1,dim,Number> &src1,
 
 
 /**
- * Double contract two tensors of rank 2, thus computing the Frobenius
- * inner product <tt> sum<sub>i,j</sub> src1[i][j]*src2[i][j]</tt>.
+ * Double contract two tensors of rank 2, thus computing the Frobenius inner
+ * product <tt> sum<sub>i,j</sub> src1[i][j]*src2[i][j]</tt>.
  *
  * @relates Tensor
  * @author Guido Kanschat, 2000
@@ -835,17 +778,16 @@ void contract (Tensor<1,dim,Number>       &dest,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -889,17 +831,16 @@ void contract (Tensor<1,dim,Number>       &dest,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -946,17 +887,16 @@ void contract (Tensor<2,dim,Number>       &dest,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -977,15 +917,15 @@ operator * (const Tensor<2,dim,Number> &src1,
 
 
 /**
- * Contract a tensor of rank 2 with a tensor of rank 2. The
- * contraction is performed over index <tt>index1</tt> of the first tensor,
- * and <tt>index2</tt> of the second tensor. Thus, if <tt>index1==2</tt>,
- * <tt>index2==1</tt>, the result is the usual contraction, but if for
- * example <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
- * <tt>dest[i][k] = sum_j src1[j][i] src2[k][j]</tt>.
+ * Contract a tensor of rank 2 with a tensor of rank 2. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor, and
+ * <tt>index2</tt> of the second tensor. Thus, if <tt>index1==2</tt>,
+ * <tt>index2==1</tt>, the result is the usual contraction, but if for example
+ * <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is <tt>dest[i][k] =
+ * sum_j src1[j][i] src2[k][j]</tt>.
  *
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 1998
@@ -1050,12 +990,11 @@ void contract (Tensor<2,dim,Number>       &dest,
 
 
 /**
- * Contract a tensor of rank 3 with a tensor of rank 1. The
- * contraction is performed over index <tt>index1</tt> of the first
- * tensor.
+ * Contract a tensor of rank 3 with a tensor of rank 1. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor.
  *
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 1998
@@ -1121,15 +1060,15 @@ void contract (Tensor<3,dim,Number>       &dest,
 
 
 /**
- * Contract a tensor of rank 3 with a tensor of rank 2. The
- * contraction is performed over index <tt>index1</tt> of the first tensor,
- * and <tt>index2</tt> of the second tensor. Thus, if <tt>index1==3</tt>,
- * <tt>index2==1</tt>, the result is the usual contraction, but if for
- * example <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
+ * Contract a tensor of rank 3 with a tensor of rank 2. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor, and
+ * <tt>index2</tt> of the second tensor. Thus, if <tt>index1==3</tt>,
+ * <tt>index2==1</tt>, the result is the usual contraction, but if for example
+ * <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
  * <tt>dest[i][j][k] = sum_l src1[l][i][j] src2[k][l]</tt>.
  *
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
  *
  * @relates Tensor
  */
@@ -1220,17 +1159,16 @@ void contract (Tensor<3,dim,Number>       &dest,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -1274,17 +1212,16 @@ void contract (Tensor<3,dim,Number>       &dest,
 
 
 /**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -1331,8 +1268,8 @@ operator * (const Tensor<3,dim,Number> &src1,
 
 /**
  * Contract the last two indices of <tt>src1</tt> with the two indices
- * <tt>src2</tt>, creating a rank-2 tensor. This is the matrix-vector
- * product analog operation between tensors of rank 4 and rank 2.
+ * <tt>src2</tt>, creating a rank-2 tensor. This is the matrix-vector product
+ * analog operation between tensors of rank 4 and rank 2.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2005
@@ -1445,8 +1382,8 @@ contract3 (const Tensor<2,dim,Number> &t1,
 
 
 /**
- * Form the outer product of two tensors of rank 1 and 1, i.e.
- * <tt>dst[i][j] = src1[i] * src2[j]</tt>.
+ * Form the outer product of two tensors of rank 1 and 1, i.e. <tt>dst[i][j] =
+ * src1[i] * src2[j]</tt>.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2000
@@ -1501,12 +1438,11 @@ void outer_product (Tensor<3,dim,Number>       &dst,
 
 
 /**
- * Form the outer product of two tensors of rank 0 and 1, i.e.
- * <tt>dst[i] = src1 * src2[i]</tt>. Of course, this is only a scaling of
- * <tt>src2</tt>, but we consider this an outer product for completeness of
- * these functions and since this is sometimes needed when writing
- * templates that depend on the rank of a tensor, which may sometimes
- * be zero (i.e. a scalar).
+ * Form the outer product of two tensors of rank 0 and 1, i.e. <tt>dst[i] =
+ * src1 * src2[i]</tt>. Of course, this is only a scaling of <tt>src2</tt>,
+ * but we consider this an outer product for completeness of these functions
+ * and since this is sometimes needed when writing templates that depend on
+ * the rank of a tensor, which may sometimes be zero (i.e. a scalar).
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2000
@@ -1523,12 +1459,11 @@ void outer_product (Tensor<1,dim,Number>       &dst,
 
 
 /**
- * Form the outer product of two tensors of rank 1 and 0, i.e.
- * <tt>dst[i] = src1[i] * src2</tt>. Of course, this is only a scaling of
- * <tt>src1</tt>, but we consider this an outer product for completeness of
- * these functions and since this is sometimes needed when writing
- * templates that depend on the rank of a tensor, which may sometimes
- * be zero (i.e. a scalar).
+ * Form the outer product of two tensors of rank 1 and 0, i.e. <tt>dst[i] =
+ * src1[i] * src2</tt>. Of course, this is only a scaling of <tt>src1</tt>,
+ * but we consider this an outer product for completeness of these functions
+ * and since this is sometimes needed when writing templates that depend on
+ * the rank of a tensor, which may sometimes be zero (i.e. a scalar).
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2000
@@ -1544,13 +1479,12 @@ void outer_product (Tensor<1,dim,Number>       &dst,
 
 
 /**
- * Cross-product in 2d. This is just a rotation by 90 degrees
- * clockwise to compute the outer normal from a tangential
- * vector. This function is defined for all space dimensions to allow
- * for dimension independent programming (e.g. within switches over
- * the space dimenion), but may only be called if the actual dimension
- * of the arguments is two (e.g. from the <tt>dim==2</tt> case in the
- * switch).
+ * Cross-product in 2d. This is just a rotation by 90 degrees clockwise to
+ * compute the outer normal from a tangential vector. This function is defined
+ * for all space dimensions to allow for dimension independent programming
+ * (e.g. within switches over the space dimenion), but may only be called if
+ * the actual dimension of the arguments is two (e.g. from the <tt>dim==2</tt>
+ * case in the switch).
  *
  * @relates Tensor
  * @author Guido Kanschat, 2001
@@ -1569,11 +1503,11 @@ cross_product (Tensor<1,dim,Number>       &dst,
 
 
 /**
- * Cross-product of 2 vectors in 3d. This function is defined for all
- * space dimensions to allow for dimension independent programming
- * (e.g. within switches over the space dimenion), but may only be
- * called if the actual dimension of the arguments is three (e.g. from
- * the <tt>dim==3</tt> case in the switch).
+ * Cross-product of 2 vectors in 3d. This function is defined for all space
+ * dimensions to allow for dimension independent programming (e.g. within
+ * switches over the space dimenion), but may only be called if the actual
+ * dimension of the arguments is three (e.g. from the <tt>dim==3</tt> case in
+ * the switch).
  *
  * @relates Tensor
  * @author Guido Kanschat, 2001
@@ -1618,9 +1552,8 @@ scalar_product (const Tensor<2,dim,Number> &t1,
 
 
 /**
- * Compute the determinant of a tensor of arbitrary rank and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of arbitrary rank and dimension one.
+ * Since this is a number, the return value is, of course, the number itself.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 1998
@@ -1635,9 +1568,8 @@ Number determinant (const Tensor<rank,1,Number> &t)
 
 
 /**
- * Compute the determinant of a tensor of rank one and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of rank one and dimension one. Since
+ * this is a number, the return value is, of course, the number itself.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 1998
@@ -1651,9 +1583,8 @@ Number determinant (const Tensor<1,1,Number> &t)
 
 
 /**
- * Compute the determinant of a tensor of rank two and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of rank two and dimension one. Since
+ * this is a number, the return value is, of course, the number itself.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 1998
@@ -1748,8 +1679,8 @@ Number determinant (const Tensor<2,dim,Number> &t)
 
 
 /**
- * Compute and return the trace of a tensor of rank 2, i.e. the sum of
- * its diagonal entries.
+ * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
+ * diagonal entries.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2001
@@ -1766,10 +1697,10 @@ Number trace (const Tensor<2,dim,Number> &d)
 
 
 /**
- * Compute and return the inverse of the given tensor. Since the
- * compiler can perform the return value optimization, and since the
- * size of the return object is known, it is acceptable to return the
- * result by value, rather than by reference as a parameter.
+ * Compute and return the inverse of the given tensor. Since the compiler can
+ * perform the return value optimization, and since the size of the return
+ * object is known, it is acceptable to return the result by value, rather
+ * than by reference as a parameter.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2000
@@ -1835,11 +1766,11 @@ invert (const Tensor<2,dim,Number> &t)
 
 
 /**
- * Return the transpose of the given tensor. Since the compiler can
- * perform the return value optimization, and since the size of the
- * return object is known, it is acceptable to return the result by
- * value, rather than by reference as a parameter. Note that there are
- * specializations of this function for <tt>dim==1,2,3</tt>.
+ * Return the transpose of the given tensor. Since the compiler can perform
+ * the return value optimization, and since the size of the return object is
+ * known, it is acceptable to return the result by value, rather than by
+ * reference as a parameter. Note that there are specializations of this
+ * function for <tt>dim==1,2,3</tt>.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2002
@@ -1865,8 +1796,8 @@ transpose (const Tensor<2,dim,Number> &t)
 #ifndef DOXYGEN
 
 /**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==1</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==1</tt>.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2002
@@ -1883,8 +1814,8 @@ transpose (const Tensor<2,1,Number> &t)
 
 
 /**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==2</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==2</tt>.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2002
@@ -1902,8 +1833,8 @@ transpose (const Tensor<2,2,Number> &t)
 
 
 /**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==3</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==3</tt>.
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2002
@@ -1924,9 +1855,8 @@ transpose (const Tensor<2,3,Number> &t)
 
 
 /**
- * Return the $l_1$ norm of the given rank-2 tensor, where
- * $||t||_1 = \max_j \sum_i |t_{ij}|$ (maximum of
- * the sums over columns).
+ * Return the $l_1$ norm of the given rank-2 tensor, where $||t||_1 = \max_j
+ * \sum_i |t_{ij}|$ (maximum of the sums over columns).
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2012
@@ -1953,9 +1883,8 @@ l1_norm (const Tensor<2,dim,Number> &t)
 
 
 /**
- * Return the $l_\infty$ norm of the given rank-2 tensor, where
- * $||t||_\infty = \max_i \sum_j |t_{ij}|$ (maximum of
- * the sums over rows).
+ * Return the $l_\infty$ norm of the given rank-2 tensor, where $||t||_\infty
+ * = \max_i \sum_j |t_{ij}|$ (maximum of the sums over rows).
  *
  * @relates Tensor
  * @author Wolfgang Bangerth, 2012
@@ -1982,8 +1911,8 @@ linfty_norm (const Tensor<2,dim,Number> &t)
 
 
 /**
- * Multiplication of a tensor of general rank with a scalar Number
- * from the right.
+ * Multiplication of a tensor of general rank with a scalar Number from the
+ * right.
  *
  * @relates Tensor
  */
@@ -2001,8 +1930,8 @@ operator * (const Tensor<rank,dim,Number> &t,
 
 
 /**
- * Multiplication of a tensor of general rank with a scalar Number
- * from the left.
+ * Multiplication of a tensor of general rank with a scalar Number from the
+ * left.
  *
  * @relates Tensor
  */
@@ -2039,8 +1968,8 @@ operator / (const Tensor<rank,dim,Number> &t,
 
 
 /**
- * Multiplication of a tensor of general rank with a scalar double
- * from the right.
+ * Multiplication of a tensor of general rank with a scalar double from the
+ * right.
  *
  * @relates Tensor
  */
@@ -2058,8 +1987,8 @@ operator * (const Tensor<rank,dim> &t,
 
 
 /**
- * Multiplication of a tensor of general rank with a scalar double
- * from the left.
+ * Multiplication of a tensor of general rank with a scalar double from the
+ * left.
  *
  * @relates Tensor
  */
@@ -2095,8 +2024,8 @@ operator / (const Tensor<rank,dim> &t,
 
 
 /**
- * Multiplication of a tensor of general rank by a scalar
- * complex<double> from the left.
+ * Multiplication of a tensor of general rank by a scalar complex<double> from
+ * the left.
  *
  * @relates Tensor
  */
@@ -2115,8 +2044,8 @@ operator * (const std::complex<double>  factor,
 
 
 /**
- * Multiplication of a tensor of general rank by a scalar
- * complex<double> from the right.
+ * Multiplication of a tensor of general rank by a scalar complex<double> from
+ * the right.
  *
  * @relates Tensor
  */
index 19800c9d899b0712d7e4b1a6d54c63cef266d368..d7a9509f8eaa52aced6b79805653614c62dbf7da 100644 (file)
@@ -55,12 +55,12 @@ template <int dim, typename Number> class Tensor<1,dim,Number>;
  * class. It handles tensors of rank zero, i.e. scalars. The second template
  * argument is ignored.
  *
- * This class exists because in some cases we want to construct
- * objects of type Tensor@<spacedim-dim,dim,Number@>, which should expand to
- * scalars, vectors, matrices, etc, depending on the values of the
- * template arguments @p dim and @p spacedim. We therefore need a
- * class that acts as a scalar (i.e. @p Number) for all purposes but
- * is part of the Tensor template family.
+ * This class exists because in some cases we want to construct objects of
+ * type Tensor@<spacedim-dim,dim,Number@>, which should expand to scalars,
+ * vectors, matrices, etc, depending on the values of the template arguments
+ * @p dim and @p spacedim. We therefore need a class that acts as a scalar
+ * (i.e. @p Number) for all purposes but is part of the Tensor template
+ * family.
  *
  * @ingroup geomprimitives
  * @author Wolfgang Bangerth, 2009
@@ -70,50 +70,33 @@ class Tensor<0,dim,Number>
 {
 public:
   /**
-   * Provide a way to get the
-   * dimension of an object without
-   * explicit knowledge of it's
-   * data type. Implementation is
-   * this way instead of providing
-   * a function <tt>dimension()</tt>
-   * because now it is possible to
-   * get the dimension at compile
-   * time without the expansion and
-   * preevaluation of an inlined
-   * function; the compiler may
-   * therefore produce more
-   * efficient code and you may use
-   * this value to declare other
-   * data types.
+   * Provide a way to get the dimension of an object without explicit
+   * knowledge of it's data type. Implementation is this way instead of
+   * providing a function <tt>dimension()</tt> because now it is possible to
+   * get the dimension at compile time without the expansion and preevaluation
+   * of an inlined function; the compiler may therefore produce more efficient
+   * code and you may use this value to declare other data types.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Publish the rank of this tensor to
-   * the outside world.
+   * Publish the rank of this tensor to the outside world.
    */
   static const unsigned int rank      = 0;
 
   /**
-   * Type of stored objects. This
-   * is a Number for a rank 1 tensor.
+   * Type of stored objects. This is a Number for a rank 1 tensor.
    */
 
   typedef Number value_type;
 
   /**
-   * Declare a type that has holds
-   * real-valued numbers with the same
-   * precision as the template argument to
-   * this class. For std::complex<number>,
-   * this corresponds to type number, and
-   * it is equal to Number for all other
-   * cases. See also the respective field
-   * in Vector<Number>.
+   * Declare a type that has holds real-valued numbers with the same precision
+   * as the template argument to this class. For std::complex<number>, this
+   * corresponds to type number, and it is equal to Number for all other
+   * cases. See also the respective field in Vector<Number>.
    *
-   * This typedef is used to
-   * represent the return type of
-   * norms.
+   * This typedef is used to represent the return type of norms.
    */
   typedef typename numbers::NumberTraits<Number>::real_type real_type;
 
@@ -123,9 +106,7 @@ public:
   Tensor ();
 
   /**
-   * Copy constructor, where the
-   * data is copied from a C-style
-   * array.
+   * Copy constructor, where the data is copied from a C-style array.
    */
   Tensor (const value_type &initializer);
 
@@ -135,20 +116,17 @@ public:
   Tensor (const Tensor<0,dim,Number> &);
 
   /**
-   * Conversion to Number. Since
-   * rank-0 tensors are scalars,
-   * this is a natural operation.
+   * Conversion to Number. Since rank-0 tensors are scalars, this is a natural
+   * operation.
    */
   operator Number () const;
 
   /**
-   * Conversion to Number. Since
-   * rank-0 tensors are scalars,
-   * this is a natural operation.
+   * Conversion to Number. Since rank-0 tensors are scalars, this is a natural
+   * operation.
    *
-   * This is the non-const
-   * conversion operator that
-   * returns a writable reference.
+   * This is the non-const conversion operator that returns a writable
+   * reference.
    */
   operator Number &();
 
@@ -163,21 +141,17 @@ public:
   Tensor<0,dim,Number> &operator = (const Number d);
 
   /**
-   * Test for equality of two
-   * tensors.
+   * Test for equality of two tensors.
    */
   bool operator == (const Tensor<0,dim,Number> &) const;
 
   /**
-   * Test for inequality of two
-   * tensors.
+   * Test for inequality of two tensors.
    */
   bool operator != (const Tensor<0,dim,Number> &) const;
 
   /**
-   * Add another vector, i.e. move
-   * this point by the given
-   * offset.
+   * Add another vector, i.e. move this point by the given offset.
    */
   Tensor<0,dim,Number> &operator += (const Tensor<0,dim,Number> &);
 
@@ -187,9 +161,8 @@ public:
   Tensor<0,dim,Number> &operator -= (const Tensor<0,dim,Number> &);
 
   /**
-   * Scale the vector by
-   * <tt>factor</tt>, i.e. multiply all
-   * coordinates by <tt>factor</tt>.
+   * Scale the vector by <tt>factor</tt>, i.e. multiply all coordinates by
+   * <tt>factor</tt>.
    */
   Tensor<0,dim,Number> &operator *= (const Number factor);
 
@@ -199,25 +172,19 @@ public:
   Tensor<0,dim,Number> &operator /= (const Number factor);
 
   /**
-   * Returns the scalar product of
-   * two vectors.
+   * Returns the scalar product of two vectors.
    */
   Number                 operator * (const Tensor<0,dim,Number> &) const;
 
   /**
-   * Add two tensors. If possible,
-   * use <tt>operator +=</tt> instead
-   * since this does not need to
-   * copy a point at least once.
+   * Add two tensors. If possible, use <tt>operator +=</tt> instead since this
+   * does not need to copy a point at least once.
    */
   Tensor<0,dim,Number>   operator + (const Tensor<0,dim,Number> &) const;
 
   /**
-   * Subtract two tensors. If
-   * possible, use <tt>operator +=</tt>
-   * instead since this does not
-   * need to copy a point at least
-   * once.
+   * Subtract two tensors. If possible, use <tt>operator +=</tt> instead since
+   * this does not need to copy a point at least once.
    */
   Tensor<0,dim,Number>   operator - (const Tensor<0,dim,Number> &) const;
 
@@ -227,58 +194,39 @@ public:
   Tensor<0,dim,Number>   operator - () const;
 
   /**
-   * Return the Frobenius-norm of a
-   * tensor, i.e. the square root
-   * of the sum of squares of all
-   * entries. For the present case
-   * of rank-1 tensors, this equals
-   * the usual
-   * <tt>l<sub>2</sub></tt> norm of
-   * the vector.
+   * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+   * squares of all entries. For the present case of rank-1 tensors, this
+   * equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
    */
   real_type norm () const;
 
   /**
-   * Return the square of the
-   * Frobenius-norm of a tensor,
-   * i.e. the square root of the
-   * sum of squares of all entries.
+   * Return the square of the Frobenius-norm of a tensor, i.e. the square root
+   * of the sum of squares of all entries.
    *
-   * This function mainly exists
-   * because it makes computing the
-   * norm simpler recursively, but
-   * may also be useful in other
-   * contexts.
+   * This function mainly exists because it makes computing the norm simpler
+   * recursively, but may also be useful in other contexts.
    */
   real_type norm_square () const;
 
   /**
    * Reset all values to zero.
    *
-   * Note that this is partly inconsistent
-   * with the semantics of the @p clear()
-   * member functions of the STL and of
-   * several other classes within deal.II
-   * which not only reset the values of
-   * stored elements to zero, but release
-   * all memory and return the object into
-   * a virginial state. However, since the
-   * size of objects of the present type is
-   * determined by its template parameters,
-   * resizing is not an option, and indeed
-   * the state where all elements have a
-   * zero value is the state right after
+   * Note that this is partly inconsistent with the semantics of the @p
+   * clear() member functions of the STL and of several other classes within
+   * deal.II which not only reset the values of stored elements to zero, but
+   * release all memory and return the object into a virginial state. However,
+   * since the size of objects of the present type is determined by its
+   * template parameters, resizing is not an option, and indeed the state
+   * where all elements have a zero value is the state right after
    * construction of such an object.
    */
   void clear ();
 
   /**
-   * Only tensors with a positive
-   * dimension are implemented. This
-   * exception is thrown by the
-   * constructor if the template
-   * argument <tt>dim</tt> is zero or
-   * less.
+   * Only tensors with a positive dimension are implemented. This exception is
+   * thrown by the constructor if the template argument <tt>dim</tt> is zero
+   * or less.
    *
    * @ingroup Exceptions
    */
@@ -287,8 +235,8 @@ public:
                   << "dim must be positive, but was " << arg1);
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
@@ -329,84 +277,59 @@ class Tensor<1,dim,Number>
 {
 public:
   /**
-   * Provide a way to get the
-   * dimension of an object without
-   * explicit knowledge of it's
-   * data type. Implementation is
-   * this way instead of providing
-   * a function <tt>dimension()</tt>
-   * because now it is possible to
-   * get the dimension at compile
-   * time without the expansion and
-   * preevaluation of an inlined
-   * function; the compiler may
-   * therefore produce more
-   * efficient code and you may use
-   * this value to declare other
-   * data types.
+   * Provide a way to get the dimension of an object without explicit
+   * knowledge of it's data type. Implementation is this way instead of
+   * providing a function <tt>dimension()</tt> because now it is possible to
+   * get the dimension at compile time without the expansion and preevaluation
+   * of an inlined function; the compiler may therefore produce more efficient
+   * code and you may use this value to declare other data types.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Publish the rank of this tensor to
-   * the outside world.
+   * Publish the rank of this tensor to the outside world.
    */
   static const unsigned int rank      = 1;
 
   /**
-   * Number of independent components of a
-   * tensor of rank 1.
+   * Number of independent components of a tensor of rank 1.
    */
   static const unsigned int
   n_independent_components = dim;
 
   /**
-   * Type of stored objects. This
-   * is a Number for a rank 1 tensor.
+   * Type of stored objects. This is a Number for a rank 1 tensor.
    */
 
   typedef Number value_type;
 
   /**
-   * Declare a type that has holds
-   * real-valued numbers with the same
-   * precision as the template argument to
-   * this class. For std::complex<number>,
-   * this corresponds to type number, and
-   * it is equal to Number for all other
-   * cases. See also the respective field
-   * in Vector<Number>.
+   * Declare a type that has holds real-valued numbers with the same precision
+   * as the template argument to this class. For std::complex<number>, this
+   * corresponds to type number, and it is equal to Number for all other
+   * cases. See also the respective field in Vector<Number>.
    *
-   * This typedef is used to
-   * represent the return type of
-   * norms.
+   * This typedef is used to represent the return type of norms.
    */
   typedef typename numbers::NumberTraits<Number>::real_type real_type;
 
   /**
-   * Declare an array type which can
-   * be used to initialize statically
-   * an object of this type.
+   * Declare an array type which can be used to initialize statically an
+   * object of this type.
    *
-   * Avoid warning about zero-sized
-   * array for <tt>dim==0</tt> by
-   * choosing lunatic value that is
-   * likely to overflow memory
-   * limits.
+   * Avoid warning about zero-sized array for <tt>dim==0</tt> by choosing
+   * lunatic value that is likely to overflow memory limits.
    */
   typedef Number array_type[(dim!=0) ? dim : 100000000];
 
   /**
-   * Constructor. Initialize all entries
-   * to zero if <tt>initialize==true</tt>; this
-   * is the default behaviour.
+   * Constructor. Initialize all entries to zero if <tt>initialize==true</tt>;
+   * this is the default behaviour.
    */
   explicit Tensor (const bool initialize = true);
 
   /**
-   * Copy constructor, where the
-   * data is copied from a C-style
-   * array.
+   * Copy constructor, where the data is copied from a C-style array.
    */
   Tensor (const array_type &initializer);
 
@@ -416,26 +339,18 @@ public:
   Tensor (const Tensor<1,dim,Number> &);
 
   /**
-   * Read access to the <tt>index</tt>th
-   * coordinate.
+   * Read access to the <tt>index</tt>th coordinate.
    *
-   * Note that the derived
-   * <tt>Point</tt> class also provides
-   * access through the <tt>()</tt>
-   * operator for
-   * backcompatibility.
+   * Note that the derived <tt>Point</tt> class also provides access through
+   * the <tt>()</tt> operator for backcompatibility.
    */
   Number   operator [] (const unsigned int index) const;
 
   /**
-   * Read and write access to the
-   * <tt>index</tt>th coordinate.
+   * Read and write access to the <tt>index</tt>th coordinate.
    *
-   * Note that the derived
-   * <tt>Point</tt> class also provides
-   * access through the <tt>()</tt>
-   * operator for
-   * backcompatibility.
+   * Note that the derived <tt>Point</tt> class also provides access through
+   * the <tt>()</tt> operator for backcompatibility.
    */
   Number &operator [] (const unsigned int index);
 
@@ -455,35 +370,25 @@ public:
   Tensor<1,dim,Number> &operator = (const Tensor<1,dim,Number> &);
 
   /**
-   * This operator assigns a scalar
-   * to a tensor. To avoid
-   * confusion with what exactly it
-   * means to assign a scalar value
-   * to a tensor, zero is the only
-   * value allowed for <tt>d</tt>,
-   * allowing the intuitive
-   * notation <tt>t=0</tt> to reset
-   * all elements of the tensor to
-   * zero.
+   * This operator assigns a scalar to a tensor. To avoid confusion with what
+   * exactly it means to assign a scalar value to a tensor, zero is the only
+   * value allowed for <tt>d</tt>, allowing the intuitive notation
+   * <tt>t=0</tt> to reset all elements of the tensor to zero.
    */
   Tensor<1,dim,Number> &operator = (const Number d);
 
   /**
-   * Test for equality of two
-   * tensors.
+   * Test for equality of two tensors.
    */
   bool operator == (const Tensor<1,dim,Number> &) const;
 
   /**
-   * Test for inequality of two
-   * tensors.
+   * Test for inequality of two tensors.
    */
   bool operator != (const Tensor<1,dim,Number> &) const;
 
   /**
-   * Add another vector, i.e. move
-   * this point by the given
-   * offset.
+   * Add another vector, i.e. move this point by the given offset.
    */
   Tensor<1,dim,Number> &operator += (const Tensor<1,dim,Number> &);
 
@@ -493,9 +398,8 @@ public:
   Tensor<1,dim,Number> &operator -= (const Tensor<1,dim,Number> &);
 
   /**
-   * Scale the vector by
-   * <tt>factor</tt>, i.e. multiply all
-   * coordinates by <tt>factor</tt>.
+   * Scale the vector by <tt>factor</tt>, i.e. multiply all coordinates by
+   * <tt>factor</tt>.
    */
   Tensor<1,dim,Number> &operator *= (const Number factor);
 
@@ -505,25 +409,19 @@ public:
   Tensor<1,dim,Number> &operator /= (const Number factor);
 
   /**
-   * Returns the scalar product of
-   * two vectors.
+   * Returns the scalar product of two vectors.
    */
   Number                 operator * (const Tensor<1,dim,Number> &) const;
 
   /**
-   * Add two tensors. If possible,
-   * use <tt>operator +=</tt> instead
-   * since this does not need to
-   * copy a point at least once.
+   * Add two tensors. If possible, use <tt>operator +=</tt> instead since this
+   * does not need to copy a point at least once.
    */
   Tensor<1,dim,Number>   operator + (const Tensor<1,dim,Number> &) const;
 
   /**
-   * Subtract two tensors. If
-   * possible, use <tt>operator +=</tt>
-   * instead since this does not
-   * need to copy a point at least
-   * once.
+   * Subtract two tensors. If possible, use <tt>operator +=</tt> instead since
+   * this does not need to copy a point at least once.
    */
   Tensor<1,dim,Number>   operator - (const Tensor<1,dim,Number> &) const;
 
@@ -533,47 +431,31 @@ public:
   Tensor<1,dim,Number>   operator - () const;
 
   /**
-   * Return the Frobenius-norm of a
-   * tensor, i.e. the square root
-   * of the sum of squares of all
-   * entries. For the present case
-   * of rank-1 tensors, this equals
-   * the usual
-   * <tt>l<sub>2</sub></tt> norm of
-   * the vector.
+   * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+   * squares of all entries. For the present case of rank-1 tensors, this
+   * equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
    */
   real_type norm () const;
 
   /**
-   * Return the square of the
-   * Frobenius-norm of a tensor,
-   * i.e. the square root of the
-   * sum of squares of all entries.
+   * Return the square of the Frobenius-norm of a tensor, i.e. the square root
+   * of the sum of squares of all entries.
    *
-   * This function mainly exists
-   * because it makes computing the
-   * norm simpler recursively, but
-   * may also be useful in other
-   * contexts.
+   * This function mainly exists because it makes computing the norm simpler
+   * recursively, but may also be useful in other contexts.
    */
   real_type norm_square () const;
 
   /**
    * Reset all values to zero.
    *
-   * Note that this is partly inconsistent
-   * with the semantics of the @p clear()
-   * member functions of the STL and of
-   * several other classes within deal.II
-   * which not only reset the values of
-   * stored elements to zero, but release
-   * all memory and return the object into
-   * a virginial state. However, since the
-   * size of objects of the present type is
-   * determined by its template parameters,
-   * resizing is not an option, and indeed
-   * the state where all elements have a
-   * zero value is the state right after
+   * Note that this is partly inconsistent with the semantics of the @p
+   * clear() member functions of the STL and of several other classes within
+   * deal.II which not only reset the values of stored elements to zero, but
+   * release all memory and return the object into a virginial state. However,
+   * since the size of objects of the present type is determined by its
+   * template parameters, resizing is not an option, and indeed the state
+   * where all elements have a zero value is the state right after
    * construction of such an object.
    */
   void clear ();
@@ -581,55 +463,45 @@ public:
   /**
    * Fill a vector with all tensor elements.
    *
-   * This function unrolls all
-   * tensor entries into a single,
-   * linearly numbered vector. As
-   * usual in C++, the rightmost
-   * index marches fastest.
+   * This function unrolls all tensor entries into a single, linearly numbered
+   * vector. As usual in C++, the rightmost index marches fastest.
    */
   template <typename Number2>
   void unroll (Vector<Number2> &result) const;
 
   /**
-   * Returns an unrolled index in
-   * the range [0,dim-1] for the element of the tensor indexed by
-   * the argument to the function.
+   * Returns an unrolled index in the range [0,dim-1] for the element of the
+   * tensor indexed by the argument to the function.
    *
-   * Given that this is a rank-1 object, the returned value
-   * is simply the value of the only index stored by the argument.
+   * Given that this is a rank-1 object, the returned value is simply the
+   * value of the only index stored by the argument.
    */
   static
   unsigned int
   component_to_unrolled_index(const TableIndices<1> &indices);
 
   /**
-   * Opposite of  component_to_unrolled_index: For an index in the
-   * range [0,dim-1], return which set of indices it would
-   * correspond to.
+   * Opposite of  component_to_unrolled_index: For an index in the range
+   * [0,dim-1], return which set of indices it would correspond to.
    *
-   * Given that this is a rank-1 object, the returned set of indices
-   * consists of only a single element with value equal to the argument
-   * to this function.
+   * Given that this is a rank-1 object, the returned set of indices consists
+   * of only a single element with value equal to the argument to this
+   * function.
    */
   static
   TableIndices<1> unrolled_to_component_indices(const unsigned int i);
 
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
+   * Determine an estimate for the memory consumption (in bytes) of this
    * object.
    */
   static std::size_t memory_consumption ();
 
   /**
-   * Only tensors with a positive
-   * dimension are implemented. This
-   * exception is thrown by the
-   * constructor if the template
-   * argument <tt>dim</tt> is zero or
-   * less.
+   * Only tensors with a positive dimension are implemented. This exception is
+   * thrown by the constructor if the template argument <tt>dim</tt> is zero
+   * or less.
    *
    * @ingroup Exceptions
    */
@@ -638,34 +510,25 @@ public:
                   << "dim must be positive, but was " << arg1);
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize(Archive &ar, const unsigned int version);
 
 private:
   /**
-   * Store the values in a simple
-   * array.  For <tt>dim==0</tt> store
-   * one element, because otherways
-   * the compiler would choke.  We
-   * catch this case in the
-   * constructor to disallow the
-   * creation of such an object.
+   * Store the values in a simple array.  For <tt>dim==0</tt> store one
+   * element, because otherways the compiler would choke.  We catch this case
+   * in the constructor to disallow the creation of such an object.
    */
   Number values[(dim!=0) ? (dim) : (dim+1)];
 
   /**
-   * Help function for unroll. If
-   * we have detected an access
-   * control bug in the compiler,
-   * this function is declared
-   * public, otherwise private. Do
-   * not attempt to use this
-   * function from outside in any
-   * case, even if it should be
-   * public for your compiler.
+   * Help function for unroll. If we have detected an access control bug in
+   * the compiler, this function is declared public, otherwise private. Do not
+   * attempt to use this function from outside in any case, even if it should
+   * be public for your compiler.
    */
   template <typename Number2>
   void unroll_recursion (Vector<Number2> &result,
@@ -673,38 +536,30 @@ private:
 
 private:
   /**
-   * Make the following classes
-   * friends to this class. In
-   * principle, it would suffice if
-   * otherrank==2, but that is not
-   * possible in C++ at present.
+   * Make the following classes friends to this class. In principle, it would
+   * suffice if otherrank==2, but that is not possible in C++ at present.
    *
-   * Also, it would be sufficient
-   * to make the function
-   * unroll_loops a friend, but
-   * that seems to be impossible as
-   * well.
+   * Also, it would be sufficient to make the function unroll_loops a friend,
+   * but that seems to be impossible as well.
    */
   template <int otherrank, int otherdim, typename OtherNumber>  friend class dealii::Tensor;
 
   /**
-   * Point is allowed access to
-   * the coordinates. This is
-   * supposed to improve speed.
+   * Point is allowed access to the coordinates. This is supposed to improve
+   * speed.
    */
   friend class Point<dim,Number>;
 };
 
 
 /**
- *  Prints the value of this scalar.
+ * Prints the value of this scalar.
  */
 template <int dim,typename Number>
 std::ostream &operator << (std::ostream &out, const Tensor<0,dim,Number> &p);
 
 /**
- *  Prints the values of this tensor in the
- *  form <tt>x1 x2 x3 etc</tt>.
+ * Prints the values of this tensor in the form <tt>x1 x2 x3 etc</tt>.
  */
 template <int dim,typename Number>
 std::ostream &operator << (std::ostream &out, const Tensor<1,dim,Number> &p);
@@ -1298,8 +1153,8 @@ void Tensor<1,dim,Number>::serialize(Archive &ar, const unsigned int)
 
 
 /**
- * Output operator for tensors of rank 0. Since such tensors are
- * scalars, we simply print this one value.
+ * Output operator for tensors of rank 0. Since such tensors are scalars, we
+ * simply print this one value.
  *
  * @relates Tensor<0,dim,Number>
  */
@@ -1314,8 +1169,8 @@ std::ostream &operator << (std::ostream &out, const Tensor<0,dim,Number> &p)
 
 
 /**
- * Output operator for tensors of rank 1. Print the elements
- * consecutively, with a space in between.
+ * Output operator for tensors of rank 1. Print the elements consecutively,
+ * with a space in between.
  *
  * @relates Tensor<1,dim,Number>
  */
@@ -1333,9 +1188,9 @@ std::ostream &operator << (std::ostream &out, const Tensor<1,dim,Number> &p)
 
 
 /**
- * Output operator for tensors of rank 1 and dimension 1. This is
- * implemented specialized from the general template in order to avoid
- * a compiler warning that the loop is empty.
+ * Output operator for tensors of rank 1 and dimension 1. This is implemented
+ * specialized from the general template in order to avoid a compiler warning
+ * that the loop is empty.
  *
  * @relates Tensor<1,dim,Number>
  */
@@ -1464,8 +1319,8 @@ operator / (const Tensor<1,dim> &t,
 
 
 /**
- * Multiplication of a tensor of rank 1 by a scalar complex<double>
- * from the right.
+ * Multiplication of a tensor of rank 1 by a scalar complex<double> from the
+ * right.
  *
  * @relates Tensor<1,dim,Number>
  */
@@ -1484,8 +1339,8 @@ operator * (const Tensor<1,dim>        &t,
 
 
 /**
- * Multiplication of a tensor of rank 1 by a scalar complex<double>
- * from the left.
+ * Multiplication of a tensor of rank 1 by a scalar complex<double> from the
+ * left.
  *
  * @relates Tensor<1,dim,Number>
  */
index f1b678b8baaf46b911a66c2f82d093f2469686b2..229ad2d7e57181bb5992c168b145b9d409b5a0d7 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- *  This class is a model for a tensor valued function. The interface
- *  of the class is mostly the same as that for the Function
- *  class, with the exception that it does not support vector-valued
- *  functions with several components, but that the return type is
- *  always tensor-valued. The returned values of the evaluation of
- *  objects of this type are always whole tensors, while for the
- *  <tt>Function</tt> class, one can ask for a specific component only, or
- *  use the <tt>vector_value</tt> function, which however does not return
- *  the value, but rather writes it into the address provided by its
- *  second argument. The reason for the different behaviour of the
- *  classes is that in the case of tensor valued functions, the size
- *  of the argument is known to the compiler a priori, such that the
- *  correct amount of memory can be allocated on the stack for the
- *  return value; on the other hand, for the vector valued functions,
- *  the size is not known to the compiler, so memory has to be
- *  allocated on the heap, resulting in relatively expensive copy
- *  operations. One can therefore consider this class a specialization
- *  of the <tt>Function</tt> class for which the size is known. An
- *  additional benefit is that tensors of arbitrary rank can be
- *  returned, not only vectors, as for them the size can be determined
- *  similarly simply.
+ * This class is a model for a tensor valued function. The interface of the
+ * class is mostly the same as that for the Function class, with the exception
+ * that it does not support vector-valued functions with several components,
+ * but that the return type is always tensor-valued. The returned values of
+ * the evaluation of objects of this type are always whole tensors, while for
+ * the <tt>Function</tt> class, one can ask for a specific component only, or
+ * use the <tt>vector_value</tt> function, which however does not return the
+ * value, but rather writes it into the address provided by its second
+ * argument. The reason for the different behaviour of the classes is that in
+ * the case of tensor valued functions, the size of the argument is known to
+ * the compiler a priori, such that the correct amount of memory can be
+ * allocated on the stack for the return value; on the other hand, for the
+ * vector valued functions, the size is not known to the compiler, so memory
+ * has to be allocated on the heap, resulting in relatively expensive copy
+ * operations. One can therefore consider this class a specialization of the
+ * <tt>Function</tt> class for which the size is known. An additional benefit
+ * is that tensors of arbitrary rank can be returned, not only vectors, as for
+ * them the size can be determined similarly simply.
  *
- *  @ingroup functions
- *  @author Guido Kanschat, 1999
+ * @ingroup functions
+ * @author Guido Kanschat, 1999
  */
 template <int rank, int dim, typename Number=double>
 class TensorFunction : public FunctionTime<Number>,
@@ -75,8 +72,8 @@ public:
 
   /**
    * Virtual destructor; absolutely necessary in this case, as classes are
-   * usually not used by their true type, but rather through pointers to
-   * this base class.
+   * usually not used by their true type, but rather through pointers to this
+   * base class.
    */
   virtual ~TensorFunction ();
 
@@ -134,8 +131,8 @@ class ConstantTensorFunction : public TensorFunction<rank, dim, Number>
 {
 public:
   /**
-   * Constructor; takes the constant tensor value as an argument.
-   * The reference value is copied internally.
+   * Constructor; takes the constant tensor value as an argument. The
+   * reference value is copied internally.
    *
    * An initial value for the time variable may be specified, otherwise it
    * defaults to zero.
@@ -162,8 +159,8 @@ private:
 
 
 /**
- * Provide a tensor valued function which always returns zero.
- * Obviously, all derivates of this function are zero.
+ * Provide a tensor valued function which always returns zero. Obviously, all
+ * derivates of this function are zero.
  *
  * @ingroup functions
  * @author Matthias Maier, 2013
index d1190bf68916919009725f30f00a59915c38f41b..6906e453d8586c0b781da04ab6ce11ad79634a0d 100644 (file)
@@ -36,31 +36,29 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Tensor product of given polynomials.
  *
- * Given a vector of <i>n</i> one-dimensional polynomials
- * <i>P<sub>1</sub></i> to <i>P<sub>n</sub></i>, this class generates
- * <i>n<sup>dim</sup></i> polynomials of the form
- * <i>Q<sub>ijk</sub>(x,y,z) =
+ * Given a vector of <i>n</i> one-dimensional polynomials <i>P<sub>1</sub></i>
+ * to <i>P<sub>n</sub></i>, this class generates <i>n<sup>dim</sup></i>
+ * polynomials of the form <i>Q<sub>ijk</sub>(x,y,z) =
  * P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>. If the base
- * polynomials are mutually orthogonal on the interval [-1,1] or
- * [0,1], then the tensor product polynomials are orthogonal on
- * [-1,1]<sup>dim</sup> or [0,1]<sup>dim</sup>, respectively.
+ * polynomials are mutually orthogonal on the interval [-1,1] or [0,1], then
+ * the tensor product polynomials are orthogonal on [-1,1]<sup>dim</sup> or
+ * [0,1]<sup>dim</sup>, respectively.
  *
  * Indexing is as follows: the order of dim-dimensional polynomials is
- * x-coordinates running fastest, then y-coordinate, etc. The first
- * few polynomials are thus <i>P<sub>1</sub>(x)P<sub>1</sub>(y),
- * P<sub>2</sub>(x)P<sub>1</sub>(y), P<sub>3</sub>(x)P<sub>1</sub>(y),
- * ..., P<sub>1</sub>(x)P<sub>2</sub>(y),
- * P<sub>2</sub>(x)P<sub>2</sub>(y), P<sub>3</sub>(x)P<sub>2</sub>(y),
- * ...</i> and likewise in 3d.
+ * x-coordinates running fastest, then y-coordinate, etc. The first few
+ * polynomials are thus <i>P<sub>1</sub>(x)P<sub>1</sub>(y),
+ * P<sub>2</sub>(x)P<sub>1</sub>(y), P<sub>3</sub>(x)P<sub>1</sub>(y), ...,
+ * P<sub>1</sub>(x)P<sub>2</sub>(y), P<sub>2</sub>(x)P<sub>2</sub>(y),
+ * P<sub>3</sub>(x)P<sub>2</sub>(y), ...</i> and likewise in 3d.
  *
- * The output_indices() function prints the ordering of the
- * dim-dimensional polynomials, i.e. for each polynomial in the
- * polynomial space it gives the indices i,j,k of the one-dimensional
- * polynomials in x,y and z direction. The ordering of the
- * dim-dimensional polynomials can be changed by using the
+ * The output_indices() function prints the ordering of the dim-dimensional
+ * polynomials, i.e. for each polynomial in the polynomial space it gives the
+ * indices i,j,k of the one-dimensional polynomials in x,y and z direction.
+ * The ordering of the dim-dimensional polynomials can be changed by using the
  * set_numbering() function.
  *
- * @author Ralf Hartmann, 2000, 2004, Guido Kanschat, 2000, Wolfgang Bangerth 2003
+ * @author Ralf Hartmann, 2000, 2004, Guido Kanschat, 2000, Wolfgang Bangerth
+ * 2003
  */
 template <int dim, typename POLY=Polynomials::Polynomial<double> >
 class TensorProductPolynomials
@@ -194,8 +192,8 @@ protected:
 
   /**
    * Each tensor product polynomial <i>i</i> is a product of one-dimensional
-   * polynomials in each space direction. Compute the indices of these
-   * one-dimensional polynomials for each space direction, given the index
+   * polynomials in each space direction. Compute the indices of these one-
+   * dimensional polynomials for each space direction, given the index
    * <i>i</i>.
    */
   // fix to avoid compiler warnings about zero length arrays
@@ -209,16 +207,15 @@ protected:
  * Anisotropic tensor product of given polynomials.
  *
  * Given one-dimensional polynomials <tt>Px1</tt>, <tt>Px2</tt>, ... in
- * x-direction, <tt>Py1</tt>, <tt>Py2</tt>, ... in y-direction, and so on, this
- * class generates polynomials of the form  <i>Q<sub>ijk</sub>(x,y,z) =
- * Pxi(x)Pyj(y)Pzk(z)</i>. If the base polynomials are mutually
- * orthogonal on the interval $[-1,1]$ or $[0,d]$, then the tensor
- * product polynomials are orthogonal on $[-1,1]^d$ or $[0,1]^d$,
- * respectively.
+ * x-direction, <tt>Py1</tt>, <tt>Py2</tt>, ... in y-direction, and so on,
+ * this class generates polynomials of the form  <i>Q<sub>ijk</sub>(x,y,z) =
+ * Pxi(x)Pyj(y)Pzk(z)</i>. If the base polynomials are mutually orthogonal on
+ * the interval $[-1,1]$ or $[0,d]$, then the tensor product polynomials are
+ * orthogonal on $[-1,1]^d$ or $[0,1]^d$, respectively.
  *
- * Indexing is as follows: the order of dim-dimensional polynomials
- * is x-coordinates running fastest, then y-coordinate, etc. The first
- * few polynomials are thus <tt>Px1(x)Py1(y)</tt>, <tt>Px2(x)Py1(y)</tt>,
+ * Indexing is as follows: the order of dim-dimensional polynomials is
+ * x-coordinates running fastest, then y-coordinate, etc. The first few
+ * polynomials are thus <tt>Px1(x)Py1(y)</tt>, <tt>Px2(x)Py1(y)</tt>,
  * <tt>Px3(x)Py1(y)</tt>, ..., <tt>Px1(x)Py2(y)</tt>, <tt>Px2(x)Py2(y)</tt>,
  * <tt>Px3(x)Py2(y)</tt>, ..., and likewise in 3d.
  *
@@ -320,8 +317,8 @@ private:
 
   /**
    * Each tensor product polynomial @þ{i} is a product of one-dimensional
-   * polynomials in each space direction. Compute the indices of these
-   * one-dimensional polynomials for each space direction, given the index
+   * polynomials in each space direction. Compute the indices of these one-
+   * dimensional polynomials for each space direction, given the index
    * <tt>i</tt>.
    */
   void compute_index (const unsigned int i,
index a359dc1abcdcf165dd1ecd06cc3dfb5a9ed1b227..8deadfb4b5ddc58cda5fda3f089fcb51fa5bc719 100644 (file)
@@ -48,10 +48,8 @@ class TensorProductPolynomialsConst : public TensorProductPolynomials<dim>
 {
 public:
   /**
-   * Access to the dimension of
-   * this object, for checking and
-   * automatic setting of dimension
-   * in other classes.
+   * Access to the dimension of this object, for checking and automatic
+   * setting of dimension in other classes.
    */
   static const unsigned int dimension = dim;
 
index 5a28b5c8808f3ac61e67ca0fbc11057f8fd71989..96e456de0e037d63b93718389184357864be0855 100644 (file)
@@ -34,55 +34,57 @@ DEAL_II_NAMESPACE_OPEN
 namespace Threads
 {
   /**
-   * @brief A class that provides a separate storage location on each thread that accesses the object.
+   * @brief A class that provides a separate storage location on each thread
+   * that accesses the object.
    *
-   * This class offers ways so that every thread that accesses it has its
-   * own copy of an object of type T. In essence, accessing this object
-   * can never result in race conditions in multithreaded programs since
-   * no other thread than the current one can ever access it.
+   * This class offers ways so that every thread that accesses it has its own
+   * copy of an object of type T. In essence, accessing this object can never
+   * result in race conditions in multithreaded programs since no other thread
+   * than the current one can ever access it.
    *
-   * The class builds on the Threading Building Blocks's tbb::enumerable_thread_specific
-   * class but wraps it in such a way that this class can also be used when deal.II
-   * is configured not to use threads at all -- in that case, this class simply
-   * stores a single copy of an object of type T.
+   * The class builds on the Threading Building Blocks's
+   * tbb::enumerable_thread_specific class but wraps it in such a way that
+   * this class can also be used when deal.II is configured not to use threads
+   * at all -- in that case, this class simply stores a single copy of an
+   * object of type T.
    *
    * <h3>Construction and destruction</h3>
    *
-   * Objects of this class can either be default constructed or by providing an
-   * "exemplar", i.e. an object of type T so that every time we need to create
-   * a T on a thread that doesn't already have such an object, it is copied from
-   * the exemplar.
+   * Objects of this class can either be default constructed or by providing
+   * an "exemplar", i.e. an object of type T so that every time we need to
+   * create a T on a thread that doesn't already have such an object, it is
+   * copied from the exemplar.
    *
    * Upon destruction of objects of this class, all T objects that correspond
-   * to threads that have accessed this object are destroyed. Note that this may be
-   * before the time when a thread is terminated.
+   * to threads that have accessed this object are destroyed. Note that this
+   * may be before the time when a thread is terminated.
    *
    * <h3>Access</h3>
    *
-   * The T object stored by this object can be accessed using the get() function. It
-   * provides a reference to a unique object when accessed from different threads.
-   * Objects of type T are created lazily, i.e. they are only created whenever a
-   * thread actually calls get().
+   * The T object stored by this object can be accessed using the get()
+   * function. It provides a reference to a unique object when accessed from
+   * different threads. Objects of type T are created lazily, i.e. they are
+   * only created whenever a thread actually calls get().
    */
   template <typename T>
   class ThreadLocalStorage
   {
   public:
     /**
-     * Default constructor. Initialize each thread local object
-     * using its default constructor.
-     **/
+     * Default constructor. Initialize each thread local object using its
+     * default constructor.
+     */
     ThreadLocalStorage ();
 
     /**
-     * A kind of copy constructor. Initialize each thread local object
-     * by copying the given object.
-     **/
+     * A kind of copy constructor. Initialize each thread local object by
+     * copying the given object.
+     */
     explicit ThreadLocalStorage (const T &t);
 
     /**
-     * Copy constructor. Initialize each thread local object
-     * with the corresponding object of the given object.
+     * Copy constructor. Initialize each thread local object with the
+     * corresponding object of the given object.
      */
     ThreadLocalStorage (const ThreadLocalStorage<T> &t);
 
@@ -90,71 +92,70 @@ namespace Threads
      * Return a reference to the data stored by this object for the current
      * thread this function is called on.
      *
-     * Note that there is no member function get() that is const and
-     * returns a const reference as one would expect. The reason is that
-     * if such a member function were called on a thread for which no
-     * thread-local object has been created yet, then one has to create
-     * such an object first which would certainly be a non-constant
-     * operation. If you need to call the get() function for a member
-     * variable of a class from a const member function, then you
-     * need to declare the member variable <code>mutable</code> to
-     * allow such access.
+     * Note that there is no member function get() that is const and returns a
+     * const reference as one would expect. The reason is that if such a
+     * member function were called on a thread for which no thread-local
+     * object has been created yet, then one has to create such an object
+     * first which would certainly be a non-constant operation. If you need to
+     * call the get() function for a member variable of a class from a const
+     * member function, then you need to declare the member variable
+     * <code>mutable</code> to allow such access.
      */
     T &get ();
 
     /**
-     * Same as above, except that @p exists is set to true if an element
-     * was already present for the current thread; false otherwise.
+     * Same as above, except that @p exists is set to true if an element was
+     * already present for the current thread; false otherwise.
      */
     T &get (bool &exists);
 
     /**
-     * Conversion operator that simply converts the thread-local object
-     * to the data type that it stores. This function is equivalent to
-     * calling the get() member function; it's purpose is to make the
-     * TLS object look more like the object it is storing.
+     * Conversion operator that simply converts the thread-local object to the
+     * data type that it stores. This function is equivalent to calling the
+     * get() member function; it's purpose is to make the TLS object look more
+     * like the object it is storing.
      */
     operator T &();
 
     /**
-     * Copy the given argument into the storage space used to represent
-     * the current thread. Calling this function as <code>tls_data = object</code>
+     * Copy the given argument into the storage space used to represent the
+     * current thread. Calling this function as <code>tls_data = object</code>
      * is equivalent to calling <code>tls_data.get() = object</code>. The
-     * intent of this operator is to make the ThreadLocalStorage object
-     * look more like the object it represents on the current thread.
+     * intent of this operator is to make the ThreadLocalStorage object look
+     * more like the object it represents on the current thread.
      *
-     * @param t The object to be copied into the storage space used
-     * for the current thread.
+     * @param t The object to be copied into the storage space used for the
+     * current thread.
      *
      * @return The current object, after the changes have been made
-     **/
+     */
     ThreadLocalStorage<T> &operator = (const T &t);
 
     /**
      * Remove the thread-local objects stored for all threads that have
-     * created one with this object (i.e., that have called get()
-     * at least once on this thread. This includes the current thread. If you
-     * call get() subsequently on this or any other thread, new objects will
-     * again be created.
+     * created one with this object (i.e., that have called get() at least
+     * once on this thread. This includes the current thread. If you call
+     * get() subsequently on this or any other thread, new objects will again
+     * be created.
      *
-     * If deal.II has been configured to not use multithreading, then this function
-     * does not do anything at all. Note that this of course has different semantics
-     * as in the multithreading context the objects are deleted and created again
-     * (possible by copying from a sample object, if the appropriate constructor
-     * of this class was called), whereas in the multithreaded context the object
-     * is simply not touched at all. At the same time, the purpose of this function
-     * is to release memory other threads may have allocated for their own thread
-     * local objects after which every use of this object will require some kind
-     * of initialization. This is necessary both in the multithreaded or
-     * non-multithreaded case.
+     * If deal.II has been configured to not use multithreading, then this
+     * function does not do anything at all. Note that this of course has
+     * different semantics as in the multithreading context the objects are
+     * deleted and created again (possible by copying from a sample object, if
+     * the appropriate constructor of this class was called), whereas in the
+     * multithreaded context the object is simply not touched at all. At the
+     * same time, the purpose of this function is to release memory other
+     * threads may have allocated for their own thread local objects after
+     * which every use of this object will require some kind of
+     * initialization. This is necessary both in the multithreaded or non-
+     * multithreaded case.
      */
     void clear ();
 
     /**
      * Returns a reference to the internal Threading Building Blocks
-     * implementation. This function is really only useful if deal.II
-     * has been configured with multithreading and has no useful
-     * purpose otherwise.
+     * implementation. This function is really only useful if deal.II has been
+     * configured with multithreading and has no useful purpose otherwise.
      */
 #ifdef DEAL_II_WITH_THREADS
     tbb::enumerable_thread_specific<T> &
@@ -166,11 +167,10 @@ namespace Threads
   private:
 #ifdef DEAL_II_WITH_THREADS
     /**
-     * The data element we store. If we support threads, then this
-     * object will be of a type that provides a separate object
-     * for each thread. Otherwise, it is simply a single object
-     * of type T.
-     **/
+     * The data element we store. If we support threads, then this object will
+     * be of a type that provides a separate object for each thread.
+     * Otherwise, it is simply a single object of type T.
+     */
     tbb::enumerable_thread_specific<T> data;
 #else
     T data;
index b268312e3c3dcfe26c6688ba9ae34e6730b4f064..01c2764b86795e771902bb9d49c43b635b3bc0a8 100644 (file)
@@ -53,10 +53,9 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * A namespace for the implementation of thread management in
- * deal.II. Most of the content of this namespace is discussed in
- * detail in one of the reports linked to from the documentation page
- * of deal.II.
+ * A namespace for the implementation of thread management in deal.II. Most of
+ * the content of this namespace is discussed in detail in one of the reports
+ * linked to from the documentation page of deal.II.
  *
  * @ingroup threads
  */
@@ -64,15 +63,14 @@ namespace Threads
 {
   /**
    * This class is used instead of a true lock class when not using
-   * multithreading. It allows to write programs such that they start
-   * new threads and/or lock objects in multithreading mode, and use
-   * dummy thread management and synchronization classes instead when
-   * running in single-thread mode. Specifically, the new_thread()
-   * functions only call the function but wait for it to return
-   * instead of running in on another thread, and the mutices do
-   * nothing really. The only reason to provide such a function is
-   * that the program can be compiled both in MT and non-MT mode
-   * without difference.
+   * multithreading. It allows to write programs such that they start new
+   * threads and/or lock objects in multithreading mode, and use dummy thread
+   * management and synchronization classes instead when running in single-
+   * thread mode. Specifically, the new_thread() functions only call the
+   * function but wait for it to return instead of running in on another
+   * thread, and the mutices do nothing really. The only reason to provide
+   * such a function is that the program can be compiled both in MT and non-MT
+   * mode without difference.
    *
    * @author Wolfgang Bangerth, 2000, 2003
    */
@@ -80,46 +78,44 @@ namespace Threads
   {
   public:
     /**
-     * Scoped lock class. When you declare an object of this type, you
-     * have to pass it a mutex, which is locked in the constructor of
-     * this class and unlocked in the destructor. The lock is thus
-     * held during the entire lifetime of this object, i.e. until the
-     * end of the present scope, which explains where the name comes
-     * from. This pattern of using locks with mutexes follows the
-     * resource-acquisition-is-initialization pattern, and was used
-     * first for mutexes by Doug Schmidt. It has the advantage that
-     * locking a mutex this way is thread-safe, i.e. when an exception
-     * is thrown between the locking and unlocking point, the
-     * destructor makes sure that the mutex is unlocked; this would
-     * not automatically be the case when you lock and unlock the
-     * mutex "by hand", i.e. using Mutex::acquire() and
-     * Mutex::release().
+     * Scoped lock class. When you declare an object of this type, you have to
+     * pass it a mutex, which is locked in the constructor of this class and
+     * unlocked in the destructor. The lock is thus held during the entire
+     * lifetime of this object, i.e. until the end of the present scope, which
+     * explains where the name comes from. This pattern of using locks with
+     * mutexes follows the resource-acquisition-is-initialization pattern, and
+     * was used first for mutexes by Doug Schmidt. It has the advantage that
+     * locking a mutex this way is thread-safe, i.e. when an exception is
+     * thrown between the locking and unlocking point, the destructor makes
+     * sure that the mutex is unlocked; this would not automatically be the
+     * case when you lock and unlock the mutex "by hand", i.e. using
+     * Mutex::acquire() and Mutex::release().
      */
     class ScopedLock
     {
     public:
       /**
-       * Constructor. Lock the mutex. Since this is a dummy mutex
-       * class, this of course does nothing.
+       * Constructor. Lock the mutex. Since this is a dummy mutex class, this
+       * of course does nothing.
        */
       ScopedLock (DummyThreadMutex &) {}
 
       /**
-       * Destructor. Unlock the mutex. Since this is a dummy mutex
-       * class, this of course does nothing.
+       * Destructor. Unlock the mutex. Since this is a dummy mutex class, this
+       * of course does nothing.
        */
       ~ScopedLock () {}
     };
 
     /**
-     * Simulate acquisition of the mutex. As this class does nothing
-     * really, this function does nothing as well.
+     * Simulate acquisition of the mutex. As this class does nothing really,
+     * this function does nothing as well.
      */
     inline void acquire () const {}
 
     /**
-     * Simulate release of the mutex. As this class does nothing
-     * really, this function does nothing as well.
+     * Simulate release of the mutex. As this class does nothing really, this
+     * function does nothing as well.
      */
     inline void release () const {}
   };
@@ -128,19 +124,18 @@ namespace Threads
 
   /**
    * This class is used in single threaded mode instead of a class
-   * implementing real condition variable semantics. It allows to
-   * write programs such that they start new threads and/or lock
-   * objects in multithreading mode, and use dummy thread management
-   * and synchronization classes instead when running in single-thread
-   * mode. Specifically, the new_thread() functions only call the
-   * function but wait for it to return instead of running in on
-   * another thread, and the mutexes do nothing really. The only
-   * reason to provide such a function is that the program can be
-   * compiled both in MT and non-MT mode without difference.
+   * implementing real condition variable semantics. It allows to write
+   * programs such that they start new threads and/or lock objects in
+   * multithreading mode, and use dummy thread management and synchronization
+   * classes instead when running in single-thread mode. Specifically, the
+   * new_thread() functions only call the function but wait for it to return
+   * instead of running in on another thread, and the mutexes do nothing
+   * really. The only reason to provide such a function is that the program
+   * can be compiled both in MT and non-MT mode without difference.
    *
-   * In this particular case, just as with mutexes, the functions do
-   * nothing, and by this provide the same semantics of condition
-   * variables as in multi-threaded mode.
+   * In this particular case, just as with mutexes, the functions do nothing,
+   * and by this provide the same semantics of condition variables as in
+   * multi-threaded mode.
    *
    * @author Wolfgang Bangerth, 2003
    */
@@ -148,26 +143,25 @@ namespace Threads
   {
   public:
     /**
-     * Signal to a single listener that a condition has been met,
-     * i.e. that some data will now be available. Since in single
-     * threaded mode, this function of course does nothing.
+     * Signal to a single listener that a condition has been met, i.e. that
+     * some data will now be available. Since in single threaded mode, this
+     * function of course does nothing.
      */
     inline void signal () const {}
 
     /**
-     * Signal to multiple listener that a condition has been met,
-     * i.e. that some data will now be available. Since in single
-     * threaded mode, this function of course does nothing.
+     * Signal to multiple listener that a condition has been met, i.e. that
+     * some data will now be available. Since in single threaded mode, this
+     * function of course does nothing.
      */
     inline void broadcast () const {}
 
     /**
-     * Wait for the condition to be signalled. Signal variables need
-     * to be guarded by a mutex which needs to be given to this
-     * function as an argument, see the man page of
-     * <code>posix_cond_wait</code> for a description of the
-     * mechanisms. Since in single threaded mode, this function of
-     * course does nothing, but returns immediately.
+     * Wait for the condition to be signalled. Signal variables need to be
+     * guarded by a mutex which needs to be given to this function as an
+     * argument, see the man page of <code>posix_cond_wait</code> for a
+     * description of the mechanisms. Since in single threaded mode, this
+     * function of course does nothing, but returns immediately.
      */
     inline void wait (DummyThreadMutex &) const {}
   };
@@ -176,16 +170,15 @@ namespace Threads
 
   /**
    * This class is used instead of a true barrier class when not using
-   * multithreading. It allows to write programs such that they use
-   * the same class names in multithreading and non-MT mode and thus
-   * may be compiled with or without thread-support without the need
-   * to use conditional compilation. Since a barrier class only makes
-   * sense in non-multithread mode if only one thread is to be
-   * synchronised (otherwise, the barrier could not be left, since the
-   * one thread is waiting for some other part of the program to reach
-   * a certain point of execution), the constructor of this class
-   * throws an exception if the <code>count</code> argument denoting
-   * the number of threads that need to be synchronized is not equal
+   * multithreading. It allows to write programs such that they use the same
+   * class names in multithreading and non-MT mode and thus may be compiled
+   * with or without thread-support without the need to use conditional
+   * compilation. Since a barrier class only makes sense in non-multithread
+   * mode if only one thread is to be synchronised (otherwise, the barrier
+   * could not be left, since the one thread is waiting for some other part of
+   * the program to reach a certain point of execution), the constructor of
+   * this class throws an exception if the <code>count</code> argument
+   * denoting the number of threads that need to be synchronized is not equal
    * to one.
    *
    * @author Wolfgang Bangerth, 2001
@@ -194,19 +187,17 @@ namespace Threads
   {
   public:
     /**
-     * Constructor. Since barriers are only useful in single-threaded
-     * mode if the number of threads to be synchronised is one, this
-     * constructor raises an exception if the <code>count</code>
-     * argument is one.
+     * Constructor. Since barriers are only useful in single-threaded mode if
+     * the number of threads to be synchronised is one, this constructor
+     * raises an exception if the <code>count</code> argument is one.
      */
     DummyBarrier (const unsigned int  count,
                   const char         *name = 0,
                   void               *arg  = 0);
 
     /**
-     * Wait for all threads to reach this point. Since there may only
-     * be one thread, return immediately, i.e. this function is a
-     * no-op.
+     * Wait for all threads to reach this point. Since there may only be one
+     * thread, return immediately, i.e. this function is a no-op.
      */
     int wait () const
     {
@@ -218,8 +209,10 @@ namespace Threads
      */
     void dump () const {}
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception.
@@ -236,19 +229,18 @@ namespace Threads
 #ifdef DEAL_II_WITH_THREADS
 
   /**
-   * Class implementing a Mutex. Mutexes are used to lock data
-   * structures to ensure that only a single thread of execution can
-   * access them at the same time.
+   * Class implementing a Mutex. Mutexes are used to lock data structures to
+   * ensure that only a single thread of execution can access them at the same
+   * time.
    *
    * <h3>Copy semantics</h3>
    *
-   * When copied, the receiving object does not receive any state from
-   * the object being copied, i.e. an entirely new mutex is
-   * created. This is consistent with expectations if a mutex is used
-   * as a member variable to lock the other member variables of a
-   * class: in that case, the mutex of the copied-to object should
-   * only guard the members of the copied-to object, not the members
-   * of both the copied-to and copied-from object.
+   * When copied, the receiving object does not receive any state from the
+   * object being copied, i.e. an entirely new mutex is created. This is
+   * consistent with expectations if a mutex is used as a member variable to
+   * lock the other member variables of a class: in that case, the mutex of
+   * the copied-to object should only guard the members of the copied-to
+   * object, not the members of both the copied-to and copied-from object.
    *
    * @author Wolfgang Bangerth, 2002, 2003, 2009
    */
@@ -256,20 +248,18 @@ namespace Threads
   {
   public:
     /**
-     * Scoped lock class. When you declare an object of this type, you
-     * have to pass it a mutex, which is locked in the constructor of
-     * this class and unlocked in the destructor. The lock is thus
-     * held during the entire lifetime of this object, i.e. until the
-     * end of the present scope, which explains where the name comes
-     * from. This pattern of using locks with mutexes follows the
-     * resource-acquisition-is-initialization pattern, and was used
-     * first for mutexes by Doug Schmidt. It has the advantage that
-     * locking a mutex this way is thread-safe, i.e. when an exception
-     * is thrown between the locking and unlocking point, the
-     * destructor makes sure that the mutex is unlocked; this would
-     * not automatically be the case when you lock and unlock the
-     * mutex "by hand", i.e. using Mutex::acquire() and
-     * Mutex::release().
+     * Scoped lock class. When you declare an object of this type, you have to
+     * pass it a mutex, which is locked in the constructor of this class and
+     * unlocked in the destructor. The lock is thus held during the entire
+     * lifetime of this object, i.e. until the end of the present scope, which
+     * explains where the name comes from. This pattern of using locks with
+     * mutexes follows the resource-acquisition-is-initialization pattern, and
+     * was used first for mutexes by Doug Schmidt. It has the advantage that
+     * locking a mutex this way is thread-safe, i.e. when an exception is
+     * thrown between the locking and unlocking point, the destructor makes
+     * sure that the mutex is unlocked; this would not automatically be the
+     * case when you lock and unlock the mutex "by hand", i.e. using
+     * Mutex::acquire() and Mutex::release().
      */
     class ScopedLock
     {
@@ -283,8 +273,8 @@ namespace Threads
       }
 
       /**
-       * Destructor. Unlock the mutex. Since this is a dummy mutex
-       * class, this of course does nothing.
+       * Destructor. Unlock the mutex. Since this is a dummy mutex class, this
+       * of course does nothing.
        */
       ~ScopedLock ()
       {
@@ -305,8 +295,8 @@ namespace Threads
     {}
 
     /**
-     * Copy constructor. As discussed in this class's documentation,
-     * no state is copied from the object given as argument.
+     * Copy constructor. As discussed in this class's documentation, no state
+     * is copied from the object given as argument.
      */
     Mutex (const Mutex &)
       :
@@ -337,17 +327,16 @@ namespace Threads
     std_cxx11::mutex mutex;
 
     /**
-     * Make the class implementing condition variables a friend, since
-     * it needs to access the mutex.
+     * Make the class implementing condition variables a friend, since it
+     * needs to access the mutex.
      */
     friend class ConditionVariable;
   };
 
 
   /**
-   * Class implementing a condition variable. The semantics of this
-   * class and its member functions are the same as those of the POSIX
-   * functions.
+   * Class implementing a condition variable. The semantics of this class and
+   * its member functions are the same as those of the POSIX functions.
    *
    * @author Wolfgang Bangerth, 2003
    */
@@ -355,8 +344,8 @@ namespace Threads
   {
   public:
     /**
-     * Signal to a single listener that a condition has been met,
-     * i.e. that some data will now be available.
+     * Signal to a single listener that a condition has been met, i.e. that
+     * some data will now be available.
      */
     inline void signal ()
     {
@@ -364,8 +353,8 @@ namespace Threads
     }
 
     /**
-     * Signal to multiple listener that a condition has been met,
-     * i.e. that some data will now be available.
+     * Signal to multiple listener that a condition has been met, i.e. that
+     * some data will now be available.
      */
     inline void broadcast ()
     {
@@ -373,14 +362,13 @@ namespace Threads
     }
 
     /**
-     * Wait for the condition to be signalled. Signal variables need
-     * to be guarded by a mutex which needs to be given to this
-     * function as an argument, see the man page of
-     * <code>pthread_cond_wait</code> for a description of the
-     * mechanisms.
+     * Wait for the condition to be signalled. Signal variables need to be
+     * guarded by a mutex which needs to be given to this function as an
+     * argument, see the man page of <code>pthread_cond_wait</code> for a
+     * description of the mechanisms.
      *
-     * The mutex is assumed held at the entry to this function but is
-     * released upon exit.
+     * The mutex is assumed held at the entry to this function but is released
+     * upon exit.
      */
     inline void wait (Mutex &mutex)
     {
@@ -398,18 +386,17 @@ namespace Threads
 
 
   /**
-   * Implementation of a thread barrier class, based on the POSIX
-   * thread functions. POSIX barriers are a relatively new feature and
-   * are not supported on all systems.
+   * Implementation of a thread barrier class, based on the POSIX thread
+   * functions. POSIX barriers are a relatively new feature and are not
+   * supported on all systems.
    *
-   * If the configuration detected the absence of these functions,
-   * then barriers will not be available, and creating objects of this
-   * class will result in an exception been thrown unless the count
-   * given for the parties waiting for the barrier is equal to one (as
-   * in this case waiting for the barrier is a no-operation, and we
-   * can dispense with the POSIX functions at all). The rest of the
-   * threading functionality will be available in its full extent,
-   * though, even if POSIX barriers are not available.
+   * If the configuration detected the absence of these functions, then
+   * barriers will not be available, and creating objects of this class will
+   * result in an exception been thrown unless the count given for the parties
+   * waiting for the barrier is equal to one (as in this case waiting for the
+   * barrier is a no-operation, and we can dispense with the POSIX functions
+   * at all). The rest of the threading functionality will be available in its
+   * full extent, though, even if POSIX barriers are not available.
    *
    * @author Wolfgang Bangerth, 2002
    */
@@ -417,8 +404,7 @@ namespace Threads
   {
   public:
     /**
-     * Constructor. Initialize the underlying POSIX barrier data
-     * structure.
+     * Constructor. Initialize the underlying POSIX barrier data structure.
      */
     PosixThreadBarrier (const unsigned int  count,
                         const char         *name = 0,
@@ -430,17 +416,17 @@ namespace Threads
     ~PosixThreadBarrier ();
 
     /**
-     * Wait for all threads to reach this point. The return value is
-     * zero for all participating threads except for one, for which
-     * the return value is some non-zero value. The operating system
-     * picks the special thread by some not further known method.
+     * Wait for all threads to reach this point. The return value is zero for
+     * all participating threads except for one, for which the return value is
+     * some non-zero value. The operating system picks the special thread by
+     * some not further known method.
      */
     int wait ();
 
   private:
     /**
-     * Data object storing the POSIX data which we need to call the
-     * POSIX functions.
+     * Data object storing the POSIX data which we need to call the POSIX
+     * functions.
      */
 #ifndef DEAL_II_USE_MT_POSIX_NO_BARRIERS
     pthread_barrier_t barrier;
@@ -451,50 +437,50 @@ namespace Threads
 
 
   /**
-   * Provide a backward compatible name (we used ThreadMutex up to
-   * release 6.1, but since it is already in a namespace Threads this
-   * seems redundant).
+   * Provide a backward compatible name (we used ThreadMutex up to release
+   * 6.1, but since it is already in a namespace Threads this seems
+   * redundant).
    *
    * @deprecated
    */
   typedef Mutex ThreadMutex DEAL_II_DEPRECATED;
 
   /**
-   * Provide a backward compatible name (we used ThreadCondition up to
-   * release 6.1, but since it is already in a namespace Threads this
-   * seems redundant).
+   * Provide a backward compatible name (we used ThreadCondition up to release
+   * 6.1, but since it is already in a namespace Threads this seems
+   * redundant).
    *
    * @deprecated
    */
   typedef ConditionVariable ThreadCondition DEAL_II_DEPRECATED;
 
   /**
-   * If using POSIX functions, then alias the POSIX wrapper classes to
-   * the names we use throughout the library.
+   * If using POSIX functions, then alias the POSIX wrapper classes to the
+   * names we use throughout the library.
    */
   typedef PosixThreadBarrier Barrier;
 
 #else
   /**
-   * In non-multithread mode, the mutex and thread management classes
-   * are aliased to dummy classes that actually do nothing, in
-   * particular not lock objects. Likewise for the barrier class.
+   * In non-multithread mode, the mutex and thread management classes are
+   * aliased to dummy classes that actually do nothing, in particular not lock
+   * objects. Likewise for the barrier class.
    */
   typedef DummyThreadMutex     Mutex;
   typedef DummyThreadMutex     ThreadMutex;
 
   /**
-   * In non-multithread mode, the mutex and thread management classes
-   * are aliased to dummy classes that actually do nothing, in
-   * particular not lock objects. Likewise for the barrier class.
+   * In non-multithread mode, the mutex and thread management classes are
+   * aliased to dummy classes that actually do nothing, in particular not lock
+   * objects. Likewise for the barrier class.
    */
   typedef DummyThreadCondition ConditionVariable;
   typedef DummyThreadCondition ThreadCondition;
 
   /**
-   * In non-multithread mode, the mutex and thread management classes
-   * are aliased to dummy classes that actually do nothing, in
-   * particular not lock objects. Likewise for the barrier class.
+   * In non-multithread mode, the mutex and thread management classes are
+   * aliased to dummy classes that actually do nothing, in particular not lock
+   * objects. Likewise for the barrier class.
    */
   typedef DummyBarrier         Barrier;
 #endif
@@ -506,44 +492,41 @@ namespace Threads
 {
 
   /**
-   * Return the number of presently existing threads. This function
-   * may be useful in a situation where a large number of threads are
-   * concurrently, and you want to decide whether creation of another
-   * thread is reasonable or whether running the respective operation
-   * sequentially is more useful since already many more threads than
-   * processors are running.
+   * Return the number of presently existing threads. This function may be
+   * useful in a situation where a large number of threads are concurrently,
+   * and you want to decide whether creation of another thread is reasonable
+   * or whether running the respective operation sequentially is more useful
+   * since already many more threads than processors are running.
    *
-   * Note that the function returns the total number of threads, not
-   * those actually running. Some of the threads may be waiting for
-   * locks and mutexes, or may be sleeping until they are delivered
-   * with data to work on.
+   * Note that the function returns the total number of threads, not those
+   * actually running. Some of the threads may be waiting for locks and
+   * mutexes, or may be sleeping until they are delivered with data to work
+   * on.
    *
-   * Upon program start, this number is one. It is increased each time
-   * a thread is created using the Threads::new_thread function. It is
-   * decreased once a thread terminates by returning from the function
-   * that was spawned.
+   * Upon program start, this number is one. It is increased each time a
+   * thread is created using the Threads::new_thread function. It is decreased
+   * once a thread terminates by returning from the function that was spawned.
    *
-   * Note that this means that only threads created and terminated
-   * through the interfaces of this namespace are taken care of. If
-   * threads are created by directly calling the respective functions
-   * of the operating system (e.g. <code>pthread_create</code> for the
-   * POSIX thread interface), or if they are killed (e.g. either
-   * through <code>pthread_exit</code> from the spawned thread, or
-   * <code>pthread_kill</code> from another thread), then these events
-   * are not registered and counted for the result of this
-   * function. Likewise, threads that the Threading Building Blocks
-   * library may have created to work on tasks created using the
-   * Threads::new_task functions are not counted.
+   * Note that this means that only threads created and terminated through the
+   * interfaces of this namespace are taken care of. If threads are created by
+   * directly calling the respective functions of the operating system (e.g.
+   * <code>pthread_create</code> for the POSIX thread interface), or if they
+   * are killed (e.g. either through <code>pthread_exit</code> from the
+   * spawned thread, or <code>pthread_kill</code> from another thread), then
+   * these events are not registered and counted for the result of this
+   * function. Likewise, threads that the Threading Building Blocks library
+   * may have created to work on tasks created using the Threads::new_task
+   * functions are not counted.
    *
    * @ingroup threads
    */
   unsigned int n_existing_threads ();
 
   /**
-   * Return a number used as id of this thread. This number is
-   * generated using the system call <code>getpid</code>, or, if it
-   * exists <code>gettid</code>. The result of either is converted to
-   * an integer and returned by this function.
+   * Return a number used as id of this thread. This number is generated using
+   * the system call <code>getpid</code>, or, if it exists
+   * <code>gettid</code>. The result of either is converted to an integer and
+   * returned by this function.
    *
    * @todo As of now, none of our systems seems to support
    * <code>gettid</code>, so that part of the code is untested yet.
@@ -553,18 +536,16 @@ namespace Threads
   unsigned int this_thread_id ();
 
   /**
-   * Split the range <code>[begin,end)</code> into
-   * <code>n_intervals</code> subintervals of equal size. The last
-   * interval will be a little bit larger, if the number of elements
-   * in the whole range is not exactly divisible by
-   * <code>n_intervals</code>. The type of the iterators has to
-   * fulfill the requirements of a forward iterator,
-   * i.e. <code>operator++</code> must be available, and of course it
-   * must be assignable.
+   * Split the range <code>[begin,end)</code> into <code>n_intervals</code>
+   * subintervals of equal size. The last interval will be a little bit
+   * larger, if the number of elements in the whole range is not exactly
+   * divisible by <code>n_intervals</code>. The type of the iterators has to
+   * fulfill the requirements of a forward iterator, i.e.
+   * <code>operator++</code> must be available, and of course it must be
+   * assignable.
    *
-   * A list of subintervals is returned as a vector of pairs of
-   * iterators, where each pair denotes the range
-   * <code>[begin[i],end[i])</code>.
+   * A list of subintervals is returned as a vector of pairs of iterators,
+   * where each pair denotes the range <code>[begin[i],end[i])</code>.
    *
    * @ingroup threads
    */
@@ -575,10 +556,10 @@ namespace Threads
                const unsigned int n_intervals);
 
   /**
-   * Split the interval <code>[begin,end)</code> into subintervals of
-   * (almost) equal size. This function works mostly as the one
-   * before, with the difference that instead of iterators, now values
-   * are taken that define the whole interval.
+   * Split the interval <code>[begin,end)</code> into subintervals of (almost)
+   * equal size. This function works mostly as the one before, with the
+   * difference that instead of iterators, now values are taken that define
+   * the whole interval.
    *
    * @ingroup threads
    */
@@ -592,9 +573,9 @@ namespace Threads
    */
 
   /**
-   * A namespace in which helper functions and the like for the
-   * threading subsystem are implemented. The members of this
-   * namespace are not meant for public use.
+   * A namespace in which helper functions and the like for the threading
+   * subsystem are implemented. The members of this namespace are not meant
+   * for public use.
    *
    * @author Wolfgang Bangerth, 2003
    */
@@ -603,48 +584,44 @@ namespace Threads
     /**
      * @internal
      *
-     * If in a sub-thread an exception is thrown, it is not
-     * propagated to the main thread. Therefore, the exception handler
-     * that is provided by the applications main function or some of
-     * its other parts will not be able to catch these
-     * exceptions. Therefore, we have to provide an exception handler
-     * in the top function of each sub-thread that at least catches
-     * the exception and prints some information, rather than letting
-     * the operating system to just kill the program without a
-     * message. In each of the functions we use as entry points to new
-     * threads, we therefore install a try-catch block, and if an
-     * exception of type <code>std::exception</code> is caught, it
-     * passes over control to this function, which will then provide
-     * some output.
+     * If in a sub-thread an exception is thrown, it is not propagated to the
+     * main thread. Therefore, the exception handler that is provided by the
+     * applications main function or some of its other parts will not be able
+     * to catch these exceptions. Therefore, we have to provide an exception
+     * handler in the top function of each sub-thread that at least catches
+     * the exception and prints some information, rather than letting the
+     * operating system to just kill the program without a message. In each of
+     * the functions we use as entry points to new threads, we therefore
+     * install a try-catch block, and if an exception of type
+     * <code>std::exception</code> is caught, it passes over control to this
+     * function, which will then provide some output.
      */
     void handle_std_exception (const std::exception &exc);
 
     /**
      * @internal
      *
-     * Same as above, but the type of the exception is not
-     * derived from <code>std::exception</code>, so there is little
-     * way to provide something more useful.
+     * Same as above, but the type of the exception is not derived from
+     * <code>std::exception</code>, so there is little way to provide
+     * something more useful.
      */
     void handle_unknown_exception ();
 
     /**
      * @internal
      *
-     * The following function is used for internal bookkeeping of the
-     * number of existing threads. It is not thought for use in
-     * application programs, but only for use in the template
-     * functions below.
+     * The following function is used for internal bookkeeping of the number
+     * of existing threads. It is not thought for use in application programs,
+     * but only for use in the template functions below.
      */
     void register_thread ();
 
     /**
      * @internal
      *
-     * The following function is used for internal bookkeeping of the
-     * number of existing threads. It is not thought for use in
-     * application programs, but only for use in the template
-     * functions below.
+     * The following function is used for internal bookkeeping of the number
+     * of existing threads. It is not thought for use in application programs,
+     * but only for use in the template functions below.
      */
     void deregister_thread ();
   }
@@ -717,10 +694,9 @@ namespace Threads
     /**
      * @internal
      *
-     * Given an arbitrary type RT, store an element of it and grant
-     * access to it through functions get() and set(). There are
-     * specializations for reference types (which cannot be set), and
-     * for type void.
+     * Given an arbitrary type RT, store an element of it and grant access to
+     * it through functions get() and set(). There are specializations for
+     * reference types (which cannot be set), and for type void.
      */
     template <typename RT> struct return_value
     {
@@ -744,11 +720,11 @@ namespace Threads
     /**
      * @internal
      *
-     * Given an arbitrary type RT, store an element of it and grant
-     * access to it through functions get() and set(). This is the
-     * specialization for reference types: since they cannot be set
-     * after construction time, we store a pointer instead, that holds
-     * the address of the object being referenced.
+     * Given an arbitrary type RT, store an element of it and grant access to
+     * it through functions get() and set(). This is the specialization for
+     * reference types: since they cannot be set after construction time, we
+     * store a pointer instead, that holds the address of the object being
+     * referenced.
      */
     template <typename RT> struct return_value<RT &>
     {
@@ -771,11 +747,10 @@ namespace Threads
     /**
      * @internal
      *
-     * Given an arbitrary type RT, store an element of it and grant
-     * access to it through functions get() and set(). This is the
-     * specialization for type void: there is obviously nothing to
-     * store, so no function set(), and a function get() that returns
-     * void.
+     * Given an arbitrary type RT, store an element of it and grant access to
+     * it through functions get() and set(). This is the specialization for
+     * type void: there is obviously nothing to store, so no function set(),
+     * and a function get() that returns void.
      */
     template <> struct return_value<void>
     {
@@ -809,11 +784,11 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments, and whether the second argument is a const
-     * or non-const class, depending on which the member function will
-     * also me const or non-const. There are specializations of this
-     * class for each number of arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments, and whether the second argument is a const or non-const
+     * class, depending on which the member function will also me const or
+     * non-const. There are specializations of this class for each number of
+     * arguments.
      */
     template <typename RT, typename ArgList,
               int length = std_cxx11::tuple_size<ArgList>::value>
@@ -823,8 +798,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 0 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 0 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 0>
@@ -836,8 +811,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 1 argument.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 1 argument.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 1>
@@ -849,8 +824,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 2 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 2 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 2>
@@ -863,8 +838,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 3 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 3 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 3>
@@ -878,8 +853,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 4 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 4 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 4>
@@ -894,8 +869,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 5 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 5 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 5>
@@ -911,8 +886,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 6 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 6 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 6>
@@ -929,8 +904,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 7 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 7 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 7>
@@ -948,8 +923,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 8 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 8 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 8>
@@ -968,8 +943,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 9 arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 9 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 9>
@@ -990,9 +965,8 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. This is the specialization for 10
-     * arguments.
+     * Construct a pointer to non-member function based on the template
+     * arguments. This is the specialization for 10 arguments.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr_helper<RT, ArgList, 10>
@@ -1014,14 +988,12 @@ namespace Threads
     /**
      * @internal
      *
-     * Construct a pointer to non-member function based on the
-     * template arguments. We do this by dispatching to the
-     * fun_ptr_helper classes that are overloaded on the number of
-     * elements.
+     * Construct a pointer to non-member function based on the template
+     * arguments. We do this by dispatching to the fun_ptr_helper classes that
+     * are overloaded on the number of elements.
      *
-     * Note that the last template argument for the fun_ptr_helper
-     * class is automatically computed in the default argument to the
-     * general template.
+     * Note that the last template argument for the fun_ptr_helper class is
+     * automatically computed in the default argument to the general template.
      */
     template <typename RT, typename ArgList>
     struct fun_ptr
@@ -1037,14 +1009,14 @@ namespace Threads
 #ifdef DEAL_II_WITH_THREADS
 
     /**
-     * A class that represents threads. For each thread, we create
-     * exactly one of these objects -- exactly one because it carries
-     * the returned value of the function called on the thread.
+     * A class that represents threads. For each thread, we create exactly one
+     * of these objects -- exactly one because it carries the returned value
+     * of the function called on the thread.
      *
      * While we have only one of these objects per thread, several
-     * Threads::Thread objects may refer to this descriptor. If all
-     * Thread objects go out of scope the ThreadDescriptor will detach
-     * from the thread before being destructed.
+     * Threads::Thread objects may refer to this descriptor. If all Thread
+     * objects go out of scope the ThreadDescriptor will detach from the
+     * thread before being destructed.
      */
     template <typename RT>
     struct ThreadDescriptor
@@ -1055,49 +1027,45 @@ namespace Threads
       std_cxx11::thread thread;
 
       /**
-       * An object that will hold the value returned by the function
-       * called on the thread.
+       * An object that will hold the value returned by the function called on
+       * the thread.
        *
-       * The return value is stored in a shared_ptr because we might
-       * abandon the the ThreadDescriptor.  This makes sure the object
-       * stays alive until the thread exits.
+       * The return value is stored in a shared_ptr because we might abandon
+       * the the ThreadDescriptor.  This makes sure the object stays alive
+       * until the thread exits.
        */
       std_cxx11::shared_ptr<return_value<RT> > ret_val;
 
       /**
-       * A bool variable that is initially false, is set to true when
-       * a new thread is started, and is set back to false once join()
-       * has been called.
+       * A bool variable that is initially false, is set to true when a new
+       * thread is started, and is set back to false once join() has been
+       * called.
        *
-       * We use this variable to make sure we can call join() twice on
-       * the same thread. For some reason, the C++ standard library
-       * throws a std::system_error exception if one tries to call
-       * std::thread::join twice (and in fact, before the second call,
-       * std::thread::joinable returns false) but this is a somewhat
-       * desirable thing to do because one doesn't have to keep track
-       * whether join() has been called before. Using this variable,
-       * whenever we have called join() before, the variable is set to
-       * true and we can skip over calling std::thread::join() a
-       * second time. Access to this variable is guarded by the
-       * following mutex.
+       * We use this variable to make sure we can call join() twice on the
+       * same thread. For some reason, the C++ standard library throws a
+       * std::system_error exception if one tries to call std::thread::join
+       * twice (and in fact, before the second call, std::thread::joinable
+       * returns false) but this is a somewhat desirable thing to do because
+       * one doesn't have to keep track whether join() has been called before.
+       * Using this variable, whenever we have called join() before, the
+       * variable is set to true and we can skip over calling
+       * std::thread::join() a second time. Access to this variable is guarded
+       * by the following mutex.
        *
-       * @note Historically, we did not need the mutex for this
-       * variable: threads can only be joined from the thread that
-       * created it originally. Consequently, everything that happens
-       * in a function that does not create threads (such as the
-       * join() function below) looks atomic to the outside
-       * world. Since we clear and test thread_is_active in the same
-       * function as we call std::thread::join, these actions are
-       * atomic and need no mutex. Of course, two threads may call
-       * join() on the same thread object at the same time, but this
-       * action is undefined anyway since they can not both join the
-       * same thread. That said, more recent C++ standards do not
-       * appear to have the requirement any more that the only thread
-       * that can call join() is the one that created the
-       * thread. Neither does pthread_join appear to have this
-       * requirement any more.  Consequently, we can in fact join from
-       * different threads and we test this in
-       * base/thread_validity_07.
+       * @note Historically, we did not need the mutex for this variable:
+       * threads can only be joined from the thread that created it
+       * originally. Consequently, everything that happens in a function that
+       * does not create threads (such as the join() function below) looks
+       * atomic to the outside world. Since we clear and test thread_is_active
+       * in the same function as we call std::thread::join, these actions are
+       * atomic and need no mutex. Of course, two threads may call join() on
+       * the same thread object at the same time, but this action is undefined
+       * anyway since they can not both join the same thread. That said, more
+       * recent C++ standards do not appear to have the requirement any more
+       * that the only thread that can call join() is the one that created the
+       * thread. Neither does pthread_join appear to have this requirement any
+       * more.  Consequently, we can in fact join from different threads and
+       * we test this in base/thread_validity_07.
        */
       bool thread_is_active;
 
@@ -1123,8 +1091,8 @@ namespace Threads
       }
 
       /**
-       * Start the thread and let it put its return value into the
-       * ret_val object.
+       * Start the thread and let it put its return value into the ret_val
+       * object.
        */
       void start (const std_cxx11::function<RT ()> &function)
       {
@@ -1187,9 +1155,9 @@ namespace Threads
 
 #else
     /**
-     * A class that represents threads. For each thread, we create
-     * exactly one of these objects -- exactly one because it carries
-     * the returned value of the function called on the thread.
+     * A class that represents threads. For each thread, we create exactly one
+     * of these objects -- exactly one because it carries the returned value
+     * of the function called on the thread.
      *
      * While we have only one of these objects per thread, several
      * Threads::Thread objects may refer to this descriptor.
@@ -1198,14 +1166,14 @@ namespace Threads
     struct ThreadDescriptor
     {
       /**
-       * An object that will hold the value returned by the function
-       * called on the thread.
+       * An object that will hold the value returned by the function called on
+       * the thread.
        */
       std_cxx11::shared_ptr<return_value<RT> > ret_val;
 
       /**
-       * Start the thread and let it put its return value into the
-       * ret_val object.
+       * Start the thread and let it put its return value into the ret_val
+       * object.
        */
       void start (const std_cxx11::function<RT ()> &function)
       {
@@ -1225,23 +1193,22 @@ namespace Threads
 
 
   /**
-   * An object that represents a spawned thread. This object can be
-   * freely copied around in user space, and all instances will
-   * represent the same thread and can require to wait for its
-   * termination and access its return value.
+   * An object that represents a spawned thread. This object can be freely
+   * copied around in user space, and all instances will represent the same
+   * thread and can require to wait for its termination and access its return
+   * value.
    *
-   * Threads can be abandoned, i.e. if you just call
-   * Threads::new_thread but don't care about the returned object, or
-   * if you assign the return Threads::Thread object to an object that
-   * subsequently goes out of scope, then the thread previously
-   * created will still continue to do work. You will simply not be
-   * able to access its return value any more, and it may also happen
-   * that your program terminates before the thread has finished its
-   * work.
+   * Threads can be abandoned, i.e. if you just call Threads::new_thread but
+   * don't care about the returned object, or if you assign the return
+   * Threads::Thread object to an object that subsequently goes out of scope,
+   * then the thread previously created will still continue to do work. You
+   * will simply not be able to access its return value any more, and it may
+   * also happen that your program terminates before the thread has finished
+   * its work.
    *
-   * The default value of the template argument is <code>void</code>,
-   * so if the function you are calling on a new thread has no return
-   * value, you can omit the template argument.
+   * The default value of the template argument is <code>void</code>, so if
+   * the function you are calling on a new thread has no return value, you can
+   * omit the template argument.
    *
    * @author Wolfgang Bangerth, 2003, 2009
    * @ingroup threads
@@ -1263,9 +1230,9 @@ namespace Threads
     }
 
     /**
-     * Default constructor. You can't do much with a thread object
-     * constructed this way, except for assigning it a thread object
-     * that holds data created by the new_thread() functions.
+     * Default constructor. You can't do much with a thread object constructed
+     * this way, except for assigning it a thread object that holds data
+     * created by the new_thread() functions.
      */
     Thread () {}
 
@@ -1278,10 +1245,9 @@ namespace Threads
     {}
 
     /**
-     * Join the thread represented by this object, i.e. wait for it to
-     * finish. If you have used the default constructor of this class
-     * and have not assigned a thread object to it, then this function
-     * is a no-op.
+     * Join the thread represented by this object, i.e. wait for it to finish.
+     * If you have used the default constructor of this class and have not
+     * assigned a thread object to it, then this function is a no-op.
      */
     void join () const
     {
@@ -1290,9 +1256,8 @@ namespace Threads
     }
 
     /**
-     * Get the return value of the function of the thread. Since this
-     * is only available once the thread finishes, this implicitly
-     * also calls join().
+     * Get the return value of the function of the thread. Since this is only
+     * available once the thread finishes, this implicitly also calls join().
      */
     RT return_value ()
     {
@@ -1301,8 +1266,8 @@ namespace Threads
     }
 
     /**
-     * Return true if this object has had a thread associated with it,
-     * either by using the non-default constructor or by assignment.
+     * Return true if this object has had a thread associated with it, either
+     * by using the non-default constructor or by assignment.
      */
     bool valid () const
     {
@@ -1311,10 +1276,9 @@ namespace Threads
 
 
     /**
-     * Check for equality of thread objects. Since objects of this
-     * class store an implicit pointer to an object that exists
-     * exactly once for each thread, the check is simply to compare
-     * these pointers.
+     * Check for equality of thread objects. Since objects of this class store
+     * an implicit pointer to an object that exists exactly once for each
+     * thread, the check is simply to compare these pointers.
      */
     bool operator == (const Thread &t)
     {
@@ -1323,10 +1287,10 @@ namespace Threads
 
   private:
     /**
-     * Shared pointer to the object representing the thread, and
-     * abstracting operating system functions to work on it. Boost's
-     * shared pointer implementation will make sure that that object
-     * lives as long as there is at least one subscriber to it.
+     * Shared pointer to the object representing the thread, and abstracting
+     * operating system functions to work on it. Boost's shared pointer
+     * implementation will make sure that that object lives as long as there
+     * is at least one subscriber to it.
      */
     std_cxx11::shared_ptr<internal::ThreadDescriptor<RT> > thread_descriptor;
   };
@@ -1335,8 +1299,8 @@ namespace Threads
   namespace internal
   {
     /**
-     * A general template that returns std_cxx11::ref(t) if t is of
-     * reference type, and t otherwise.
+     * A general template that returns std_cxx11::ref(t) if t is of reference
+     * type, and t otherwise.
      *
      * The case that t is of reference type is handled in a partial
      * specialization declared below.
@@ -1353,8 +1317,8 @@ namespace Threads
 
 
     /**
-     * A general template that returns std_cxx11::ref(t) if t is of
-     * reference type, and t otherwise.
+     * A general template that returns std_cxx11::ref(t) if t is of reference
+     * type, and t otherwise.
      *
      * The case that t is of reference type is handled in this partial
      * specialization.
@@ -1376,17 +1340,15 @@ namespace Threads
     /**
      * @internal
      *
-     * General template declaration of a class that is used to
-     * encapsulate arguments to global and static member functions,
-     * make sure a new thread is created and that function being run
-     * on that thread.
+     * General template declaration of a class that is used to encapsulate
+     * arguments to global and static member functions, make sure a new thread
+     * is created and that function being run on that thread.
      *
-     * Although this general template is not implemented at all, the
-     * default template argument makes sure that whenever using the
-     * name of this class, the last template argument will be computed
-     * correctly from the previous arguments, and the correct
-     * specialization for this last template argument be used, even
-     * though we need to specify it.
+     * Although this general template is not implemented at all, the default
+     * template argument makes sure that whenever using the name of this
+     * class, the last template argument will be computed correctly from the
+     * previous arguments, and the correct specialization for this last
+     * template argument be used, even though we need to specify it.
      */
     template <typename RT, typename ArgList, int length>
     class fun_encapsulator;
@@ -1780,8 +1742,8 @@ namespace Threads
 // ----------- encapsulators for functions not taking any parameters
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with no arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with no arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1801,8 +1763,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with no arguments.
+   * Overload of the non-const spawn function for member functions with no
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1850,8 +1812,8 @@ namespace Threads
 // ----------- encapsulators for unary functions
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 1 argument.
+   * Overload of the spawn function for non-member or static member functions
+   * with 1 argument.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1872,8 +1834,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 1 argument.
+   * Overload of the non-const spawn function for member functions with 1
+   * argument.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1919,8 +1881,8 @@ namespace Threads
 // ----------- encapsulators for binary functions
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 2 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 2 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1941,8 +1903,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 2 arguments.
+   * Overload of the non-const spawn function for member functions with 2
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -1988,8 +1950,8 @@ namespace Threads
 // ----------- encapsulators for ternary functions
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 3 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 3 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2012,8 +1974,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 3 arguments.
+   * Overload of the non-const spawn function for member functions with 3
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2064,8 +2026,8 @@ namespace Threads
 // ----------- encapsulators for functions with 4 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 4 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 4 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2088,8 +2050,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 4 arguments.
+   * Overload of the non-const spawn function for member functions with 4
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2139,8 +2101,8 @@ namespace Threads
 // ----------- encapsulators for functions with 5 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 5 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 5 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2165,8 +2127,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 5 arguments.
+   * Overload of the non-const spawn function for member functions with 5
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2220,8 +2182,8 @@ namespace Threads
 // ----------- encapsulators for functions with 6 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 6 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 6 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2246,8 +2208,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 6 arguments.
+   * Overload of the non-const spawn function for member functions with 6
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2303,8 +2265,8 @@ namespace Threads
 // ----------- encapsulators for functions with 7 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 7 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 7 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2333,8 +2295,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 7 arguments.
+   * Overload of the non-const spawn function for member functions with 7
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2398,8 +2360,8 @@ namespace Threads
 // ----------- encapsulators for functions with 8 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 8 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 8 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2432,8 +2394,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 8 arguments.
+   * Overload of the non-const spawn function for member functions with 8
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2505,8 +2467,8 @@ namespace Threads
 // ----------- encapsulators for functions with 9 arguments
 
   /**
-   * Overload of the spawn function for non-member or static member
-   * functions with 9 arguments.
+   * Overload of the spawn function for non-member or static member functions
+   * with 9 arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2539,8 +2501,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const spawn function for member functions
-   * with 9 arguments.
+   * Overload of the non-const spawn function for member functions with 9
+   * arguments.
    *
    * @deprecated Use new_thread() instead.
    */
@@ -2613,10 +2575,10 @@ namespace Threads
 // ----------- thread starters for functions not taking any parameters
 
   /**
-   * Overload of the new_thread function for objects that can be
-   * converted to std_cxx11::function<RT ()>, i.e. anything that can
-   * be called like a function object without arguments and returning
-   * an object of type RT (or void).
+   * Overload of the new_thread function for objects that can be converted to
+   * std_cxx11::function<RT ()>, i.e. anything that can be called like a
+   * function object without arguments and returning an object of type RT (or
+   * void).
    *
    * @ingroup threads
    */
@@ -2629,8 +2591,8 @@ namespace Threads
   }
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with no arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with no arguments.
    *
    * @ingroup threads
    */
@@ -2644,8 +2606,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with no arguments.
+   * Overload of the non-const new_thread function for member functions with
+   * no arguments.
    *
    * @ingroup threads
    */
@@ -2663,8 +2625,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with no arguments.
+   * Overload of the new_thread function for const member functions with no
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2685,8 +2647,8 @@ namespace Threads
 // ----------- thread starters for unary functions
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 1 argument.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 1 argument.
    *
    * @ingroup threads
    */
@@ -2705,8 +2667,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 1 argument.
+   * Overload of the non-const new_thread function for member functions with 1
+   * argument.
    *
    * @ingroup threads
    */
@@ -2725,8 +2687,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 1 argument.
+   * Overload of the new_thread function for const member functions with 1
+   * argument.
    *
    * @ingroup threads
    */
@@ -2747,8 +2709,8 @@ namespace Threads
 // ----------- thread starters for binary functions
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 2 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 2 arguments.
    *
    * @ingroup threads
    */
@@ -2769,8 +2731,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 2 arguments.
+   * Overload of the non-const new_thread function for member functions with 2
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2791,8 +2753,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 2 arguments.
+   * Overload of the new_thread function for const member functions with 2
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2815,8 +2777,8 @@ namespace Threads
 // ----------- thread starters for ternary functions
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 3 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 3 arguments.
    *
    * @ingroup threads
    */
@@ -2840,8 +2802,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 3 arguments.
+   * Overload of the non-const new_thread function for member functions with 3
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2865,8 +2827,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 3 arguments.
+   * Overload of the new_thread function for const member functions with 3
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2893,8 +2855,8 @@ namespace Threads
 // ----------- thread starters for functions with 4 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 4 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 4 arguments.
    *
    * @ingroup threads
    */
@@ -2920,8 +2882,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 4 arguments.
+   * Overload of the non-const new_thread function for member functions with 4
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2947,8 +2909,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 4 arguments.
+   * Overload of the new_thread function for const member functions with 4
+   * arguments.
    *
    * @ingroup threads
    */
@@ -2976,8 +2938,8 @@ namespace Threads
 // ----------- thread starters for functions with 5 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 5 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 5 arguments.
    *
    * @ingroup threads
    */
@@ -3006,8 +2968,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 5 arguments.
+   * Overload of the non-const new_thread function for member functions with 5
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3036,8 +2998,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 5 arguments.
+   * Overload of the new_thread function for const member functions with 5
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3068,8 +3030,8 @@ namespace Threads
 // ----------- thread starters for functions with 6 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 6 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 6 arguments.
    *
    * @ingroup threads
    */
@@ -3100,8 +3062,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 6 arguments.
+   * Overload of the non-const new_thread function for member functions with 6
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3132,8 +3094,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 6 arguments.
+   * Overload of the new_thread function for const member functions with 6
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3166,8 +3128,8 @@ namespace Threads
 // ----------- thread starters for functions with 7 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 7 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 7 arguments.
    *
    * @ingroup threads
    */
@@ -3201,8 +3163,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 7 arguments.
+   * Overload of the non-const new_thread function for member functions with 7
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3236,8 +3198,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 7 arguments.
+   * Overload of the new_thread function for const member functions with 7
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3273,8 +3235,8 @@ namespace Threads
 // ----------- thread starters for functions with 8 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 8 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 8 arguments.
    *
    * @ingroup threads
    */
@@ -3311,8 +3273,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 8 arguments.
+   * Overload of the non-const new_thread function for member functions with 8
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3349,8 +3311,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 8 arguments.
+   * Overload of the new_thread function for const member functions with 8
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3389,8 +3351,8 @@ namespace Threads
 // ----------- thread starters for functions with 9 arguments
 
   /**
-   * Overload of the new_thread function for non-member or static
-   * member functions with 9 arguments.
+   * Overload of the new_thread function for non-member or static member
+   * functions with 9 arguments.
    *
    * @ingroup threads
    */
@@ -3429,8 +3391,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_thread function for member
-   * functions with 9 arguments.
+   * Overload of the non-const new_thread function for member functions with 9
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3469,8 +3431,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_thread function for const member functions
-   * with 9 arguments.
+   * Overload of the new_thread function for const member functions with 9
+   * arguments.
    *
    * @ingroup threads
    */
@@ -3511,9 +3473,9 @@ namespace Threads
 // ------------------------ ThreadGroup -------------------------------------
 
   /**
-   * A container for thread objects. Allows to add new thread objects
-   * and wait for them all together. The thread objects need to have
-   * the same return value for the called function.
+   * A container for thread objects. Allows to add new thread objects and wait
+   * for them all together. The thread objects need to have the same return
+   * value for the called function.
    *
    * @author Wolfgang Bangerth, 2003
    * @ingroup threads
@@ -3523,8 +3485,7 @@ namespace Threads
   {
   public:
     /**
-     * Add another thread object to
-     * the collection.
+     * Add another thread object to the collection.
      */
     ThreadGroup &operator += (const Thread<RT> &t)
     {
@@ -3533,11 +3494,10 @@ namespace Threads
     }
 
     /**
-     * Wait for all threads in the collection to finish. It is not a
-     * problem if some of them have already been waited for, i.e. you
-     * may call this function more than once, and you can also add new
-     * thread objects between subsequent calls to this function if you
-     * want.
+     * Wait for all threads in the collection to finish. It is not a problem
+     * if some of them have already been waited for, i.e. you may call this
+     * function more than once, and you can also add new thread objects
+     * between subsequent calls to this function if you want.
      */
     void join_all () const
     {
@@ -3564,8 +3524,7 @@ namespace Threads
     template <typename> struct TaskDescriptor;
 
     /**
-     * The task class for TBB that is used by the TaskDescriptor
-     * class.
+     * The task class for TBB that is used by the TaskDescriptor class.
      */
     template <typename RT>
     struct TaskEntryPoint : public tbb::task
@@ -3603,24 +3562,21 @@ namespace Threads
     /**
      * @internal
      *
-     * Base class describing a task. This is the basic class
-     * abstracting the Threading Building Blocks implementation of
-     * tasks.  It provides a mechanism to start a new task, as well as
-     * for joining it.
+     * Base class describing a task. This is the basic class abstracting the
+     * Threading Building Blocks implementation of tasks.  It provides a
+     * mechanism to start a new task, as well as for joining it.
      *
-     * Internally, the way things are implemented is that all Task<>
-     * objects keep a shared pointer to the task descriptor. When the
-     * last Task<> object goes out of scope, the destructor of the
-     * descriptor is called. Since tasks can not be abandoned, the
-     * destructor makes sure that the task is finished before it can
-     * continue to destroy the object.
+     * Internally, the way things are implemented is that all Task<> objects
+     * keep a shared pointer to the task descriptor. When the last Task<>
+     * object goes out of scope, the destructor of the descriptor is called.
+     * Since tasks can not be abandoned, the destructor makes sure that the
+     * task is finished before it can continue to destroy the object.
      *
-     * Note that unlike threads, tasks are not always started right
-     * away, and so the starting thread can't rely on the fact that
-     * the started task can copy things off the spawning thread's
-     * stack frame. As a consequence, the task description needs to
-     * include a way to store the function and its arguments that
-     * shall be run on the task.
+     * Note that unlike threads, tasks are not always started right away, and
+     * so the starting thread can't rely on the fact that the started task can
+     * copy things off the spawning thread's stack frame. As a consequence,
+     * the task description needs to include a way to store the function and
+     * its arguments that shall be run on the task.
      *
      * @author Wolfgang Bangerth, 2009
      */
@@ -3629,18 +3585,16 @@ namespace Threads
     {
     private:
       /**
-       * The function and its arguments that are to be run on the
-       * task.
+       * The function and its arguments that are to be run on the task.
        */
       std_cxx11::function<RT ()> function;
 
       /**
-       * Variable holding the data the TBB needs to work with a
-       * task. Set by the queue_up_task() function. Note that the
-       * object behind this pointer will be deleted upon termination
-       * of the task, so we do not have to do so ourselves. In
-       * particular, if all objects with pointers to this
-       * task_description object go out of scope then no action is
+       * Variable holding the data the TBB needs to work with a task. Set by
+       * the queue_up_task() function. Note that the object behind this
+       * pointer will be deleted upon termination of the task, so we do not
+       * have to do so ourselves. In particular, if all objects with pointers
+       * to this task_description object go out of scope then no action is
        * needed on our behalf.
        */
       tbb::task *task;
@@ -3658,23 +3612,20 @@ namespace Threads
     public:
 
       /**
-       * Constructor. Take the function to be run on this task as
-       * argument.
+       * Constructor. Take the function to be run on this task as argument.
        */
       TaskDescriptor (const std_cxx11::function<RT ()> &function);
 
       /**
-       * Default constructor. Throws an exception since we want to
-       * queue a task immediately upon construction of these objects
-       * to make sure that each TaskDescriptor object corresponds to
-       * exactly one task.
+       * Default constructor. Throws an exception since we want to queue a
+       * task immediately upon construction of these objects to make sure that
+       * each TaskDescriptor object corresponds to exactly one task.
        */
       TaskDescriptor ();
 
       /**
-       * Copy constructor. Throws an exception since we want to make
-       * sure that each TaskDescriptor object corresponds to exactly
-       * one task.
+       * Copy constructor. Throws an exception since we want to make sure that
+       * each TaskDescriptor object corresponds to exactly one task.
        */
       TaskDescriptor (const TaskDescriptor &);
 
@@ -3684,17 +3635,17 @@ namespace Threads
       ~TaskDescriptor ();
 
       /**
-       * Queue up the task to the scheduler. We need to do this in a
-       * separate function since the new tasks needs to access objects
-       * from the current object and that can only reliably happen if
-       * the current object is completely constructed already.
+       * Queue up the task to the scheduler. We need to do this in a separate
+       * function since the new tasks needs to access objects from the current
+       * object and that can only reliably happen if the current object is
+       * completely constructed already.
        */
       void queue_task ();
 
       /**
-       * Join a task, i.e. wait for it to finish. This function can
-       * safely be called from different threads at the same time, and
-       * can also be called more than once.
+       * Join a task, i.e. wait for it to finish. This function can safely be
+       * called from different threads at the same time, and can also be
+       * called more than once.
        */
       void join ();
 
@@ -3796,8 +3747,8 @@ namespace Threads
 #else        // no threading enabled
 
     /**
-     * A way to describe tasks. Since we are in non-MT mode at this
-     * place, things are a lot simpler than in MT mode.
+     * A way to describe tasks. Since we are in non-MT mode at this place,
+     * things are a lot simpler than in MT mode.
      */
     template <typename RT>
     struct TaskDescriptor
@@ -3808,8 +3759,8 @@ namespace Threads
       return_value<RT> ret_val;
 
       /**
-       * Constructor. Call the given function and emplace the return
-       * value into the slot reserved for this purpose.
+       * Constructor. Call the given function and emplace the return value
+       * into the slot reserved for this purpose.
        */
       TaskDescriptor (const std_cxx11::function<RT ()> &function)
       {
@@ -3817,14 +3768,14 @@ namespace Threads
       }
 
       /**
-       * Wait for the task to return. Since we are in non-MT mode
-       * here, there is nothing to do.
+       * Wait for the task to return. Since we are in non-MT mode here, there
+       * is nothing to do.
        */
       static void join () {}
 
       /**
-       * Run the task. Since we are here in non-MT mode, there is
-       * nothing to do that the constructor hasn't already done.
+       * Run the task. Since we are here in non-MT mode, there is nothing to
+       * do that the constructor hasn't already done.
        */
       static void queue_task () {}
     };
@@ -3836,11 +3787,11 @@ namespace Threads
 
 
   /**
-   * Describes one task object based on the Threading Building Blocks'
-   * Task. Note that the call to join() must be executed on the same
-   * thread as the call to the constructor. Otherwise, there might be
-   * a deadlock. In other words, a Task object should never passed on
-   * to another task for calling the join() method.
+   * Describes one task object based on the Threading Building Blocks' Task.
+   * Note that the call to join() must be executed on the same thread as the
+   * call to the constructor. Otherwise, there might be a deadlock. In other
+   * words, a Task object should never passed on to another task for calling
+   * the join() method.
    *
    * @author Wolfgang Bangerth, 2009
    * @ingroup threads
@@ -3850,11 +3801,11 @@ namespace Threads
   {
   public:
     /**
-     * Construct a task object given a function object to execute on
-     * the task, and then schedule this function for execution.
+     * Construct a task object given a function object to execute on the task,
+     * and then schedule this function for execution.
      *
-     * @post Using this constructor automatically makes the task
-     * object joinable().
+     * @post Using this constructor automatically makes the task object
+     * joinable().
      */
     Task (const std_cxx11::function<RT ()> &function_object)
     {
@@ -3870,8 +3821,8 @@ namespace Threads
     /**
      * Copy constructor.
      *
-     * @post Using this constructor automatically makes the task
-     * object joinable().
+     * @post Using this constructor automatically makes the task object
+     * joinable().
      */
     Task (const Task<RT> &t)
       :
@@ -3880,27 +3831,25 @@ namespace Threads
 
 
     /**
-     * Default constructor. You can't do much with a task object
-     * constructed this way, except for assigning it a task object
-     * that holds data created by the Threads::new_task() functions.
+     * Default constructor. You can't do much with a task object constructed
+     * this way, except for assigning it a task object that holds data created
+     * by the Threads::new_task() functions.
      *
-     * @post Using this constructor leaves the object in an unjoinable
-     *   state, i.e., joinable() will return false.
+     * @post Using this constructor leaves the object in an unjoinable state,
+     * i.e., joinable() will return false.
      */
     Task () {}
 
     /**
-     * Join the task represented by this object, i.e. wait for it to
-     * finish.
+     * Join the task represented by this object, i.e. wait for it to finish.
      *
      * A task can be joined multiple times (while the first join() operation
      * may block until the task has completed running, all successive attempts
      * to join will return immediately).
      *
      * @pre You can't call this function if you have used the default
-     *   constructor of this class and have not assigned a task object
-     *   to it. In other words, the function joinable() must return
-     *   true.
+     * constructor of this class and have not assigned a task object to it. In
+     * other words, the function joinable() must return true.
      */
     void join () const
     {
@@ -3909,11 +3858,10 @@ namespace Threads
     }
 
     /**
-     * Return whether the current object can be joined. You can join a
-     * task object once a task (typically created with
-     * Threads::new_task()) has actually been assigned to it. On the
-     * other hand, the function returns false if the object has been
-     * default constructed.
+     * Return whether the current object can be joined. You can join a task
+     * object once a task (typically created with Threads::new_task()) has
+     * actually been assigned to it. On the other hand, the function returns
+     * false if the object has been default constructed.
      *
      * A task can be joined multiple times (while the first join() operation
      * may block until the task has completed running, all successive attempts
@@ -3929,16 +3877,14 @@ namespace Threads
 
 
     /**
-     * Get the return value of the function of the task. Since this is
-     * only available once the task finishes, this implicitly also
-     * calls join(). You can call this function multiple times
-     * as long as the object refers to the same task, and expect to get
-     * the same return value every time.
+     * Get the return value of the function of the task. Since this is only
+     * available once the task finishes, this implicitly also calls join().
+     * You can call this function multiple times as long as the object refers
+     * to the same task, and expect to get the same return value every time.
      *
      * @pre You can't call this function if you have used the default
-     *   constructor of this class and have not assigned a task object
-     *   to it. In other words, the function joinable() must return
-     *   true.
+     * constructor of this class and have not assigned a task object to it. In
+     * other words, the function joinable() must return true.
      */
     RT return_value ()
     {
@@ -3948,9 +3894,9 @@ namespace Threads
 
 
     /**
-     * Check for equality of task objects. Since objects of this class
-     * store an implicit pointer to an object that exists exactly once
-     * for each task, the check is simply to compare these pointers.
+     * Check for equality of task objects. Since objects of this class store
+     * an implicit pointer to an object that exists exactly once for each
+     * task, the check is simply to compare these pointers.
      */
     bool operator == (const Task &t)
     {
@@ -3958,8 +3904,10 @@ namespace Threads
       return task_descriptor == t.task_descriptor;
     }
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception
@@ -3968,9 +3916,9 @@ namespace Threads
     //@}
   private:
     /**
-     * Shared pointer to the object representing the task. Boost's
-     * shared pointer implementation will make sure that that object
-     * lives as long as there is at least one subscriber to it.
+     * Shared pointer to the object representing the task. Boost's shared
+     * pointer implementation will make sure that that object lives as long as
+     * there is at least one subscriber to it.
      */
     std_cxx11::shared_ptr<internal::TaskDescriptor<RT> > task_descriptor;
   };
@@ -3978,10 +3926,10 @@ namespace Threads
 
 
   /**
-   * Overload of the new_task function for objects that can be
-   * converted to std_cxx11::function<RT ()>, i.e. anything that can
-   * be called like a function object without arguments and returning
-   * an object of type RT (or void).
+   * Overload of the new_task function for objects that can be converted to
+   * std_cxx11::function<RT ()>, i.e. anything that can be called like a
+   * function object without arguments and returning an object of type RT (or
+   * void).
    *
    * @ingroup threads
    */
@@ -4009,8 +3957,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with no arguments.
+   * Overload of the non-const new_task function for member functions with no
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4027,8 +3975,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * no arguments.
+   * Overload of the new_task function for const member functions with no
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4069,8 +4017,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 1 argument.
+   * Overload of the non-const new_task function for member functions with 1
+   * argument.
    *
    * @ingroup threads
    */
@@ -4089,8 +4037,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * argument.
+   * Overload of the new_task function for const member functions with 1
+   * argument.
    *
    * @ingroup threads
    */
@@ -4133,8 +4081,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 2 arguments.
+   * Overload of the non-const new_task function for member functions with 2
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4155,8 +4103,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 2
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4204,8 +4152,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 3 arguments.
+   * Overload of the non-const new_task function for member functions with 3
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4229,8 +4177,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 3
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4284,8 +4232,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 4 arguments.
+   * Overload of the non-const new_task function for member functions with 4
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4311,8 +4259,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 4
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4370,8 +4318,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 5 arguments.
+   * Overload of the non-const new_task function for member functions with 5
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4400,8 +4348,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 5
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4464,8 +4412,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 6 arguments.
+   * Overload of the non-const new_task function for member functions with 6
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4496,8 +4444,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 6
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4565,8 +4513,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 7 arguments.
+   * Overload of the non-const new_task function for member functions with 7
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4600,8 +4548,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 7
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4675,8 +4623,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 8 arguments.
+   * Overload of the non-const new_task function for member functions with 8
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4713,8 +4661,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 8
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4793,8 +4741,8 @@ namespace Threads
 
 
   /**
-   * Overload of the non-const new_task function for member functions
-   * with 9 arguments.
+   * Overload of the non-const new_task function for member functions with 9
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4833,8 +4781,8 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overload of the new_task function for const member functions with
-   * arguments.
+   * Overload of the new_task function for const member functions with 9
+   * arguments.
    *
    * @ingroup threads
    */
@@ -4876,14 +4824,14 @@ namespace Threads
 // ------------------------ TaskGroup -------------------------------------
 
   /**
-   * A container for task objects. Allows to add new task objects and
-   * wait for them all together. The task objects need to have the
-   * same return value for the called function.
+   * A container for task objects. Allows to add new task objects and wait for
+   * them all together. The task objects need to have the same return value
+   * for the called function.
    *
-   * Note that the call to join_all() must be executed on the same
-   * thread as the calls that add subtasks. Otherwise, there might be
-   * a deadlock. In other words, a Task object should never passed on
-   * to another task for calling the join() method.
+   * Note that the call to join_all() must be executed on the same thread as
+   * the calls that add subtasks. Otherwise, there might be a deadlock. In
+   * other words, a Task object should never passed on to another task for
+   * calling the join() method.
    *
    * @author Wolfgang Bangerth, 2003
    * @ingroup tasks
@@ -4893,8 +4841,7 @@ namespace Threads
   {
   public:
     /**
-     * Add another task object to
-     * the collection.
+     * Add another task object to the collection.
      */
     TaskGroup &operator += (const Task<RT> &t)
     {
@@ -4903,11 +4850,10 @@ namespace Threads
     }
 
     /**
-     * Wait for all tasks in the collection to finish. It is not a
-     * problem if some of them have already been waited for, i.e. you
-     * may call this function more than once, and you can also add new
-     * task objects between subsequent calls to this function if you
-     * want.
+     * Wait for all tasks in the collection to finish. It is not a problem if
+     * some of them have already been waited for, i.e. you may call this
+     * function more than once, and you can also add new task objects between
+     * subsequent calls to this function if you want.
      */
     void join_all () const
     {
index d68715bf2a30838cfdf64ab84983b143d2cb0d08..ded4f87cfc7d229846328335af260c430e65ea82 100644 (file)
@@ -34,22 +34,14 @@ DEAL_II_NAMESPACE_OPEN
 namespace TimeStepping
 {
   /**
-   * Runge-Kutta methods available:
-   *   - Explicit methods:
-   *     - FORWARD_EULER: first order
-   *     - RK_THIRD_ORDER: third order Runge-Kutta
-   *     - RK_CLASSIC_FOURTH_ORDER: classical fourth order Runge-Kutta
-   *   - Implicit methods:
-   *     - BACKWARD_EULER: first order
-   *     - IMPLICIT_MIDPOINT: second order
-   *     - CRANK_NICOLSON: second order
-   *     - SDIRK_TWO_STAGES: second order
-   *   - Embedded explicit methods:
-   *     - HEUN_EULER: second order
-   *     - BOGACKI_SHAMPINE: third order
-   *     - DOPRI: Dormand-Prince fifth order (method used by ode45 in MATLAB)
-   *     - FEHLBERG: fifth order
-   *     - CASH_KARP: firth order
+   * Runge-Kutta methods available: - Explicit methods: - FORWARD_EULER: first
+   * order - RK_THIRD_ORDER: third order Runge-Kutta -
+   * RK_CLASSIC_FOURTH_ORDER: classical fourth order Runge-Kutta - Implicit
+   * methods: - BACKWARD_EULER: first order - IMPLICIT_MIDPOINT: second order
+   * - CRANK_NICOLSON: second order - SDIRK_TWO_STAGES: second order -
+   * Embedded explicit methods: - HEUN_EULER: second order - BOGACKI_SHAMPINE:
+   * third order - DOPRI: Dormand-Prince fifth order (method used by ode45 in
+   * MATLAB) - FEHLBERG: fifth order - CASH_KARP: firth order
    */
   enum runge_kutta_method { FORWARD_EULER, RK_THIRD_ORDER, RK_CLASSIC_FOURTH_ORDER,
                             BACKWARD_EULER, IMPLICIT_MIDPOINT, CRANK_NICOLSON,
@@ -60,10 +52,10 @@ namespace TimeStepping
 
 
   /**
-   * Reason for exiting evolve_one_time_step when using an embedded
-   * method: DELTA_T (the time step is in the valid range), MIN_DELTA_T (the
-   * time step was increased to the minimum acceptable time step), MAX_DELTA_T
-   * (the time step was reduced to the maximum acceptable time step).
+   * Reason for exiting evolve_one_time_step when using an embedded method:
+   * DELTA_T (the time step is in the valid range), MIN_DELTA_T (the time step
+   * was increased to the minimum acceptable time step), MAX_DELTA_T (the time
+   * step was reduced to the maximum acceptable time step).
    */
   enum embedded_runge_kutta_time_step { DELTA_T, MIN_DELTA_T, MAX_DELTA_T };
 
@@ -84,14 +76,13 @@ namespace TimeStepping
 
     /**
      * Purely virtual function. This function is used to advance from time @p
-     * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that should be
-     * integrated, the input parameters are the time t and the vector y and the
-     * output is value of f at this point. @p J_inverse is a vector
-     * functions that compute the inverse of the Jacobians associated to the
-     * implicit problems. The input parameters are the
-     * time, $ \tau $, and a vector. The output is the value of function
-     * at this point. This function returns the time at the end of the
-     * time step.
+     * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that
+     * should be integrated, the input parameters are the time t and the
+     * vector y and the output is value of f at this point. @p J_inverse is a
+     * vector functions that compute the inverse of the Jacobians associated
+     * to the implicit problems. The input parameters are the time, $ \tau $,
+     * and a vector. The output is the value of function at this point. This
+     * function returns the time at the end of the time step.
      */
     virtual double evolve_one_time_step(
       std::vector<std_cxx11::function<VECTOR (const double, const VECTOR &)> > &F,
@@ -133,16 +124,15 @@ namespace TimeStepping
      */
     virtual void initialize(runge_kutta_method method) = 0;
     /**
-     * This function is used to advance from time @p
-     * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that should be
-     * integrated, the input parameters are the time t and the vector y and the
-     * output is value of f at this point. @p J_inverse is a vector
-     * functions that compute the inverse of the Jacobians associated to the
-     * implicit problems. The input parameters are the
-     * time, $ \tau $, and a vector. The output is the value of function
-     * at this point. This function returns the time at the end of the
-     * time step. When using Runge-Kutta methods, @p F and @ J_inverse can
-     * only contain one element.
+     * This function is used to advance from time @p t to t+ @p delta_t. @p F
+     * is a vector of functions $ f(t,y) $ that should be integrated, the
+     * input parameters are the time t and the vector y and the output is
+     * value of f at this point. @p J_inverse is a vector functions that
+     * compute the inverse of the Jacobians associated to the implicit
+     * problems. The input parameters are the time, $ \tau $, and a vector.
+     * The output is the value of function at this point. This function
+     * returns the time at the end of the time step. When using Runge-Kutta
+     * methods, @p F and @ J_inverse can only contain one element.
      */
     double evolve_one_time_step(
       std::vector<std_cxx11::function<VECTOR (const double, const VECTOR &)> > &F,
@@ -152,14 +142,14 @@ namespace TimeStepping
       VECTOR &y);
 
     /**
-     * Purely virtual function. This function is used to advance from time @p t
-     * to t+ @p delta_t. @p f  is the function $ f(t,y) $ that should be
-     * integrated, the input parameters are the time t and the vector y and the
-     * output is value of f at this point. @p id_minus_tau_J_inverse is a function
-     * that computes $ inv(I-\tau J)$ where $ I $ is the identity matrix,
-     * $ \tau $ is given, and $ J $ is the Jacobian $ \frac{\partial
-     * J}{\partial y} $. The input parameters are the time, $ \tau $, and
-     * vector. The output is the value of function at this point.
+     * Purely virtual function. This function is used to advance from time @p
+     * t to t+ @p delta_t. @p f  is the function $ f(t,y) $ that should be
+     * integrated, the input parameters are the time t and the vector y and
+     * the output is value of f at this point. @p id_minus_tau_J_inverse is a
+     * function that computes $ inv(I-\tau J)$ where $ I $ is the identity
+     * matrix, $ \tau $ is given, and $ J $ is the Jacobian $ \frac{\partial
+     * J}{\partial y} $. The input parameters are the time, $ \tau $, and a
+     * vector. The output is the value of function at this point.
      * evolve_one_time_step returns the time at the end of the time step.
      */
     virtual double evolve_one_time_step(
@@ -194,7 +184,8 @@ namespace TimeStepping
 
 
   /**
-   * ExplicitRungeKutta is derived from RungeKutta and implement the explicit methods.
+   * ExplicitRungeKutta is derived from RungeKutta and implement the explicit
+   * methods.
    */
   template <typename VECTOR>
   class ExplicitRungeKutta : public RungeKutta<VECTOR>
@@ -221,13 +212,13 @@ namespace TimeStepping
     /**
      * This function is used to advance from time @p t to t+ @p delta_t. @p f
      * is the function $ f(t,y) $ that should be integrated, the input
-     * parameters are the time t and the vector y and the output is value of
-     * f at this point. @p id_minus_tau_J_inverse is a function that computes
-     * $ inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau
-     * $ is given, and $ J $ is the Jacobian $ \frac{\partial
-     * J}{\partial y} $. The input parameter are the time, $ \tau $, and
-     * a vector. The output is the value of function at this point.
-     * evolve_one_time_step returns the time at the end of the time step.
+     * parameters are the time t and the vector y and the output is value of f
+     * at this point. @p id_minus_tau_J_inverse is a function that computes $
+     * inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau $ is given,
+     * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+     * parameter are the time, $ \tau $, and a vector. The output is the value
+     * of function at this point. evolve_one_time_step returns the time at the
+     * end of the time step.
      */
     double evolve_one_time_step(
       std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
@@ -237,11 +228,11 @@ namespace TimeStepping
       VECTOR &y);
 
     /**
-     * This function is used to advance from time @p t to t+ @p delta_t.
-     * This function is similar to the one derived from RungeKutta, but
-     * does not required id_minus_tau_J_inverse because it is not used for
-     * explicit methods. evolve_one_time_step returns the time at the end of the
-     * time step.
+     * This function is used to advance from time @p t to t+ @p delta_t. This
+     * function is similar to the one derived from RungeKutta, but does not
+     * required id_minus_tau_J_inverse because it is not used for explicit
+     * methods. evolve_one_time_step returns the time at the end of the time
+     * step.
      */
     double evolve_one_time_step(std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
                                 double t,
@@ -280,9 +271,8 @@ namespace TimeStepping
 
 
   /**
-   * This class is derived from RungeKutta and implement the implicit
-   * methods. This class works only for Diagonal Implicit Runge-Kutta
-   * (DIRK) methods.
+   * This class is derived from RungeKutta and implement the implicit methods.
+   * This class works only for Diagonal Implicit Runge-Kutta (DIRK) methods.
    */
   template <typename VECTOR>
   class ImplicitRungeKutta : public RungeKutta<VECTOR>
@@ -292,8 +282,8 @@ namespace TimeStepping
 
     /**
      * Default constructor. initialize(runge_kutta_method) and
-     * set_newton_solver_parameters(unsigned int,double)
-     * need to be called before the object can be used.
+     * set_newton_solver_parameters(unsigned int,double) need to be called
+     * before the object can be used.
      */
     ImplicitRungeKutta() {};
 
@@ -312,14 +302,13 @@ namespace TimeStepping
     /**
      * This function is used to advance from time @p t to t+ @p delta_t. @p f
      * is the function $ f(t,y) $ that should be integrated, the input
-     * parameters are the time t and the vector y and the output is value of
-     * f at this point. @p id_minus_tau_J_inverse is a function that computes
-     * $ (I-\tau J)^{-1}$ where $ I $ is the identity matrix, $ \tau $
-     * is given, and $ J $ is the Jacobian $ \frac{\partial
-     * J}{\partial y} $. The input parameters this function receives
-     * are the time, $ \tau $, and
-     * a vector. The output is the value of function at this point.
-     * evolve_one_time_step returns the time at the end of the time step.
+     * parameters are the time t and the vector y and the output is value of f
+     * at this point. @p id_minus_tau_J_inverse is a function that computes $
+     * (I-\tau J)^{-1}$ where $ I $ is the identity matrix, $ \tau $ is given,
+     * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+     * parameters this function receives are the time, $ \tau $, and a vector.
+     * The output is the value of function at this point. evolve_one_time_step
+     * returns the time at the end of the time step.
      */
     double evolve_one_time_step(
       std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
@@ -335,9 +324,8 @@ namespace TimeStepping
     void set_newton_solver_parameters(unsigned int max_it, double tolerance);
 
     /**
-     * Structure that stores the name of the method, the number of
-     * Newton iterations and the norm of the residual when exiting the
-     * Newton solver.
+     * Structure that stores the name of the method, the number of Newton
+     * iterations and the norm of the residual when exiting the Newton solver.
      */
     struct Status : public TimeStepping<VECTOR>::Status
     {
@@ -382,9 +370,9 @@ namespace TimeStepping
                           VECTOR &residual) const;
 
     /**
-     * When using SDIRK, there is no need to compute the linear combination
-     * of the stages. Thus, when this flag is true, the linear combination
-     * is skipped.
+     * When using SDIRK, there is no need to compute the linear combination of
+     * the stages. Thus, when this flag is true, the linear combination is
+     * skipped.
      */
     bool skip_linear_combi;
 
@@ -418,8 +406,8 @@ namespace TimeStepping
 
     /**
      * Default constructor. initialize(runge_kutta_method) and
-     * set_time_adaptation_parameters(double, double, double, double, double, double)
-     * need to be called before the object can be used.
+     * set_time_adaptation_parameters(double, double, double, double, double,
+     * double) need to be called before the object can be used.
      */
     EmbeddedExplicitRungeKutta() {};
 
@@ -456,13 +444,13 @@ namespace TimeStepping
     /**
      * This function is used to advance from time @p t to t+ @p delta_t. @p f
      * is the function $ f(t,y) $ that should be integrated, the input
-     * parameters are the time t and the vector y and the output is value of
-     * f at this point. @p id_minus_tau_J_inverse is a function that computes
-     * $ inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau
-     * $ is given, and $ J $ is the Jacobian $ \frac{\partial
-     * J}{\partial y} $. The input parameters are the time, $ \tau $, and
-     * a vector. The output is the value of function at this point.
-     * evolve_one_time_step returns the time at the end of the time step.
+     * parameters are the time t and the vector y and the output is value of f
+     * at this point. @p id_minus_tau_J_inverse is a function that computes $
+     * inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau $ is given,
+     * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+     * parameters are the time, $ \tau $, and a vector. The output is the
+     * value of function at this point. evolve_one_time_step returns the time
+     * at the end of the time step.
      */
     double evolve_one_time_step(
       std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
@@ -472,11 +460,11 @@ namespace TimeStepping
       VECTOR &y);
 
     /**
-     * This function is used to advance from time @p t to t+ @p delta_t.
-     * This function is similar to the one derived from TimeStepping, but
-     * does not required id_minus_tau_J_inverse because it is not used for
-     * explicit methods. evolve_one_time_step returns the time at the end of the
-     * time step.
+     * This function is used to advance from time @p t to t+ @p delta_t. This
+     * function is similar to the one derived from TimeStepping, but does not
+     * required id_minus_tau_J_inverse because it is not used for explicit
+     * methods. evolve_one_time_step returns the time at the end of the time
+     * step.
      */
     double evolve_one_time_step(std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
                                 double t,
@@ -495,9 +483,9 @@ namespace TimeStepping
 
     /**
      * Structure that stores the name of the method, the reason to exit
-     * evolve_one_time_step, the number of iteration inside n_iterations, a guess
-     * of what the next time step should be, and an estimate of the norm of
-     * the error.
+     * evolve_one_time_step, the number of iteration inside n_iterations, a
+     * guess of what the next time step should be, and an estimate of the norm
+     * of the error.
      */
     struct Status : public TimeStepping<VECTOR>::Status
     {
@@ -524,14 +512,14 @@ namespace TimeStepping
                         std::vector<VECTOR> &f_stages);
 
     /**
-     * This parameter is the factor (>1) by which the time step is
-     * multiplied when the time stepping can be coarsen.
+     * This parameter is the factor (>1) by which the time step is multiplied
+     * when the time stepping can be coarsen.
      */
     double coarsen_param;
 
     /**
-     * This parameter is the factor (<1) by which the time step is
-     * multiplied when the time stepping must be refined.
+     * This parameter is the factor (<1) by which the time step is multiplied
+     * when the time stepping must be refined.
      */
     double refine_param;
 
@@ -546,20 +534,20 @@ namespace TimeStepping
     double max_delta_t;
 
     /**
-     * Refinement tolerance: if the error estimate is larger than
-     * refine_tol, the time step is refined.
+     * Refinement tolerance: if the error estimate is larger than refine_tol,
+     * the time step is refined.
      */
     double refine_tol;
 
     /**
-     * Coarsening tolerance: if the error estimate is smaller than
-     * coarse_tol, the time step is coarsen.
+     * Coarsening tolerance: if the error estimate is smaller than coarse_tol,
+     * the time step is coarsen.
      */
     double coarsen_tol;
 
     /**
-     * If the flag is true, the last stage is the same as the first stage
-     * and one evaluation of f can be saved.
+     * If the flag is true, the last stage is the same as the first stage and
+     * one evaluation of f can be saved.
      */
     bool last_same_as_first;
 
@@ -574,8 +562,8 @@ namespace TimeStepping
     std::vector<double> b2;
 
     /**
-     * If the last_same_as_first flag is set to true, the last stage is
-     * saved and reused as the first stage of the next time step.
+     * If the last_same_as_first flag is set to true, the last stage is saved
+     * and reused as the first stage of the next time step.
      */
     VECTOR *last_stage;
 
index bdd0c7a9894fa3ff90932e20941ce170dd9fffd0..1bbc9643b1923eab4ac9abfa7b1ab933a879c6a9 100644 (file)
@@ -33,11 +33,11 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * This is a very simple class which provides information about both the CPU
- * time and the wallclock time elapsed since the timer was started last
- * time. Information is retrieved from the system on the basis of clock cycles
- * since last time the computer was booted for the CPU time. The wall time is
- * based on the system clock accessed by @p gettimeofday, with a typical
- * accuracy of 0.01 ms on linux systems.
+ * time and the wallclock time elapsed since the timer was started last time.
+ * Information is retrieved from the system on the basis of clock cycles since
+ * last time the computer was booted for the CPU time. The wall time is based
+ * on the system clock accessed by @p gettimeofday, with a typical accuracy of
+ * 0.01 ms on linux systems.
  *
  *
  * <h3>Usage</h3>
@@ -60,10 +60,10 @@ DEAL_II_NAMESPACE_OPEN
  *   timer.reset();
  * @endcode
  *
- * Alternatively, you can also restart the timer instead of resetting
- * it. The times between successive calls to start() / stop() will then be
- * accumulated. The usage of this class is also explained in the
- * step-28, step-29 and step-30 tutorial programs.
+ * Alternatively, you can also restart the timer instead of resetting it. The
+ * times between successive calls to start() / stop() will then be
+ * accumulated. The usage of this class is also explained in the step-28,
+ * step-29 and step-30 tutorial programs.
  *
  * @note Implementation of this class is system dependent. In case
  * multithreaded routines (matrix-vector products, error estimators, etc.) are
@@ -82,37 +82,27 @@ public:
 
 #ifdef DEAL_II_WITH_MPI
   /**
-   * Constructor that takes an MPI
-   * communicator as input. A timer
-   * constructed this way will sum up the
-   * CPU times over all processors in the
-   * MPI network when requested by the
-   * operator ().
+   * Constructor that takes an MPI communicator as input. A timer constructed
+   * this way will sum up the CPU times over all processors in the MPI network
+   * when requested by the operator ().
    *
    * Starts the timer at 0 sec.
    *
-   * If @p sync_wall_time is true, the wall
-   * time is synchronized between all CPUs
-   * using a MPI_Barrier() and a collective
-   * operation. Note that this only works
-   * if you stop() the timer before
-   * querying for the wall time. The time
-   * for the MPI operations are not
-   * included in the timing but may slow
+   * If @p sync_wall_time is true, the wall time is synchronized between all
+   * CPUs using a MPI_Barrier() and a collective operation. Note that this
+   * only works if you stop() the timer before querying for the wall time. The
+   * time for the MPI operations are not included in the timing but may slow
    * down your program.
    *
-   * This constructor is only available
-   * if the deal.II compiler is an MPI
+   * This constructor is only available if the deal.II compiler is an MPI
    * compiler.
    */
   Timer (MPI_Comm mpi_communicator,
          const bool sync_wall_time = false);
 
   /**
-   * Returns a reference to the data
-   * structure with global timing
-   * information. Filled after calling
-   * stop().
+   * Returns a reference to the data structure with global timing information.
+   * Filled after calling stop().
    */
   const Utilities::MPI::MinMaxAvg &get_data() const;
 
@@ -126,52 +116,42 @@ public:
 #endif
 
   /**
-   * Re-start the timer at the point where
-   * it was stopped. This way a cumulative
-   * measurement of time is possible.
+   * Re-start the timer at the point where it was stopped. This way a
+   * cumulative measurement of time is possible.
    */
   void start ();
 
   /**
-   * Sets the current time as next
-   * starting time and return the
-   * elapsed time in seconds.
+   * Sets the current time as next starting time and return the elapsed time
+   * in seconds.
    */
   double stop ();
 
   /**
-   * Stop the timer if necessary and reset
-   * the elapsed time to zero.
+   * Stop the timer if necessary and reset the elapsed time to zero.
    */
   void reset ();
 
   /**
-   * Resets the elapsed time to zero and
-   * starts the timer. This corresponds to
-   * calling @p reset() and @p start() on
-   * the Timer object.
+   * Resets the elapsed time to zero and starts the timer. This corresponds to
+   * calling @p reset() and @p start() on the Timer object.
    */
   void restart();
 
   /**
-   * Access to the current CPU time
-   * without disturbing time
-   * measurement. The elapsed time is
-   * returned in units of seconds.
+   * Access to the current CPU time without disturbing time measurement. The
+   * elapsed time is returned in units of seconds.
    */
   double operator() () const;
 
   /**
-   * Access to the current wall time
-   * without disturbing time
-   * measurement. The elapsed time is
-   * returned in units of seconds.
+   * Access to the current wall time without disturbing time measurement. The
+   * elapsed time is returned in units of seconds.
    */
   double wall_time () const;
 
   /**
-   * Returns the last lap time; the
-   * time taken between the last start()/stop()
+   * Returns the last lap time; the time taken between the last start()/stop()
    * call.
    */
   double get_lap_time () const;
@@ -179,92 +159,68 @@ public:
 private:
 
   /**
-   * Value of the user time when start()
-   * was called the last time or when the
-   * object was created and no stop() was
-   * issued in between.
+   * Value of the user time when start() was called the last time or when the
+   * object was created and no stop() was issued in between.
    */
   double              start_time;
 
 
   /**
-   * Similar to #start_time, but
-   * needed for children threads
-   * in multithread mode. Value of
-   * the user time when start()
-   * was called the last time or
-   * when the object was created
-   * and no stop() was issued in
-   * between.
+   * Similar to #start_time, but needed for children threads in multithread
+   * mode. Value of the user time when start() was called the last time or
+   * when the object was created and no stop() was issued in between.
    *
-   * For some reason (error in
-   * operating system?) the
-   * function call
-   * <tt>getrusage(RUSAGE_CHILDREN,.)</tt>
-   * gives always 0 (at least
-   * on Solaris7). Hence the
-   * Timer class still does not
-   * yet work for multithreading
-   * mode.
+   * For some reason (error in operating system?) the function call
+   * <tt>getrusage(RUSAGE_CHILDREN,.)</tt> gives always 0 (at least on
+   * Solaris7). Hence the Timer class still does not yet work for
+   * multithreading mode.
    */
   double              start_time_children;
 
   /**
-   * Value of the wall time when start()
-   * was called the last time or when the
-   * object was created and no stop() was
-   * issued in between.
+   * Value of the wall time when start() was called the last time or when the
+   * object was created and no stop() was issued in between.
    */
   double              start_wall_time;
 
   /**
-   * Accumulated time for all previous
-   * start()/stop() cycles. The time for
-   * the present cycle is not included.
+   * Accumulated time for all previous start()/stop() cycles. The time for the
+   * present cycle is not included.
    */
   double              cumulative_time;
 
   /**
-   * Accumulated wall time for all
-   * previous start()/stop() cycles. The
-   * wall time for the present cycle is
-   * not included.
+   * Accumulated wall time for all previous start()/stop() cycles. The wall
+   * time for the present cycle is not included.
    */
   double              cumulative_wall_time;
 
   /**
-   * Stores the last lap time; the time
-   * between the last start()/stop() cycle.
+   * Stores the last lap time; the time between the last start()/stop() cycle.
    */
   double              last_lap_time;
 
   /**
-   * Store whether the timer is presently
-   * running.
+   * Store whether the timer is presently running.
    */
   bool                running;
 
   /**
-   * Store whether the timer is presently
-   * running.
+   * Store whether the timer is presently running.
    */
   MPI_Comm            mpi_communicator;
 
 #ifdef DEAL_II_WITH_MPI
   /**
-   * Store whether the wall time is
-   * synchronized between machines.
+   * Store whether the wall time is synchronized between machines.
    */
   bool sync_wall_time;
 
   /**
-   * A structure for parallel wall time
-   * measurement that includes the minimum
-   * time recorded among all processes, the
-   * maximum time as well as the average
-   * time defined as the sum of all
-   * individual times divided by the number
-   * of MPI processes in the MPI_Comm.
+   * A structure for parallel wall time measurement that includes the minimum
+   * time recorded among all processes, the maximum time as well as the
+   * average time defined as the sum of all individual times divided by the
+   * number of MPI processes in the MPI_Comm.
    */
   Utilities::System::MinMaxAvg mpi_data;
 #endif
@@ -274,13 +230,13 @@ private:
 
 //TODO: The following class is not thread-safe
 /**
- * This class can be used to generate formatted output from time
- * measurements of different subsections in a program. It is possible to
- * create several sections that perform certain aspects of the program. A
- * section can be 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.
+ * This class can be used to generate formatted output from time measurements
+ * of different subsections in a program. It is possible to create several
+ * sections that perform certain aspects of the program. A section can be
+ * 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.
  *
  * <h3>Usage</h3>
  *
@@ -323,11 +279,11 @@ private:
  * | Setup dof system                |         1 |      3.97s |       4.5% |
  * +---------------------------------+-----------+------------+------------+
  * @endcode
- * The output will see that we entered the assembly and solve section
- * twice, and reports how much time we spent there. Moreover, the class
- * measures the total time spent from start to termination of the TimerOutput
- * object. In this case, we did a lot of other stuff, so that the time
- * proportions of the functions we measured are far away from 100 precent.
+ * The output will see that we entered the assembly and solve section twice,
+ * and reports how much time we spent there. Moreover, the class measures the
+ * total time spent from start to termination of the TimerOutput object. In
+ * this case, we did a lot of other stuff, so that the time proportions of the
+ * functions we measured are far away from 100 precent.
  *
  *
  * <h3>Using scoped timers</h3>
@@ -337,13 +293,13 @@ private:
  * awkward if the sections in between these calls contain <code>return</code>
  * statements or may throw exceptions. In that case, it is easy to forget that
  * one nevertheless needs to leave the section somehow, somewhere. An easier
- * approach is to use "scoped" sections. This is a variable that when you create
- * it enters a section, and leaves the section when you destroy it. If this is
- * a variable local to a particular scope (a code block between curly braces)
- * and you leave this scope due to a <code>return</code> statements or an
- * exception, then the variable is destroyed and the timed section is left
- * automatically. Consequently, we could have written the code piece above
- * as follows, with exactly the same result but now exception-safe:
+ * approach is to use "scoped" sections. This is a variable that when you
+ * create it enters a section, and leaves the section when you destroy it. If
+ * this is a variable local to a particular scope (a code block between curly
+ * braces) and you leave this scope due to a <code>return</code> statements or
+ * an exception, then the variable is destroyed and the timed section is left
+ * automatically. Consequently, we could have written the code piece above as
+ * follows, with exactly the same result but now exception-safe:
  * @code
  *   TimerOutput timer (std::cout, TimerOutput::summary,
  *                      TimerOutput::wall_times);
@@ -379,54 +335,52 @@ private:
  *
  * <h3>Usage in parallel programs using MPI</h3>
  *
- * In a parallel program built on MPI, using the class in a way such
- * as the one shown above would result in a situation where each
- * process times the corresponding sections and then outputs the resulting
- * timing information at the end. This is annoying since you'd get a lot
- * of output -- one set of timing information from each processor.
+ * In a parallel program built on MPI, using the class in a way such as the
+ * one shown above would result in a situation where each process times the
+ * corresponding sections and then outputs the resulting timing information at
+ * the end. This is annoying since you'd get a lot of output -- one set of
+ * timing information from each processor.
  *
  * This can be avoided by only letting one processor generate screen output,
  * typically by using an object of type ConditionalOStream instead of
  * <code>std::cout</code> to write to screen (see, for example, step-17,
  * step-18, step-32 and step-40, all of which use this method).
  *
- * This way, only a single processor outputs timing information, typically
- * the first process in the MPI universe. However,
- * if you take the above code snippet as an example, imagine what would happen
- * if <code>setup_dofs()</code> is fast on processor zero and slow on at
- * least one of the other processors; and if the first thing
+ * This way, only a single processor outputs timing information, typically the
+ * first process in the MPI universe. However, if you take the above code
+ * snippet as an example, imagine what would happen if
+ * <code>setup_dofs()</code> is fast on processor zero and slow on at least
+ * one of the other processors; and if the first thing
  * <code>assemble_system_1()</code> does is something that requires all
  * processors to communicate. In this case, on processor zero, the timing
- * section with name <code>"Setup dof system"</code> will yield a short
- * run time on processor zero, whereas the section <code> "Assemble"</code>
- * will take a long time: not because <code>assemble_system_1()</code>
- * takes a particularly long time, but because on the processor on which
- * we time (or, rather, the one on which we generate output) happens to
- * have to wait for a long time till the other processor is finally done
- * with <code>setup_dofs()</code> and starts to participate in
+ * section with name <code>"Setup dof system"</code> will yield a short run
+ * time on processor zero, whereas the section <code> "Assemble"</code> will
+ * take a long time: not because <code>assemble_system_1()</code> takes a
+ * particularly long time, but because on the processor on which we time (or,
+ * rather, the one on which we generate output) happens to have to wait for a
+ * long time till the other processor is finally done with
+ * <code>setup_dofs()</code> and starts to participate in
  * <code>assemble_system_1()</code>. In other words, the timing that is
- * reported is unreliable because it reflects run times from other
- * processors. Furthermore, the run time of this section on processor zero
- * has nothing to do with the run time of the section on other processors
- * but instead with the run time of <i>the previous section</i> on another
- * processor.
+ * reported is unreliable because it reflects run times from other processors.
+ * Furthermore, the run time of this section on processor zero has nothing to
+ * do with the run time of the section on other processors but instead with
+ * the run time of <i>the previous section</i> on another processor.
  *
  * The usual way to avoid this is to introduce a barrier into the parallel
- * code just before we start and stop timing sections. This ensures that
- * all processes are at the same place and the timing information then
- * reflects the maximal run time across all processors. To achieve this,
- * you need to initialize the TimerOutput object with an MPI communicator
- * object, for example as in the following code:
+ * code just before we start and stop timing sections. This ensures that all
+ * processes are at the same place and the timing information then reflects
+ * the maximal run time across all processors. To achieve this, you need to
+ * initialize the TimerOutput object with an MPI communicator object, for
+ * example as in the following code:
  * @code
  *   TimerOutput timer (MPI_COMM_WORLD,
  *                      pcout,
  *                      TimerOutput::summary,
  *                      TimerOutput::wall_times);
  * @endcode
- * Here, <code>pcout</code> is an object of type ConditionalOStream that
- * makes sure that we only generate output on a single processor.
- * See the step-32 and step-40 tutorial programs for this kind of usage
- * of this class.
+ * Here, <code>pcout</code> is an object of type ConditionalOStream that makes
+ * sure that we only generate output on a single processor. See the step-32
+ * and step-40 tutorial programs for this kind of usage of this class.
  *
  * @ingroup utilities
  * @author M. Kronbichler, 2009.
@@ -435,9 +389,9 @@ class TimerOutput
 {
 public:
   /**
-   * Helper class to enter/exit sections in TimerOutput be constructing
-   * a simple scope-based object. The purpose of this class is explained
-   * in the documentation of TimerOutput.
+   * Helper class to enter/exit sections in TimerOutput be constructing a
+   * simple scope-based object. The purpose of this class is explained in the
+   * documentation of TimerOutput.
    */
   class Scope
   {
@@ -496,11 +450,12 @@ public:
   /**
    * Constructor.
    *
-   * @param stream The stream (of type std::ostream) to which output is written.
-   * @param output_frequency A variable indicating when output is to be written
-   *   to the given stream.
+   * @param stream The stream (of type std::ostream) to which output is
+   * written.
+   * @param output_frequency A variable indicating when output is to be
+   * written to the given stream.
    * @param output_type A variable indicating what kind of timing the output
-   *   should represent (CPU or wall time).
+   * should represent (CPU or wall time).
    */
   TimerOutput (std::ostream              &stream,
                const enum OutputFrequency output_frequency,
@@ -509,11 +464,12 @@ public:
   /**
    * Constructor.
    *
-   * @param stream The stream (of type ConditionalOstream) to which output is written.
-   * @param output_frequency A variable indicating when output is to be written
-   *   to the given stream.
+   * @param stream The stream (of type ConditionalOstream) to which output is
+   * written.
+   * @param output_frequency A variable indicating when output is to be
+   * written to the given stream.
    * @param output_type A variable indicating what kind of timing the output
-   *   should represent (CPU or wall time).
+   * should represent (CPU or wall time).
    */
   TimerOutput (ConditionalOStream        &stream,
                const enum OutputFrequency output_frequency,
@@ -521,26 +477,27 @@ public:
 
 #ifdef DEAL_II_WITH_MPI
   /**
-   * Constructor that takes an MPI communicator as input. A timer
-   * constructed this way will sum up the CPU times over all
-   * processors in the MPI network for calculating the CPU time, or
-   * take the maximum over all processors, depending on the value of
-   * @p output_type . See the documentation of this class for the
-   * rationale for this constructor and an example.
+   * Constructor that takes an MPI communicator as input. A timer constructed
+   * this way will sum up the CPU times over all processors in the MPI network
+   * for calculating the CPU time, or take the maximum over all processors,
+   * depending on the value of @p output_type . See the documentation of this
+   * class for the rationale for this constructor and an example.
    *
    * @param mpi_comm An MPI communicator across which we should accumulate or
-   *   otherwise synchronize the timing information we produce on every MPI process.
-   * @param stream The stream (of type std::ostream) to which output is written.
-   * @param output_frequency A variable indicating when output is to be written
-   *   to the given stream.
+   * otherwise synchronize the timing information we produce on every MPI
+   * process.
+   * @param stream The stream (of type std::ostream) to which output is
+   * written.
+   * @param output_frequency A variable indicating when output is to be
+   * written to the given stream.
    * @param output_type A variable indicating what kind of timing the output
-   *   should represent (CPU or wall time). In this parallel context, when this
-   *   argument selects CPU time, then times are accumulated over all processes
-   *   participating in the MPI communicator. If this argument selects wall
-   *   time, then reported times are the maximum over all processors' run times
-   *   for this section. (The latter is computed by placing an
-   *   <code>MPI_Barrier</code> call before starting and stopping the timer
-   *   for each section.
+   * should represent (CPU or wall time). In this parallel context, when this
+   * argument selects CPU time, then times are accumulated over all processes
+   * participating in the MPI communicator. If this argument selects wall
+   * time, then reported times are the maximum over all processors' run times
+   * for this section. (The latter is computed by placing an
+   * <code>MPI_Barrier</code> call before starting and stopping the timer for
+   * each section.
    */
   TimerOutput (MPI_Comm                   mpi_comm,
                std::ostream              &stream,
@@ -548,26 +505,27 @@ public:
                const enum OutputType      output_type);
 
   /**
-   * Constructor that takes an MPI communicator as input. A timer
-   * constructed this way will sum up the CPU times over all
-   * processors in the MPI network for calculating the CPU time, or
-   * take the maximum over all processors, depending on the value of
-   * @p output_type . See the documentation of this class for the
-   * rationale for this constructor and an example.
+   * Constructor that takes an MPI communicator as input. A timer constructed
+   * this way will sum up the CPU times over all processors in the MPI network
+   * for calculating the CPU time, or take the maximum over all processors,
+   * depending on the value of @p output_type . See the documentation of this
+   * class for the rationale for this constructor and an example.
    *
    * @param mpi_comm An MPI communicator across which we should accumulate or
-   *   otherwise synchronize the timing information we produce on every MPI process.
-   * @param stream The stream (of type ConditionalOstream) to which output is written.
-   * @param output_frequency A variable indicating when output is to be written
-   *   to the given stream.
+   * otherwise synchronize the timing information we produce on every MPI
+   * process.
+   * @param stream The stream (of type ConditionalOstream) to which output is
+   * written.
+   * @param output_frequency A variable indicating when output is to be
+   * written to the given stream.
    * @param output_type A variable indicating what kind of timing the output
-   *   should represent (CPU or wall time). In this parallel context, when this
-   *   argument selects CPU time, then times are accumulated over all processes
-   *   participating in the MPI communicator. If this argument selects wall
-   *   time, then reported times are the maximum over all processors' run times
-   *   for this section. (The latter is computed by placing an
-   *   <code>MPI_Barrier</code> call before starting and stopping the timer
-   *   for each section.)
+   * should represent (CPU or wall time). In this parallel context, when this
+   * argument selects CPU time, then times are accumulated over all processes
+   * participating in the MPI communicator. If this argument selects wall
+   * time, then reported times are the maximum over all processors' run times
+   * for this section. (The latter is computed by placing an
+   * <code>MPI_Barrier</code> call before starting and stopping the timer for
+   * each section.)
    */
   TimerOutput (MPI_Comm                   mpi_comm,
                ConditionalOStream        &stream,
@@ -580,17 +538,14 @@ public:
 #endif
 
   /**
-   * Destructor. Calls print_summary() in
-   * case the option for writing the
+   * Destructor. Calls print_summary() in case the option for writing the
    * summary output is set.
    */
   ~TimerOutput();
 
   /**
-   * Open a section by given a string name
-   * of it. In case the name already
-   * exists, that section is entered once
-   * again and times are accumulated.
+   * Open a section by given a string name of it. In case the name already
+   * exists, that section is entered once again and times are accumulated.
    */
   void enter_subsection (const std::string &section_name);
 
@@ -602,9 +557,8 @@ public:
   //TODO: make some of these functions DEPRECATED (I would keep enter/exit_section)
 
   /**
-   * Leave a section. If no name is given,
-   * the last section that was entered is
-   * left.
+   * Leave a section. If no name is given, the last section that was entered
+   * is left.
    */
   void leave_subsection (const std::string &section_name = std::string());
 
@@ -614,33 +568,24 @@ public:
   void exit_section (const std::string &section_name = std::string());
 
   /**
-   * Print a formatted table that
-   * summarizes the time consumed in the
-   * various sections.
+   * Print a formatted table that summarizes the time consumed in the various
+   * sections.
    */
   void print_summary () const;
 
   /**
-   * By calling this function, all output
-   * can be disabled. This function
-   * together with enable_output() can be
-   * useful if one wants to control the
-   * output in a flexible way without
-   * putting a lot of <tt>if</tt> clauses
-   * in the program.
+   * By calling this function, all output can be disabled. This function
+   * together with enable_output() can be useful if one wants to control the
+   * output in a flexible way without putting a lot of <tt>if</tt> clauses in
+   * the program.
    */
   void disable_output ();
 
   /**
-   * This function re-enables output of
-   * this class if it was previously
-   * disabled with disable_output(). This
-   * function together with
-   * disable_output() can be useful if
-   * one wants to control the output in a
-   * flexible way without putting a lot
-   * of <tt>if</tt> clauses in the
-   * program.
+   * This function re-enables output of this class if it was previously
+   * disabled with disable_output(). This function together with
+   * disable_output() can be useful if one wants to control the output in a
+   * flexible way without putting a lot of <tt>if</tt> clauses in the program.
    */
   void enable_output ();
 
@@ -656,24 +601,20 @@ private:
   OutputFrequency output_frequency;
 
   /**
-   * Whether to show CPU times, wall
-   * times, or both CPU and wall times.
+   * Whether to show CPU times, wall times, or both CPU and wall times.
    */
   OutputType output_type;
 
 
   /**
-   * A timer object for the overall
-   * run time. If we are using MPI,
-   * this timer also accumulates
-   * over all MPI processes.
+   * A timer object for the overall run time. If we are using MPI, this timer
+   * also accumulates over all MPI processes.
    */
   Timer              timer_all;
 
   /**
-   * A structure that groups all
-   * information that we collect
-   * about each of the sections.
+   * A structure that groups all information that we collect about each of the
+   * sections.
    */
   struct Section
   {
@@ -684,33 +625,25 @@ private:
   };
 
   /**
-   * A list of all the sections and
-   * their information.
+   * A list of all the sections and their information.
    */
   std::map<std::string, Section> sections;
 
   /**
-   * The stream object to which we
-   * are to output.
+   * The stream object to which we are to output.
    */
   ConditionalOStream out_stream;
 
   /**
-   * A boolean variable that sets whether
-   * output of this class is currently on
+   * A boolean variable that sets whether output of this class is currently on
    * or off.
    */
   bool output_is_enabled;
 
   /**
-   * A list of the sections that
-   * have been entered and not
-   * exited. The list is kept in
-   * the order in which sections
-   * have been entered, but
-   * elements may be removed in the
-   * middle if an argument is given
-   * to the exit_section()
+   * A list of the sections that have been entered and not exited. The list is
+   * kept in the order in which sections have been entered, but elements may
+   * be removed in the middle if an argument is given to the exit_section()
    * function.
    */
   std::list<std::string> active_sections;
@@ -721,9 +654,8 @@ private:
   MPI_Comm            mpi_communicator;
 
   /**
-   * A lock that makes sure that this
-   * class gives reasonable results even
-   * when used with several threads.
+   * A lock that makes sure that this class gives reasonable results even when
+   * used with several threads.
    */
   Threads::Mutex mutex;
 };
index f6f75fabe5aefe4ee2375ee8575488f39d930485..9aefba4f9e5fa0dab87285b8610ad85c3f2cba52 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * A namespace in which we declare typedefs for types used in deal.II,
- * as well as special values for these types.
+ * A namespace in which we declare typedefs for types used in deal.II, as well
+ * as special values for these types.
  */
 namespace types
 {
   /**
-   * The type used to denote
-   * subdomain_ids of cells.
+   * The type used to denote subdomain_ids of cells.
    *
-   * See the @ref GlossSubdomainId
-   * "glossary" for more information.
-  *
-  * There is a special value,
-  * numbers::invalid_subdomain_id
-  * that is used to indicate an
-  * invalid value of this type.
+   * See the @ref GlossSubdomainId "glossary" for more information.
+   *
+   * There is a special value, numbers::invalid_subdomain_id that is used to
+   * indicate an invalid value of this type.
    */
   typedef unsigned int subdomain_id;
 
@@ -47,7 +43,7 @@ namespace types
   typedef subdomain_id subdomain_id_t DEAL_II_DEPRECATED;
 
   /**
-  * @deprecated Use numbers::invalid_subdomain_id
+   * @deprecated Use numbers::invalid_subdomain_id
    */
   const unsigned int invalid_subdomain_id DEAL_II_DEPRECATED = static_cast<subdomain_id>(-1);
 
@@ -58,80 +54,71 @@ namespace types
 
 #ifdef DEAL_II_WITH_64BIT_INDICES
   /**
-   * The type used for global indices of
-   * degrees of freedom. While in sequential
-   * computations the 4 billion indices of
-   * 32-bit unsigned integers is plenty,
-   * parallel computations using the
-   * parallel::distributed::Triangulation
-   * class can overflow this number and we
-   * need a bigger index space.
+   * The type used for global indices of degrees of freedom. While in
+   * sequential computations the 4 billion indices of 32-bit unsigned integers
+   * is plenty, parallel computations using the
+   * parallel::distributed::Triangulation class can overflow this number and
+   * we need a bigger index space.
    *
-   * The data type always indicates an
-   * unsigned integer type.
+   * The data type always indicates an unsigned integer type.
    *
-   * See the @ref GlobalDoFIndex page for guidance on when this
-   * type should or should not be used.
+   * See the @ref GlobalDoFIndex page for guidance on when this type should or
+   * should not be used.
    */
   // TODO: we should check that unsigned long long int
   // has the same size as uint64_t
   typedef unsigned long long int global_dof_index;
 
   /**
-   * An identifier that denotes the MPI type
-   * associated with types::global_dof_index.
+   * An identifier that denotes the MPI type associated with
+   * types::global_dof_index.
    */
 #  define DEAL_II_DOF_INDEX_MPI_TYPE MPI_UNSIGNED_LONG_LONG
 #else
   /**
-   * The type used for global indices of
-   * degrees of freedom. While in sequential
-   * computations the 4 billion indices of
-   * 32-bit unsigned integers is plenty,
-   * parallel computations using the
-   * parallel::distributed::Triangulation
-   * class can overflow this number and we
-   * need a bigger index space.
+   * The type used for global indices of degrees of freedom. While in
+   * sequential computations the 4 billion indices of 32-bit unsigned integers
+   * is plenty, parallel computations using the
+   * parallel::distributed::Triangulation class can overflow this number and
+   * we need a bigger index space.
    *
-   * The data type always indicates an
-   * unsigned integer type.
+   * The data type always indicates an unsigned integer type.
    */
   typedef unsigned int global_dof_index;
 
   /**
-   * An identifier that denotes the MPI type
-   * associated with types::global_dof_index.
+   * An identifier that denotes the MPI type associated with
+   * types::global_dof_index.
    */
 #  define DEAL_II_DOF_INDEX_MPI_TYPE MPI_UNSIGNED
 #endif
 
 
   /**
-   *  @deprecated Use numbers::invalid_dof_index
+   * @deprecated Use numbers::invalid_dof_index
    */
   const global_dof_index invalid_dof_index DEAL_II_DEPRECATED = static_cast<global_dof_index>(-1);
 
   /**
-   * The type used to denote boundary indicators associated with every
-   * piece of the boundary and, in the case of meshes that describe
-   * manifolds in higher dimensions, associated with every cell.
+   * The type used to denote boundary indicators associated with every piece
+   * of the boundary and, in the case of meshes that describe manifolds in
+   * higher dimensions, associated with every cell.
    *
-   * There is a special value, numbers::internal_face_boundary_id
-   * that is used to indicate an invalid value of this type and that
-   * is used as the boundary indicator for faces that are in the interior
-   * of the domain and therefore not part of any addressable boundary
-   * component.
+   * There is a special value, numbers::internal_face_boundary_id that is used
+   * to indicate an invalid value of this type and that is used as the
+   * boundary indicator for faces that are in the interior of the domain and
+   * therefore not part of any addressable boundary component.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
   typedef unsigned char boundary_id;
 
   /**
-   * The type used to denote manifold indicators associated with every
-   * object of the mesh.
+   * The type used to denote manifold indicators associated with every object
+   * of the mesh.
    *
-   * There is a special value, numbers::flat_manifold_id
-   * that is used to indicate the standard cartesian manifold.
+   * There is a special value, numbers::flat_manifold_id that is used to
+   * indicate the standard cartesian manifold.
    *
    * @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
    */
@@ -144,11 +131,10 @@ namespace types
   typedef boundary_id boundary_id_t DEAL_II_DEPRECATED;
 
   /**
-   * The type used to denote material indicators associated with every
-   * cell.
-  *
-  * There is a special value, numbers::invalid_material_id
-  * that is used to indicate an invalid value of this type.
+   * The type used to denote material indicators associated with every cell.
+   *
+   * There is a special value, numbers::invalid_material_id that is used to
+   * indicate an invalid value of this type.
    */
   typedef unsigned char material_id;
 
@@ -184,91 +170,62 @@ namespace TrilinosWrappers
 namespace numbers
 {
   /**
-   * Representation of the
-   * largest number that
-   * can be put into an
-   * unsigned integer. This
-   * value is widely used
-   * throughout the library
-   * as a marker for an
-   * invalid unsigned
-   * integer value, such as
-   * an invalid array
-   * index, an invalid
-   * array size, and the
-   * like.
+   * Representation of the largest number that can be put into an unsigned
+   * integer. This value is widely used throughout the library as a marker for
+   * an invalid unsigned integer value, such as an invalid array index, an
+   * invalid array size, and the like.
    */
   static const unsigned int
   invalid_unsigned_int = static_cast<unsigned int> (-1);
 
   /**
-   * Representation of the
-   * largest number that
-   * can be put into a
-   * size_type. This value
-   * is used throughout
-   * the library as a
-   * marker for an
-   * invalid size_type
-   * value, such as
-   * an invalid array
-   * index, an invalid
-   * array size, and the
-   * like. Invalid_size_type
-   * is equivalent to
-   * invalid_dof_index.
+   * Representation of the largest number that can be put into a size_type.
+   * This value is used throughout the library as a marker for an invalid
+   * size_type value, such as an invalid array index, an invalid array size,
+   * and the like. Invalid_size_type is equivalent to invalid_dof_index.
    */
   const types::global_dof_index
   invalid_size_type = static_cast<types::global_dof_index> (-1);
 
   /**
-   * An invalid value for indices of degrees
-   * of freedom.
+   * An invalid value for indices of degrees of freedom.
    */
   const types::global_dof_index invalid_dof_index = static_cast<types::global_dof_index>(-1);
 
   /**
-   * Invalid material_id which we
-   * need in several places as a
-   * default value.  We assume that
-   * all material_ids lie in the
-   * range [0, invalid_material_id).
+   * Invalid material_id which we need in several places as a default value.
+   * We assume that all material_ids lie in the range [0,
+   * invalid_material_id).
    */
   const types::material_id invalid_material_id = static_cast<types::material_id>(-1);
 
   /**
-   * Invalid boundary_id which we
-   * need in several places as a
-   * default value.  We assume that
-   * all valid boundary_ids lie in the
-   * range [0, invalid_boundary_id).
+   * Invalid boundary_id which we need in several places as a default value.
+   * We assume that all valid boundary_ids lie in the range [0,
+   * invalid_boundary_id).
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
   const types::boundary_id invalid_boundary_id = static_cast<types::boundary_id>(-1);
 
   /**
-   * A boundary indicator number that we reserve for
-   * internal faces.  We assume that
-   * all valid boundary_ids lie in the
-   * range [0,
+   * A boundary indicator number that we reserve for internal faces.  We
+   * assume that all valid boundary_ids lie in the range [0,
    * internal_face_boundary_id).
    *
    * This is an indicator that is used internally (by the library) to
-   * differentiate between faces that lie at the boundary of the domain
-   * and faces that lie in the interior of the domain. You should never try
-   * to assign this boundary indicator to anything in user code.
+   * differentiate between faces that lie at the boundary of the domain and
+   * faces that lie in the interior of the domain. You should never try to
+   * assign this boundary indicator to anything in user code.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
   const types::boundary_id internal_face_boundary_id = static_cast<types::boundary_id>(-1);
 
   /**
-   * Invalid manifold_id which we
-   * need in several places as a
-   * default value.  We assume that
-   * all valid manifold_ids lie in the
-   * range [0, invalid_maifold_id).
+   * Invalid manifold_id which we need in several places as a default value.
+   * We assume that all valid manifold_ids lie in the range [0,
+   * invalid_maifold_id).
    *
    * @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
    */
@@ -282,35 +239,23 @@ namespace numbers
   const types::manifold_id flat_manifold_id = static_cast<types::manifold_id>(-1);
 
   /**
-   * A special id for an invalid
-   * subdomain id. This value may not
-   * be used as a valid id but is
-   * used, for example, for default
-   * arguments to indicate a
-   * subdomain id that is not to be
-   * used.
+   * A special id for an invalid subdomain id. This value may not be used as a
+   * valid id but is used, for example, for default arguments to indicate a
+   * subdomain id that is not to be used.
    *
-   * See the @ref GlossSubdomainId
-   * "glossary" for more information.
+   * See the @ref GlossSubdomainId "glossary" for more information.
    */
   const types::subdomain_id invalid_subdomain_id = static_cast<types::subdomain_id>(-1);
 
   /**
-   * The subdomain id assigned to a
-   * cell whose true subdomain id we
-   * don't know, for example because
-   * it resides on a different
-   * processor on a mesh that is kept
-   * distributed on many
-   * processors. Such cells are
-   * called "artificial".
+   * The subdomain id assigned to a cell whose true subdomain id we don't
+   * know, for example because it resides on a different processor on a mesh
+   * that is kept distributed on many processors. Such cells are called
+   * "artificial".
    *
-   * See the glossary entries on @ref
-   * GlossSubdomainId "subdomain ids"
-   * and @ref GlossArtificialCell
-   * "artificial cells" as well as
-   * the @ref distributed module for
-   * more information.
+   * See the glossary entries on @ref GlossSubdomainId "subdomain ids" and
+   * @ref GlossArtificialCell "artificial cells" as well as the @ref
+   * distributed module for more information.
    */
   const types::subdomain_id artificial_subdomain_id = static_cast<types::subdomain_id>(-2);
 }
index 65ffb80c3821d28e77a1ebfb4d9ef553d0b050ca..3961616c1c2d87cdbad355b154de3918b36f9253 100644 (file)
@@ -50,61 +50,53 @@ namespace Utilities
 {
 
   /**
-   * Convert a number @p i to a string, with
-   * as many digits as given to fill with
-   * leading zeros.
+   * Convert a number @p i to a string, with as many digits as given to fill
+   * with leading zeros.
    *
-   * If the second parameter is left at its
-   * default value, the number is not padded
-   * with leading zeros. The result is then
-   * the same as of the standard C function
-   * <code>itoa()</code> had been called.
+   * If the second parameter is left at its default value, the number is not
+   * padded with leading zeros. The result is then the same as of the standard
+   * C function <code>itoa()</code> had been called.
    */
   std::string
   int_to_string (const unsigned int i,
                  const unsigned int digits = numbers::invalid_unsigned_int);
 
   /**
-   * Determine how many digits are needed to
-   * represent numbers at most as large as
-   * the given number.
+   * Determine how many digits are needed to represent numbers at most as
+   * large as the given number.
    */
   unsigned int
   needed_digits (const unsigned int max_number);
 
   /**
-   * Given a string, convert it to an
-   * integer. Throw an assertion if that is
+   * Given a string, convert it to an integer. Throw an assertion if that is
    * not possible.
    */
   int
   string_to_int (const std::string &s);
 
   /**
-   * Return a string describing the dimensions of the object. Often,
-   * functions in the deal.II library as well as in user codes need to
-   * define a string containing the template dimensions of some
-   * objects defined using two template parameters: dim (the
-   * topological dimension of the object) and spacedim (the dimension
-   * of the embedding Euclidean space).  Since in all deal.II classes,
-   * by default spacedim is equal to dimension, the above string is
-   * usually contracted to <dim>, instead of <dim,spacedim>. This
-   * function returns a string containing "dim" if dim is equal to
-   * spacedim, otherwhise it returns "dim,spacedim".
+   * Return a string describing the dimensions of the object. Often, functions
+   * in the deal.II library as well as in user codes need to define a string
+   * containing the template dimensions of some objects defined using two
+   * template parameters: dim (the topological dimension of the object) and
+   * spacedim (the dimension of the embedding Euclidean space).  Since in all
+   * deal.II classes, by default spacedim is equal to dimension, the above
+   * string is usually contracted to <dim>, instead of <dim,spacedim>. This
+   * function returns a string containing "dim" if dim is equal to spacedim,
+   * otherwhise it returns "dim,spacedim".
    */
   std::string dim_string(const int dim, const int spacedim);
 
   /**
-   * Given a list of strings, convert it to a
-   * list of integers. Throw an assertion if
-   * that is not possible.
+   * Given a list of strings, convert it to a list of integers. Throw an
+   * assertion if that is not possible.
    */
   std::vector<int>
   string_to_int (const std::vector<std::string> &s);
 
   /**
-   * Given a string, convert it to an
-   * double. Throw an assertion if that is
+   * Given a string, convert it to an double. Throw an assertion if that is
    * not possible.
    */
   double
@@ -112,40 +104,32 @@ namespace Utilities
 
 
   /**
-   * Given a list of strings, convert it to a
-   * list of doubles. Throw an assertion if
-   * that is not possible.
+   * Given a list of strings, convert it to a list of doubles. Throw an
+   * assertion if that is not possible.
    */
   std::vector<double>
   string_to_double (const std::vector<std::string> &s);
 
   /**
-   * Given a string that contains text
-   * separated by a @p delimiter, split it into
-   * its components; for each component,
-   * remove leading and trailing spaces.
+   * Given a string that contains text separated by a @p delimiter, split it
+   * into its components; for each component, remove leading and trailing
+   * spaces.
    *
-   * The default value of the delimiter is a
-   * comma, so that the function splits comma
-   * separated lists of strings.
+   * The default value of the delimiter is a comma, so that the function
+   * splits comma separated lists of strings.
    */
   std::vector<std::string>
   split_string_list (const std::string &s,
                      const char         delimiter = ',');
 
   /**
-   * Take a text, usually a documentation or
-   * something, and try to break it into
-   * individual lines of text at most @p
-   * width characters wide, by breaking at
-   * positions marked by @p delimiter in the
-   * text. If this is not possible, return
-   * the shortest lines that are longer than
-   * @p width.  The default value of the
-   * delimiter is a space character. If
-   * original_text contains newline
-   * characters (\n), the string is split at
-   * these locations, too.
+   * Take a text, usually a documentation or something, and try to break it
+   * into individual lines of text at most @p width characters wide, by
+   * breaking at positions marked by @p delimiter in the text. If this is not
+   * possible, return the shortest lines that are longer than @p width.  The
+   * default value of the delimiter is a space character. If original_text
+   * contains newline characters (\n), the string is split at these locations,
+   * too.
    */
   std::vector<std::string>
   break_text_into_lines (const std::string &original_text,
@@ -153,25 +137,19 @@ namespace Utilities
                          const char delimiter = ' ');
 
   /**
-   * Return true if the given pattern
-   * string appears in the first
-   * position of the string.
+   * Return true if the given pattern string appears in the first position of
+   * the string.
    */
   bool
   match_at_string_start (const std::string &name,
                          const std::string &pattern);
 
   /**
-   * Read a (signed) integer starting
-   * at the position in @p name
-   * indicated by the second
-   * argument, and retun this integer
-   * as a pair together with how many
-   * characters it takes up in the
-   * string.
+   * Read a (signed) integer starting at the position in @p name indicated by
+   * the second argument, and retun this integer as a pair together with how
+   * many characters it takes up in the string.
    *
-   * If no integer can be read at the
-   * indicated position, return
+   * If no integer can be read at the indicated position, return
    * (-1,numbers::invalid_unsigned_int)
    */
   std::pair<int, unsigned int>
@@ -179,32 +157,27 @@ namespace Utilities
                            const unsigned int position);
 
   /**
-   * Generate a random number from a
-   * normalized Gaussian probability
-   * distribution centered around @p a and
-   * with standard deviation @p sigma.
+   * Generate a random number from a normalized Gaussian probability
+   * distribution centered around @p a and with standard deviation @p sigma.
    *
-   * This function is reentrant, i.e., it can safely be
-   * called from multiple threads at the same time. However, if
-   * so done, then there is no guarantee that each thread will
-   * get the same sequence of numbers every time. Rather, the
-   * produced sequence of random numbers will be apportioned to
-   * the different threads in non-deterministic ways. If this
-   * is a problem, for example for exactly reproducibility, then
-   * you need to use separate random number facilities for separate
-   * threads, rather than this global function. For example, the C++11
-   * standard offers such objects, as does BOOST.
+   * This function is reentrant, i.e., it can safely be called from multiple
+   * threads at the same time. However, if so done, then there is no guarantee
+   * that each thread will get the same sequence of numbers every time.
+   * Rather, the produced sequence of random numbers will be apportioned to
+   * the different threads in non-deterministic ways. If this is a problem,
+   * for example for exactly reproducibility, then you need to use separate
+   * random number facilities for separate threads, rather than this global
+   * function. For example, the C++11 standard offers such objects, as does
+   * BOOST.
    *
-   * @note Like the system function rand(), this function produces
-   * the same sequence of random numbers every time a program is
-   * started. This is an important property for debugging codes,
-   * but it makes it impossible to really verify statistics
-   * properties of a code. For rand(), you can call srand() to
-   * "seed" the random number generator to get different sequences
-   * of random numbers every time a program is called. However, this
-   * function does not allow seeding the random number generator.
-   * If you need this, as above, use one of the C++ or BOOST
-   * facilities.
+   * @note Like the system function rand(), this function produces the same
+   * sequence of random numbers every time a program is started. This is an
+   * important property for debugging codes, but it makes it impossible to
+   * really verify statistics properties of a code. For rand(), you can call
+   * srand() to "seed" the random number generator to get different sequences
+   * of random numbers every time a program is called. However, this function
+   * does not allow seeding the random number generator. If you need this, as
+   * above, use one of the C++ or BOOST facilities.
    */
   double
   generate_normal_random_number (const double a,
@@ -212,34 +185,25 @@ namespace Utilities
 
 
   /**
-   * Calculate a fixed power, provided as a
-   * template argument, of a number.
+   * Calculate a fixed power, provided as a template argument, of a number.
    *
-   * This function provides an efficient way
-   * to calculate things like
-   * <code>t^N</code> where <code>N</code> is
-   * a known number at compile time.
+   * This function provides an efficient way to calculate things like
+   * <code>t^N</code> where <code>N</code> is a known number at compile time.
    *
-   * Use this function as in
-   * <code>fixed_power@<dim@> (n)</code>.
+   * Use this function as in <code>fixed_power@<dim@> (n)</code>.
    */
   template <int N, typename T>
   T
   fixed_power (const T t);
 
   /**
-   * Calculate a fixed power of an integer
-   * number by a template expression where
-   * both the number <code>a</code> and the
-   * power <code>N</code> are compile-time
-   * constants. This computes the result of
-   * the power operation at compile time,
-   * enabling its use e.g. in other
-   * templates.
+   * Calculate a fixed power of an integer number by a template expression
+   * where both the number <code>a</code> and the power <code>N</code> are
+   * compile-time constants. This computes the result of the power operation
+   * at compile time, enabling its use e.g. in other templates.
    *
-   * Use this class as in
-   * <code>fixed_int_power@<5,2@>::%value</code>
-   * to compute 5<sup>2</sup>.
+   * Use this class as in <code>fixed_int_power@<5,2@>::%value</code> to
+   * compute 5<sup>2</sup>.
    */
   template <int a, int N>
   struct fixed_int_power
@@ -248,9 +212,8 @@ namespace Utilities
   };
 
   /**
-   * Base case for the power operation with
-   * <code>N=0</code>, which gives the result
-   * 1.
+   * Base case for the power operation with <code>N=0</code>, which gives the
+   * result 1.
    */
   template <int a>
   struct fixed_int_power<a,0>
@@ -259,46 +222,25 @@ namespace Utilities
   };
 
   /**
-   * Optimized replacement for
-   * <tt>std::lower_bound</tt> for
-   * searching within the range of
-   * column indices. Slashes
-   * execution time by
-   * approximately one half for the
-   * present application, partly
-   * because because the
-   * binary search is replaced by a
-   * linear search for small loop
-   * lengths.
+   * Optimized replacement for <tt>std::lower_bound</tt> for searching within
+   * the range of column indices. Slashes execution time by approximately one
+   * half for the present application, partly because because the binary
+   * search is replaced by a linear search for small loop lengths.
    *
-   * Another reason for this function is
-   * rather obscure:
-   * when using the GCC libstdc++
-   * function std::lower_bound,
-   * complexity is O(log(N)) as
-   * required. However, when using the
-   * debug version of the GCC libstdc++
-   * as we do when running the testsuite,
-   * then std::lower_bound tests whether
-   * the sequence is in fact partitioned
-   * with respect to the pivot 'value'
-   * (i.e. in essence that the sequence
-   * is sorted as required for binary
-   * search to work). However, verifying
-   * this means that the complexity of
-   * std::lower_bound jumps to O(N); we
-   * call this function O(N) times below,
-   * making the overall complexity
-   * O(N**2). The consequence is that a
-   * few tests with big meshes completely
-   * run off the wall time limit for
-   * tests and fail with the libstdc++
-   * debug mode
+   * Another reason for this function is rather obscure: when using the GCC
+   * libstdc++ function std::lower_bound, complexity is O(log(N)) as required.
+   * However, when using the debug version of the GCC libstdc++ as we do when
+   * running the testsuite, then std::lower_bound tests whether the sequence
+   * is in fact partitioned with respect to the pivot 'value' (i.e. in essence
+   * that the sequence is sorted as required for binary search to work).
+   * However, verifying this means that the complexity of std::lower_bound
+   * jumps to O(N); we call this function O(N) times below, making the overall
+   * complexity O(N**2). The consequence is that a few tests with big meshes
+   * completely run off the wall time limit for tests and fail with the
+   * libstdc++ debug mode
    *
-   * This function simply makes the
-   * assumption that the sequence is
-   * sorted, and we simply don't do the
-   * additional check.
+   * This function simply makes the assumption that the sequence is sorted,
+   * and we simply don't do the additional check.
    */
   template<typename Iterator, typename T>
   Iterator
@@ -308,10 +250,9 @@ namespace Utilities
 
 
   /**
-   * The same function as above, but taking
-   * an argument that is used to compare
-   * individual elements of the sequence of
-   * objects pointed to by the iterators.
+   * The same function as above, but taking an argument that is used to
+   * compare individual elements of the sequence of objects pointed to by the
+   * iterators.
    */
   template<typename Iterator, typename T, typename Comp>
   Iterator
@@ -321,50 +262,39 @@ namespace Utilities
                const Comp comp);
 
   /**
-   * Given a permutation vector (i.e. a
-   * vector $p_0\ldots p_{N-1}$ where each
-   * $p_i\in [0,N)$ and $p_i\neq p_j$ for
-   * $i\neq j$), produce the reverse
+   * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+   * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the reverse
    * permutation $q_i=N-1-p_i$.
    */
   std::vector<unsigned int>
   reverse_permutation (const std::vector<unsigned int> &permutation);
 
   /**
-   * Given a permutation vector (i.e. a
-   * vector $p_0\ldots p_{N-1}$ where each
-   * $p_i\in [0,N)$ and $p_i\neq p_j$ for
-   * $i\neq j$), produce the inverse
-   * permutation $q_0\ldots q_{N-1}$ so that
-   * $q_{p_i}=p_{q_i}=i$.
+   * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+   * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the inverse
+   * permutation $q_0\ldots q_{N-1}$ so that $q_{p_i}=p_{q_i}=i$.
    */
   std::vector<unsigned int>
   invert_permutation (const std::vector<unsigned int> &permutation);
 
   /**
-   * Given a permutation vector (i.e. a
-   * vector $p_0\ldots p_{N-1}$ where each
-   * $p_i\in [0,N)$ and $p_i\neq p_j$ for
-   * $i\neq j$), produce the reverse
+   * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+   * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the reverse
    * permutation $q_i=N-1-p_i$.
    */
   std::vector<unsigned long long int>
   reverse_permutation (const std::vector<unsigned long long int> &permutation);
 
   /**
-   * Given a permutation vector (i.e. a
-   * vector $p_0\ldots p_{N-1}$ where each
-   * $p_i\in [0,N)$ and $p_i\neq p_j$ for
-   * $i\neq j$), produce the inverse
-   * permutation $q_0\ldots q_{N-1}$ so that
-   * $q_{p_i}=p_{q_i}=i$.
+   * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+   * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the inverse
+   * permutation $q_0\ldots q_{N-1}$ so that $q_{p_i}=p_{q_i}=i$.
    */
   std::vector<unsigned long long int>
   invert_permutation (const std::vector<unsigned long long int> &permutation);
 
   /**
-   * A namespace for utility functions that
-   * probe system properties.
+   * A namespace for utility functions that probe system properties.
    *
    * @ingroup utilities
    */
@@ -372,22 +302,17 @@ namespace Utilities
   {
 
     /**
-     * Return the CPU load as returned by
-     * "uptime". Note that the interpretation
-     * of this number depends on the actual
-     * number of processors in the
-     * machine. This is presently only
-     * implemented on Linux, using the
-     * /proc/loadavg pseudo-file, on other
-     * systems we simply return zero.
+     * Return the CPU load as returned by "uptime". Note that the
+     * interpretation of this number depends on the actual number of
+     * processors in the machine. This is presently only implemented on Linux,
+     * using the /proc/loadavg pseudo-file, on other systems we simply return
+     * zero.
      */
     double get_cpu_load ();
 
     /**
-     * Structure that hold information about
-     * memory usage in kB. Used by
-     * get_memory_stats(). See man 5 proc
-     * entry /status for details.
+     * Structure that hold information about memory usage in kB. Used by
+     * get_memory_stats(). See man 5 proc entry /status for details.
      */
     struct MemoryStats
     {
@@ -399,17 +324,14 @@ namespace Utilities
 
 
     /**
-     * Fills the @p stats structure with
-     * information about the memory
-     * consumption of this process. This is
-     * only implemented on Linux.
+     * Fills the @p stats structure with information about the memory
+     * consumption of this process. This is only implemented on Linux.
      */
     void get_memory_stats (MemoryStats &stats);
 
 
     /**
-     * Return the name of the host this
-     * process runs on.
+     * Return the name of the host this process runs on.
      */
     std::string get_hostname ();
 
@@ -420,26 +342,15 @@ namespace Utilities
     std::string get_time ();
 
     /**
-     * Return whether (i) deal.II has
-     * been compiled to support MPI
-     * (for example by compiling with
-     * <code>CXX=mpiCC</code>) and if
-     * so whether (ii)
-     * <code>MPI_Init()</code> has
-     * been called (for example using
-     * the
-     * Utilities::System::MPI_InitFinalize
-     * class). In other words, the
-     * result indicates whether the
-     * current job is running under
-     * MPI.
+     * Return whether (i) deal.II has been compiled to support MPI (for
+     * example by compiling with <code>CXX=mpiCC</code>) and if so whether
+     * (ii) <code>MPI_Init()</code> has been called (for example using the
+     * Utilities::System::MPI_InitFinalize class). In other words, the result
+     * indicates whether the current job is running under MPI.
      *
-     * @note The function does not
-     * take into account whether an
-     * MPI job actually runs on more
-     * than one processor or is, in
-     * fact, a single-node job that
-     * happens to run under MPI.
+     * @note The function does not take into account whether an MPI job
+     * actually runs on more than one processor or is, in fact, a single-node
+     * job that happens to run under MPI.
      */
     bool job_supports_mpi ();
 
@@ -451,26 +362,21 @@ namespace Utilities
     bool program_uses_mpi () DEAL_II_DEPRECATED;
 
     /**
-     * @name Functions that work
-     * in parallel via MPI. The
-     * functions following here
-     * are all deprecated and have
-     * been moved to namespace
+     * @name Functions that work in parallel via MPI. The functions following
+     * here are all deprecated and have been moved to namespace
      * Utilities::MPI.
      */
     /** @{ */
 
     /**
-     * This function is an alias for
-     * Utilities::MPI::n_mpi_processes.
+     * This function is an alias for Utilities::MPI::n_mpi_processes.
      *
      * @deprecated
      */
     unsigned int get_n_mpi_processes (const MPI_Comm &mpi_communicator) DEAL_II_DEPRECATED;
 
     /**
-     * This function is an alias for
-     * Utilities::MPI::this_mpi_process.
+     * This function is an alias for Utilities::MPI::this_mpi_process.
      *
      * @deprecated
      */
@@ -488,8 +394,7 @@ namespace Utilities
 
 
     /**
-     * This function is an alias for
-     * Utilities::MPI::duplicate_communicator.
+     * This function is an alias for Utilities::MPI::duplicate_communicator.
      *
      * @deprecated
      */
@@ -532,170 +437,110 @@ namespace Utilities
   namespace Trilinos
   {
     /**
-     * Returns a Trilinos Epetra_Comm
-     * object needed for creation of
+     * Returns a Trilinos Epetra_Comm object needed for creation of
      * Epetra_Maps.
      *
-     * If deal.II has been configured to use
-     * a compiler that does not support MPI
-     * then the resulting communicator will
-     * be a serial one. Otherwise, the
-     * communicator will correspond to
-     * MPI_COMM_WORLD, i.e. a communicator
-     * that encompasses all processes within
-     * this MPI universe.
+     * If deal.II has been configured to use a compiler that does not support
+     * MPI then the resulting communicator will be a serial one. Otherwise,
+     * the communicator will correspond to MPI_COMM_WORLD, i.e. a communicator
+     * that encompasses all processes within this MPI universe.
      */
     const Epetra_Comm &comm_world();
 
     /**
-     * Returns a Trilinos Epetra_Comm
-     * object needed for creation of
+     * Returns a Trilinos Epetra_Comm object needed for creation of
      * Epetra_Maps.
      *
-     * If deal.II has been configured to use
-     * a compiler that does not support MPI
-     * then the resulting communicator will
-     * be a serial one. Otherwise, the
-     * communicator will correspond to
-     * MPI_COMM_SELF, i.e. a communicator
-     * that comprises only this one
-     * processor.
+     * If deal.II has been configured to use a compiler that does not support
+     * MPI then the resulting communicator will be a serial one. Otherwise,
+     * the communicator will correspond to MPI_COMM_SELF, i.e. a communicator
+     * that comprises only this one processor.
      */
     const Epetra_Comm &comm_self();
 
     /**
-     * Given a communicator, duplicate it. If
-     * the given communicator is serial, that
-     * means to just return a copy of
-     * itself. On the other hand, if it is
-     * %parallel, we duplicate the underlying
-     * MPI_Comm object: we create a separate
-     * MPI communicator that contains the
-     * same processors and in the same order
-     * but has a separate identifier distinct
-     * from the given communicator. The
-     * function returns a pointer to a new
-     * object of a class derived from
-     * Epetra_Comm. The caller of this
-     * function needs to assume ownership of
-     * this function. The returned object
-     * should be destroyed using the
-     * destroy_communicator() function.
+     * Given a communicator, duplicate it. If the given communicator is
+     * serial, that means to just return a copy of itself. On the other hand,
+     * if it is %parallel, we duplicate the underlying MPI_Comm object: we
+     * create a separate MPI communicator that contains the same processors
+     * and in the same order but has a separate identifier distinct from the
+     * given communicator. The function returns a pointer to a new object of a
+     * class derived from Epetra_Comm. The caller of this function needs to
+     * assume ownership of this function. The returned object should be
+     * destroyed using the destroy_communicator() function.
      *
-     * This facility is used to separate
-     * streams of communication. For example,
-     * a program could simply use
-     * MPI_Comm_World for everything. But it
-     * is easy to come up with scenarios
-     * where sometimes not all processors
-     * participate in a communication that is
-     * intended to be global -- for example
-     * if we assemble a matrix on a coarse
-     * mesh with fewer cells than there are
-     * processors, some processors may not
-     * sync their matrices with the rest
-     * because they haven't written into it
-     * because they own no cells. That's
-     * clearly a bug. However, if these
-     * processors just continue their work,
-     * and the next %parallel operation
-     * happens to be a sync on a different
-     * matrix, then the sync could succeed --
-     * by accident, since different
-     * processors are talking about different
-     * matrices.
+     * This facility is used to separate streams of communication. For
+     * example, a program could simply use MPI_Comm_World for everything. But
+     * it is easy to come up with scenarios where sometimes not all processors
+     * participate in a communication that is intended to be global -- for
+     * example if we assemble a matrix on a coarse mesh with fewer cells than
+     * there are processors, some processors may not sync their matrices with
+     * the rest because they haven't written into it because they own no
+     * cells. That's clearly a bug. However, if these processors just continue
+     * their work, and the next %parallel operation happens to be a sync on a
+     * different matrix, then the sync could succeed -- by accident, since
+     * different processors are talking about different matrices.
      *
-     * This kind of situation can be avoided
-     * if we use different communicators for
-     * different matrices which reduces the
-     * likelihood that communications meant
-     * to be separate aren't recognized as
-     * such just because they happen on the
-     * same communicator. In addition, it is
-     * conceivable that some MPI operations
-     * can be parallelized using multiple
-     * threads because their communicators
-     * identifies the communication in
-     * question, not their relative timing as
-     * is the case in a sequential program
-     * that just uses a single communicator.
+     * This kind of situation can be avoided if we use different communicators
+     * for different matrices which reduces the likelihood that communications
+     * meant to be separate aren't recognized as such just because they happen
+     * on the same communicator. In addition, it is conceivable that some MPI
+     * operations can be parallelized using multiple threads because their
+     * communicators identifies the communication in question, not their
+     * relative timing as is the case in a sequential program that just uses a
+     * single communicator.
      */
     Epetra_Comm *
     duplicate_communicator (const Epetra_Comm &communicator);
 
     /**
-     * Given an Epetra communicator that was
-     * created by the
-     * duplicate_communicator() function,
-     * destroy the underlying MPI
-     * communicator object and reset the
-     * Epetra_Comm object to a the result of
+     * Given an Epetra communicator that was created by the
+     * duplicate_communicator() function, destroy the underlying MPI
+     * communicator object and reset the Epetra_Comm object to a the result of
      * comm_self().
      *
-     * It is necessary to call this function
-     * at the time when the result of
-     * duplicate_communicator() is no longer
-     * needed. The reason is that in that
-     * function, we first create a new
-     * MPI_Comm object and then create an
-     * Epetra_Comm around it. While we can
-     * take care of destroying the latter, it
-     * doesn't destroy the communicator since
-     * it can only assume that it may also be
-     * still used by other objects in the
-     * program. Consequently, we have to take
-     * care of destroying it ourselves,
-     * explicitly.
+     * It is necessary to call this function at the time when the result of
+     * duplicate_communicator() is no longer needed. The reason is that in
+     * that function, we first create a new MPI_Comm object and then create an
+     * Epetra_Comm around it. While we can take care of destroying the latter,
+     * it doesn't destroy the communicator since it can only assume that it
+     * may also be still used by other objects in the program. Consequently,
+     * we have to take care of destroying it ourselves, explicitly.
      *
-     * This function does exactly
-     * that. Because this has to happen while
-     * the Epetra_Comm object is still
-     * around, it first resets the latter and
-     * then destroys the communicator object.
+     * This function does exactly that. Because this has to happen while the
+     * Epetra_Comm object is still around, it first resets the latter and then
+     * destroys the communicator object.
      *
-     * @note If you call this function on an
-     * Epetra_Comm object that is not created
-     * by duplicate_communicator(), you are
-     * likely doing something quite
-     * wrong. Don't do this.
+     * @note If you call this function on an Epetra_Comm object that is not
+     * created by duplicate_communicator(), you are likely doing something
+     * quite wrong. Don't do this.
      */
     void
     destroy_communicator (Epetra_Comm &communicator);
 
     /**
-     * Return the number of MPI processes
-     * there exist in the given communicator
-     * object. If this is a sequential job,
-     * it returns 1.
+     * Return the number of MPI processes there exist in the given
+     * communicator object. If this is a sequential job, it returns 1.
      */
     unsigned int get_n_mpi_processes (const Epetra_Comm &mpi_communicator);
 
     /**
-     * Return the number of the present MPI
-     * process in the space of processes
-     * described by the given
-     * communicator. This will be a unique
-     * value for each process between zero
-     * and (less than) the number of all
-     * processes (given by
-     * get_n_mpi_processes()).
+     * Return the number of the present MPI process in the space of processes
+     * described by the given communicator. This will be a unique value for
+     * each process between zero and (less than) the number of all processes
+     * (given by get_n_mpi_processes()).
      */
     unsigned int get_this_mpi_process (const Epetra_Comm &mpi_communicator);
 
     /**
-     * Given a Trilinos Epetra map, create a
-     * new map that has the same subdivision
-     * of elements to processors but uses the
-     * given communicator object instead of
-     * the one stored in the first
-     * argument. In essence, this means that
-     * we create a map that communicates
-     * among the same processors in the same
-     * way, but using a separate channel.
+     * Given a Trilinos Epetra map, create a new map that has the same
+     * subdivision of elements to processors but uses the given communicator
+     * object instead of the one stored in the first argument. In essence,
+     * this means that we create a map that communicates among the same
+     * processors in the same way, but using a separate channel.
      *
-     * This function is typically used with a
-     * communicator that has been obtained by
-     * the duplicate_communicator() function.
+     * This function is typically used with a communicator that has been
+     * obtained by the duplicate_communicator() function.
      */
     Epetra_Map
     duplicate_map (const Epetra_BlockMap  &map,
index f472b51e9edac9a0c0c8c7abc8811ec2a12e0bf2..0e6055b69f011cee000d6fae41824ca683bbdc98 100644 (file)
@@ -26,13 +26,12 @@ DEAL_II_NAMESPACE_OPEN
  * Filter a range out of any object having a random access <tt>operator[]
  * (unsigned int)</tt> and a function <tt>size() const</tt>.
  *
- * The use of this object is straightforward. It duplicates the
- * random access operator of the <tt>VECTOR</tt> and adds an offset to
- * every index.
+ * The use of this object is straightforward. It duplicates the random access
+ * operator of the <tt>VECTOR</tt> and adds an offset to every index.
  *
- * Some precautions have to be taken if it is used for a constant
- * vector: the VectorSlice object has to be constant, too. The
- * appropriate initalization sequence is like this:
+ * Some precautions have to be taken if it is used for a constant vector: the
+ * VectorSlice object has to be constant, too. The appropriate initalization
+ * sequence is like this:
  *
  * @code
  *   void f(const std::vector<int>& v)
@@ -50,45 +49,34 @@ class VectorSlice
 {
 public:
   /**
-   * Construct a vector slice
-   * containing the whole
-   * vector. Comes handy, if you
-   * did not want to have a slice
-   * at all, but the function you
-   * call wants it: just put in the
-   * vector itself as argument and
-   * let this constructor make a
+   * Construct a vector slice containing the whole vector. Comes handy, if you
+   * did not want to have a slice at all, but the function you call wants it:
+   * just put in the vector itself as argument and let this constructor make a
    * slice for you.
    */
   VectorSlice(VECTOR &v);
   /**
-   * The real constructor for a
-   * vector slice, allowing you to
-   * specify the start index and
-   * the length of the slice.
+   * The real constructor for a vector slice, allowing you to specify the
+   * start index and the length of the slice.
    */
   VectorSlice(VECTOR &v,
               unsigned int start,
               unsigned int length);
 
   /**
-   * Return the length of the slice
-   * using the same interface as
+   * Return the length of the slice using the same interface as
    * <tt>std::vector</tt>.
    */
   unsigned int size() const;
 
   /**
-   * Access an element of the slice
-   * using the same interface as
+   * Access an element of the slice using the same interface as
    * <tt>std::vector</tt>.
    */
   typename VECTOR::reference operator[] (unsigned int i);
 
   /**
-   * Access an element of a
-   * constant slice using the same
-   * interface as
+   * Access an element of a constant slice using the same interface as
    * <tt>std::vector</tt>.
    */
   typename VECTOR::const_reference operator[] (unsigned int i) const;
@@ -130,8 +118,8 @@ private:
 
 
 /**
- * Helper function for creating temporary objects without typing
- * template arguments.
+ * Helper function for creating temporary objects without typing template
+ * arguments.
  *
  * @relates VectorSlice
  * @author Guido Kanschat, 2004
@@ -148,8 +136,8 @@ make_slice (VECTOR &v)
 
 
 /**
- * Helper function for creating temporary objects without typing
- * template arguments.
+ * Helper function for creating temporary objects without typing template
+ * arguments.
  *
  * @relates VectorSlice
  * @author Guido Kanschat, 2004
index 7b903e19dbd4e81b665491541bb5ad791050c887..f73d54f0898c3038f43919dc051aec80688319fe 100644 (file)
@@ -1273,53 +1273,52 @@ private:
 
 
 /**
- * This generic class defines a unified interface to a vectorized data
- * type. For general template arguments, this class simply corresponds to
- * the template argument. For example, VectorizedArray<long double> is
- * nothing else but a wrapper around <tt>long double</tt> with exactly one
- * data field of type <tt>long double</tt> and overloaded arithmetic
- * operations. This means that <tt>VectorizedArray<ComplicatedType></tt> has
- * a similar layout as ComplicatedType, provided that ComplicatedType
- * defines basic arithmetic operations. For floats and doubles, an array of
- * numbers are packed together, though. The number of elements packed
- * together depend on the computer system and compiler flags that are used
- * for compilation of deal.II. The fundamental idea of these packed data
- * types is to use one single CPU instruction to perform arithmetic
- * operations on the whole array using the processor's vector units. Most
- * computer systems by 2010 standards will use an array of two doubles and
- * four floats, respectively (this corresponds to the SSE/SSE2 data sets)
- * when compiling deal.II on 64-bit operating systems. On Intel Sandy Bridge
- * processors and newer or AMD Bulldozer processors and newer, four doubles
- * and eight floats are used when deal.II is configured e.g. using gcc with
- * --with-cpu=native or --with-cpu=corei7-avx. On compilations with AVX-512
- * support, eight doubles and sixteen floats are used.
+ * This generic class defines a unified interface to a vectorized data type.
+ * For general template arguments, this class simply corresponds to the
+ * template argument. For example, VectorizedArray<long double> is nothing
+ * else but a wrapper around <tt>long double</tt> with exactly one data field
+ * of type <tt>long double</tt> and overloaded arithmetic operations. This
+ * means that <tt>VectorizedArray<ComplicatedType></tt> has a similar layout
+ * as ComplicatedType, provided that ComplicatedType defines basic arithmetic
+ * operations. For floats and doubles, an array of numbers are packed
+ * together, though. The number of elements packed together depend on the
+ * computer system and compiler flags that are used for compilation of
+ * deal.II. The fundamental idea of these packed data types is to use one
+ * single CPU instruction to perform arithmetic operations on the whole array
+ * using the processor's vector units. Most computer systems by 2010 standards
+ * will use an array of two doubles and four floats, respectively (this
+ * corresponds to the SSE/SSE2 data sets) when compiling deal.II on 64-bit
+ * operating systems. On Intel Sandy Bridge processors and newer or AMD
+ * Bulldozer processors and newer, four doubles and eight floats are used when
+ * deal.II is configured e.g. using gcc with --with-cpu=native or --with-
+ * cpu=corei7-avx. On compilations with AVX-512 support, eight doubles and
+ * sixteen floats are used.
  *
- * This behavior of this class is made similar to the basic data types
- * double and float. The definition of a vectorized array does not
- * initialize the data field but rather leaves it undefined, as is the case
- * for double and float. However, when calling something like
- * VectorizedArray<double> a = VectorizedArray<double>(), it sets all numbers in this
- * field to zero. In other words, this class is a plain old data (POD) type
- * which has an equivalent C representation and can e.g. be safely copied
- * with std::memcpy. This POD layout is also necessary for ensuring correct
- * alignment of data with address boundaries when collected in a vector
- * (i.e., when the first element in a vector is properly aligned, all
- * subsequent elements will be correctly aligned, too).
+ * This behavior of this class is made similar to the basic data types double
+ * and float. The definition of a vectorized array does not initialize the
+ * data field but rather leaves it undefined, as is the case for double and
+ * float. However, when calling something like VectorizedArray<double> a =
+ * VectorizedArray<double>(), it sets all numbers in this field to zero. In
+ * other words, this class is a plain old data (POD) type which has an
+ * equivalent C representation and can e.g. be safely copied with std::memcpy.
+ * This POD layout is also necessary for ensuring correct alignment of data
+ * with address boundaries when collected in a vector (i.e., when the first
+ * element in a vector is properly aligned, all subsequent elements will be
+ * correctly aligned, too).
  *
  * Note that for proper functioning of this class, certain data alignment
- * rules must be respected. This is because the computer expects the
- * starting address of a VectorizedArray<double> field at specific addresses
- * in memory (usually, the address of the vectorized array should be a
- * multiple of the length of the array in bytes). Otherwise, a segmentation
- * fault or a severe loss of performance might occur. When creating a single
- * data field on the stack like <tt>VectorizedArray<double> a =
- * VectorizedArray<double>()</tt>, the compiler will take care of data
- * alignment automatically. However, when allocating a long vector of
- * VectorizedArray<double> data, one needs to respect these rules. Use the
- * class AlignedVector or data containers based on AlignedVector (such as
- * Table) for this purpose. It is a class very similar to
- * std::vector otherwise but always makes sure that data is correctly
- * aligned.
+ * rules must be respected. This is because the computer expects the starting
+ * address of a VectorizedArray<double> field at specific addresses in memory
+ * (usually, the address of the vectorized array should be a multiple of the
+ * length of the array in bytes). Otherwise, a segmentation fault or a severe
+ * loss of performance might occur. When creating a single data field on the
+ * stack like <tt>VectorizedArray<double> a = VectorizedArray<double>()</tt>,
+ * the compiler will take care of data alignment automatically. However, when
+ * allocating a long vector of VectorizedArray<double> data, one needs to
+ * respect these rules. Use the class AlignedVector or data containers based
+ * on AlignedVector (such as Table) for this purpose. It is a class very
+ * similar to std::vector otherwise but always makes sure that data is
+ * correctly aligned.
  *
  * @author Katharina Kormann, Martin Kronbichler, 2010, 2011
  */
@@ -1934,8 +1933,8 @@ namespace std
 
 
   /**
-   * Computes the tangent of a vectorized data field. The result is returned as
-   * vectorized array in the form <tt>{tan(x[0]), tan(x[1]), ...,
+   * Computes the tangent of a vectorized data field. The result is returned
+   * as vectorized array in the form <tt>{tan(x[0]), tan(x[1]), ...,
    * tan(x[n_array_elements-1])}</tt>.
    *
    * @relates VectorizedArray
@@ -1956,8 +1955,8 @@ namespace std
 
 
   /**
-   * Computes the exponential of a vectorized data field. The result is returned
-   * as vectorized array in the form <tt>{exp(x[0]), exp(x[1]), ...,
+   * Computes the exponential of a vectorized data field. The result is
+   * returned as vectorized array in the form <tt>{exp(x[0]), exp(x[1]), ...,
    * exp(x[n_array_elements-1])}</tt>.
    *
    * @relates VectorizedArray
@@ -2000,9 +1999,9 @@ namespace std
 
 
   /**
-   * Computes the square root of a vectorized data field. The result is returned
-   * as vectorized array in the form <tt>{sqrt(x[0]), sqrt(x[1]), ...,
-   * sqrt(x[n_array_elements-1])}</tt>.
+   * Computes the square root of a vectorized data field. The result is
+   * returned as vectorized array in the form <tt>{sqrt(x[0]), sqrt(x[1]),
+   * ..., sqrt(x[n_array_elements-1])}</tt>.
    *
    * @relates VectorizedArray
    */
index 4f86dec6cfba07713195183332cec4793009ff95..3e70430879ffc7f1c40da6a6301afb55734132b3 100644 (file)
@@ -42,14 +42,13 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * A namespace whose main template function supports running multiple
- * threads each of which operates on a subset of the given range of
- * objects. The class uses the Intel Threading Building Blocks (TBB)
- * to load balance the individual subranges onto the available
- * threads. For a lengthy discussion of the rationale of this class,
- * see the @ref threads "Parallel computing with multiple processors"
- * module. It is used in the tutorial first in step-9, and again in
- * step-13, step-14, step-32 and others.
+ * A namespace whose main template function supports running multiple threads
+ * each of which operates on a subset of the given range of objects. The class
+ * uses the Intel Threading Building Blocks (TBB) to load balance the
+ * individual subranges onto the available threads. For a lengthy discussion
+ * of the rationale of this class, see the @ref threads "Parallel computing
+ * with multiple processors" module. It is used in the tutorial first in
+ * step-9, and again in step-13, step-14, step-32 and others.
  *
  * The class is built on the following premise: One frequently has some work
  * that needs to be done on a sequence of objects; a prototypical example is
@@ -59,17 +58,17 @@ DEAL_II_NAMESPACE_OPEN
  * shared memory. However, some other part of this work may need to be
  * synchronised and be done in order. In the example of assembling a matrix,
  * the computation of local contributions can be done entirely in parallel,
- * but copying the local contributions into the global matrix requires
- * some care: First, several threads can't write at the same time, but need to
+ * but copying the local contributions into the global matrix requires some
+ * care: First, several threads can't write at the same time, but need to
  * synchronise writing using a mutex; secondly, we want the order in which
  * local contributions are added to the global matrix to be always the same
  * because floating point addition is not commutative and adding local
  * contributions to the global matrix in different orders leads to subtly
  * different results that can affect the number of iterations for iterative
- * solvers as well as the round-off error in the solution in random
- * ways. Consequently, we want to ensure that only one thread at a time writes
- * into the global matrix, and that results are copied in a stable and
- * reproducible order.
+ * solvers as well as the round-off error in the solution in random ways.
+ * Consequently, we want to ensure that only one thread at a time writes into
+ * the global matrix, and that results are copied in a stable and reproducible
+ * order.
  *
  * This class implements a framework for this work model. It works with a
  * stream of objects given by an iterator range, runs a worker function in
@@ -87,7 +86,8 @@ DEAL_II_NAMESPACE_OPEN
  * created (typically as many as there are processor cores), but the number of
  * items that may be active at any given time is specified by the argument to
  * the constructor. It should be bigger or equal to the number of processor
- * cores - the default is four times the number of cores on the current system.
+ * cores - the default is four times the number of cores on the current
+ * system.
  *
  * Items are created upon request by the TBB whenever one of the worker
  * threads is idle or is expected to become idle. It is then handed off to a
@@ -100,30 +100,30 @@ DEAL_II_NAMESPACE_OPEN
  * Typically, worker functions need additional data, for example FEValues
  * objects, input data vectors, etc, some of which can not be shared among
  * threads. To this end, the run() function takes another template argument,
- * ScratchData, which designates a type objects of which are stored with
- * each item and which threads can use as private data without having to
- * share them with other threads. The run() function takes an additional
- * argument with an object of type ScratchData that is going to be copied
- * for the arguments passed to each of the worker functions.
+ * ScratchData, which designates a type objects of which are stored with each
+ * item and which threads can use as private data without having to share them
+ * with other threads. The run() function takes an additional argument with an
+ * object of type ScratchData that is going to be copied for the arguments
+ * passed to each of the worker functions.
  *
- * In addition, worker functions store their results in objects of template type
- * CopyData. These are then handed off to a separate function, called copier,
- * that may use the stored results to transfer them into permanent
+ * In addition, worker functions store their results in objects of template
+ * type CopyData. These are then handed off to a separate function, called
+ * copier, that may use the stored results to transfer them into permanent
  * storage. For example, it may copy the results of local contributions to a
  * matrix computed by a worker function into the global matrix. In contrast to
  * the worker function, however, only one instance of the copier is run at any
  * given time; it can therefore safely copy local contributions into the
  * global matrix without the need to lock the global object using a mutex or
  * similar means. Furthermore, it is guaranteed that the copier is run with
- * CopyData objects in the same order in which their associated items
- * were created; consequently, even if worker threads may compute results in
+ * CopyData objects in the same order in which their associated items were
+ * created; consequently, even if worker threads may compute results in
  * unspecified order, the copier always receives the results in exactly the
  * same order as the items were created.
  *
- * Once an item is processed by the copier, it is deleted and the
- * ScratchData and CopyData objects that were used in its computation
- * are considered unused and may be re-used for the next invokation of
- * the worker function, on this or another thread.
+ * Once an item is processed by the copier, it is deleted and the ScratchData
+ * and CopyData objects that were used in its computation are considered
+ * unused and may be re-used for the next invokation of the worker function,
+ * on this or another thread.
  *
  * The functions in this namespace only really work in parallel when
  * multithread mode was selected during deal.II configuration. Otherwise they
@@ -152,9 +152,9 @@ namespace WorkStream
      * Bangerth (see @ref workstream_paper).
      *
      * Even though this implementation is slower than the third implementation
-     * discussed in that paper, we need to keep it around for two reasons:
-     * (i) a user may not give us a graph coloring, (ii) we want to use
-     * this implementation for colors that are just too small.
+     * discussed in that paper, we need to keep it around for two reasons: (i)
+     * a user may not give us a graph coloring, (ii) we want to use this
+     * implementation for colors that are just too small.
      */
     namespace Implementation2
     {
@@ -176,8 +176,9 @@ namespace WorkStream
         struct ItemType
         {
           /**
-           * A structure that contains a pointer to a scratch data object along
-           * with a flag that indicates whether this object is currently in use.
+           * A structure that contains a pointer to a scratch data object
+           * along with a flag that indicates whether this object is currently
+           * in use.
            */
           struct ScratchDataObject
           {
@@ -228,9 +229,9 @@ namespace WorkStream
           std::vector<Iterator> work_items;
 
           /**
-           * The CopyData objects that the Worker part of the pipeline
-           * fills for each work item. Again, only the first n_items
-           * elements are what we care about.
+           * The CopyData objects that the Worker part of the pipeline fills
+           * for each work item. Again, only the first n_items elements are
+           * what we care about.
            */
           std::vector<CopyData> copy_datas;
 
@@ -242,35 +243,35 @@ namespace WorkStream
           unsigned int          n_items;
 
           /**
-           * Pointer to a thread local variable identifying the scratch data objects
-           * this thread will use. The initial implementation of this
-           * class using thread local variables provided only a single
-           * scratch object per thread. This doesn't work, because
-           * the worker functions may start tasks itself and then call
+           * Pointer to a thread local variable identifying the scratch data
+           * objects this thread will use. The initial implementation of this
+           * class using thread local variables provided only a single scratch
+           * object per thread. This doesn't work, because the worker
+           * functions may start tasks itself and then call
            * Threads::TaskGroup::join_all() or a similar function, which the
-           * TBB scheduler may use to run something else on the current
-           * thread -- for example another instance of the worker function.
-           * Consequently, there would be two instances of the worker
-           * function that use the same scratch object if we only
-           * provided a single scratch object per thread. The solution is
-           * to provide a list of scratch objects for each thread, together
-           * with a flag indicating whether this scratch object is currently
-           * used. If a thread needs a scratch object, it walks this list
-           * until it finds an unused object, or, if there is none, creates one
-           * itself. Note that we need not use synchronization primitives
-           * for this process since the lists are thread-local and
-           * we are guaranteed that only a single thread accesses them as long
-           * as we have no yield point in between the accesses to the list.
+           * TBB scheduler may use to run something else on the current thread
+           * -- for example another instance of the worker function.
+           * Consequently, there would be two instances of the worker function
+           * that use the same scratch object if we only provided a single
+           * scratch object per thread. The solution is to provide a list of
+           * scratch objects for each thread, together with a flag indicating
+           * whether this scratch object is currently used. If a thread needs
+           * a scratch object, it walks this list until it finds an unused
+           * object, or, if there is none, creates one itself. Note that we
+           * need not use synchronization primitives for this process since
+           * the lists are thread-local and we are guaranteed that only a
+           * single thread accesses them as long as we have no yield point in
+           * between the accesses to the list.
            *
-           * The pointers to scratch objects stored in each of these lists must
-           * be so that they are deleted on all threads when the thread
+           * The pointers to scratch objects stored in each of these lists
+           * must be so that they are deleted on all threads when the thread
            * local object is destroyed. This is achieved by using shared_ptr.
            *
-           * Note that when a worker needs to create a scratch object, it allocates
-           * it using sample_scratch_data to copy from. This has
-           * the advantage of a first-touch initialization, i.e., the
-           * memory for the scratch data object is allocated and initialized
-           * by the same thread that will later use it.
+           * Note that when a worker needs to create a scratch object, it
+           * allocates it using sample_scratch_data to copy from. This has the
+           * advantage of a first-touch initialization, i.e., the memory for
+           * the scratch data object is allocated and initialized by the same
+           * thread that will later use it.
            */
           Threads::ThreadLocalStorage<ScratchDataList> *scratch_data;
 
@@ -288,9 +289,8 @@ namespace WorkStream
 
 
           /**
-           * Default constructor.
-           * Initialize everything that doesn't have a default constructor
-           * itself.
+           * Default constructor. Initialize everything that doesn't have a
+           * default constructor itself.
            */
           ItemType ()
             :
@@ -304,8 +304,8 @@ namespace WorkStream
 
         /**
          * Constructor. Take an iterator range, the size of a buffer that can
-         * hold items, and the sample additional data object that will be passed
-         * to each worker and copier function invokation.
+         * hold items, and the sample additional data object that will be
+         * passed to each worker and copier function invokation.
          */
         IteratorRangeToItemStream (const Iterator       &begin,
                                    const Iterator       &end,
@@ -338,8 +338,7 @@ namespace WorkStream
 
 
         /**
-         * Create an item and return a
-         * pointer to it.
+         * Create an item and return a pointer to it.
          */
         virtual void *operator () (void *)
         {
@@ -393,9 +392,8 @@ namespace WorkStream
 
       private:
         /**
-         * The interval of iterators still to
-         * be worked on. This range will shrink
-         * over time.
+         * The interval of iterators still to be worked on. This range will
+         * shrink over time.
          */
         std::pair<Iterator,Iterator> remaining_iterator_range;
 
@@ -405,63 +403,55 @@ namespace WorkStream
         std::vector<ItemType>        item_buffer;
 
         /**
-         * Pointer to a thread local variable identifying the scratch data objects
-         * this thread will use. The initial implementation of this
-         * class using thread local variables provided only a single
-         * scratch object per thread. This doesn't work, because
-         * the worker functions may start tasks itself and then call
-         * Threads::TaskGroup::join_all() or a similar function, which the
-         * TBB scheduler may use to run something else on the current
-         * thread -- for example another instance of the worker function.
-         * Consequently, there would be two instances of the worker
-         * function that use the same scratch object if we only
-         * provided a single scratch object per thread. The solution is
-         * to provide a list of scratch objects for each thread, together
-         * with a flag indicating whether this scratch object is currently
-         * used. If a thread needs a scratch object, it walks this list
-         * until it finds an unused object, or, if there is none, creates one
-         * itself. Note that we need not use synchronization primitives
-         * for this process since the lists are thread-local and
-         * we are guaranteed that only a single thread accesses them as long
-         * as we have no yield point in between the accesses to the list.
+         * Pointer to a thread local variable identifying the scratch data
+         * objects this thread will use. The initial implementation of this
+         * class using thread local variables provided only a single scratch
+         * object per thread. This doesn't work, because the worker functions
+         * may start tasks itself and then call Threads::TaskGroup::join_all()
+         * or a similar function, which the TBB scheduler may use to run
+         * something else on the current thread -- for example another
+         * instance of the worker function. Consequently, there would be two
+         * instances of the worker function that use the same scratch object
+         * if we only provided a single scratch object per thread. The
+         * solution is to provide a list of scratch objects for each thread,
+         * together with a flag indicating whether this scratch object is
+         * currently used. If a thread needs a scratch object, it walks this
+         * list until it finds an unused object, or, if there is none, creates
+         * one itself. Note that we need not use synchronization primitives
+         * for this process since the lists are thread-local and we are
+         * guaranteed that only a single thread accesses them as long as we
+         * have no yield point in between the accesses to the list.
          *
          * The pointers to scratch objects stored in each of these lists must
-         * be so that they are deleted on all threads when the thread
-         * local object is destroyed. This is achieved by using shared_ptr.
+         * be so that they are deleted on all threads when the thread local
+         * object is destroyed. This is achieved by using shared_ptr.
          *
-         * Note that when a worker needs to create a scratch object, it allocates
-         * it using sample_scratch_data to copy from. This has
-         * the advantage of a first-touch initialization, i.e., the
-         * memory for the scratch data object is allocated and initialized
-         * by the same thread that will later use it.
+         * Note that when a worker needs to create a scratch object, it
+         * allocates it using sample_scratch_data to copy from. This has the
+         * advantage of a first-touch initialization, i.e., the memory for the
+         * scratch data object is allocated and initialized by the same thread
+         * that will later use it.
          */
         Threads::ThreadLocalStorage<typename ItemType::ScratchDataList> thread_local_scratch;
 
         /**
          * A reference to a sample scratch data that will be used to
-         * initialize the thread-local pointers to a scratch data object
-         * each of the worker tasks uses.
+         * initialize the thread-local pointers to a scratch data object each
+         * of the worker tasks uses.
          */
         const ScratchData &sample_scratch_data;
 
         /**
-         * Number of elements of the
-         * iterator range that each
-         * thread should work on
-         * sequentially; a large number
-         * makes sure that each thread
-         * gets a significant amount of
-         * work before the next task
-         * switch happens, whereas a
-         * small number is better for
-         * load balancing.
+         * Number of elements of the iterator range that each thread should
+         * work on sequentially; a large number makes sure that each thread
+         * gets a significant amount of work before the next task switch
+         * happens, whereas a small number is better for load balancing.
          */
         const unsigned int           chunk_size;
 
         /**
-         * Initialize the pointers and vector
-         * elements in the specified entry of
-         * the item_buffer.
+         * Initialize the pointers and vector elements in the specified entry
+         * of the item_buffer.
          */
         void init_buffer_elements (const unsigned int element,
                                    const CopyData    &sample_copy_data)
@@ -483,11 +473,9 @@ namespace WorkStream
 
 
       /**
-       * A class that manages calling the
-       * worker function on a number of
-       * parallel threads. Note that it is, in
-       * the TBB notation, a filter that can
-       * run in parallel.
+       * A class that manages calling the worker function on a number of
+       * parallel threads. Note that it is, in the TBB notation, a filter that
+       * can run in parallel.
        */
       template <typename Iterator,
                 typename ScratchData,
@@ -496,11 +484,8 @@ namespace WorkStream
       {
       public:
         /**
-         * Constructor. Takes a
-         * reference to the object on
-         * which we will operate as
-         * well as a pointer to the
-         * function that will do the
+         * Constructor. Takes a reference to the object on which we will
+         * operate as well as a pointer to the function that will do the
          * assembly.
          */
         Worker (const std_cxx11::function<void (const Iterator &,
@@ -618,17 +603,16 @@ namespace WorkStream
 
       private:
         /**
-         * Pointer to the function
-         * that does the assembling
-         * on the sequence of cells.
+         * Pointer to the function that does the assembling on the sequence of
+         * cells.
          */
         const std_cxx11::function<void (const Iterator &,
                                         ScratchData &,
                                         CopyData &)> worker;
 
         /**
-         * This flag is true if the copier stage exist. If it does not,
-         * the worker has to free the buffer. Otherwise the copier will do it.
+         * This flag is true if the copier stage exist. If it does not, the
+         * worker has to free the buffer. Otherwise the copier will do it.
          */
         bool copier_exist;
       };
@@ -636,12 +620,9 @@ namespace WorkStream
 
 
       /**
-       * A class that manages calling the
-       * copier function. Note that it is, in
-       * the TBB notation, a filter that runs
-       * sequentially, ensuring that all items
-       * are copied in the same order in which
-       * they are created.
+       * A class that manages calling the copier function. Note that it is, in
+       * the TBB notation, a filter that runs sequentially, ensuring that all
+       * items are copied in the same order in which they are created.
        */
       template <typename Iterator,
                 typename ScratchData,
@@ -650,14 +631,9 @@ namespace WorkStream
       {
       public:
         /**
-         * Constructor. Takes a
-         * reference to the object on
-         * which we will operate as
-         * well as a pointer to the
-         * function that will do the
-         * copying from the
-         * additional data object to
-         * the global matrix or
+         * Constructor. Takes a reference to the object on which we will
+         * operate as well as a pointer to the function that will do the
+         * copying from the additional data object to the global matrix or
          * similar.
          */
         Copier (const std_cxx11::function<void (const CopyData &)> &copier)
@@ -728,8 +704,9 @@ namespace WorkStream
     namespace Implementation3
     {
       /**
-       * A structure that contains a pointer to scratch and copy data objects along
-       * with a flag that indicates whether this object is currently in use.
+       * A structure that contains a pointer to scratch and copy data objects
+       * along with a flag that indicates whether this object is currently in
+       * use.
        */
       template <typename Iterator,
                 typename ScratchData,
@@ -778,8 +755,9 @@ namespace WorkStream
 
 
       /**
-       * A class that manages calling the worker and copier functions. Unlike the
-       * other implementations, parallel_for is used instead of a pipeline.
+       * A class that manages calling the worker and copier functions. Unlike
+       * the other implementations, parallel_for is used instead of a
+       * pipeline.
        */
       template <typename Iterator,
                 typename ScratchData,
@@ -907,23 +885,21 @@ namespace WorkStream
         Threads::ThreadLocalStorage<ScratchAndCopyDataList> data;
 
         /**
-         * Pointer to the function
-         * that does the assembling
-         * on the sequence of cells.
+         * Pointer to the function that does the assembling on the sequence of
+         * cells.
          */
         const std_cxx11::function<void (const Iterator &,
                                         ScratchData &,
                                         CopyData &)> worker;
 
         /**
-         * Pointer to the function that does the copying from
-         * local contribution to global object.
+         * Pointer to the function that does the copying from local
+         * contribution to global object.
          */
         const std_cxx11::function<void (const CopyData &)> copier;
 
         /**
-         * References to sample scratch and copy data for
-         * when we need them.
+         * References to sample scratch and copy data for when we need them.
          */
         const ScratchData    &sample_scratch_data;
         const CopyData       &sample_copy_data;
@@ -937,22 +913,21 @@ namespace WorkStream
 
 
   /**
-   * This is one of two main functions of the WorkStream concept, doing work as
-   * described in the introduction to this namespace. It corresponds to
-   * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth,
-   * see @ref workstream_paper .
-   * As such, it takes not a range of iterators described by a begin
-   * and end iterator, but a "colored" graph of iterators where each
-   * color represents cells for which writing the cell contributions into
-   * the global object does not conflict (in other words, these cells
-   * are not neighbors). Each "color" is represented by std::vectors of cells.
-   * The first argument to this function, a set of sets of cells (which are
-   * represent as a vector of vectors, for efficiency), is typically
-   * constructed by calling GraphColoring::make_graph_coloring(). See there
-   * for more information.
+   * This is one of two main functions of the WorkStream concept, doing work
+   * as described in the introduction to this namespace. It corresponds to
+   * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth, see
+   * @ref workstream_paper . As such, it takes not a range of iterators
+   * described by a begin and end iterator, but a "colored" graph of iterators
+   * where each color represents cells for which writing the cell
+   * contributions into the global object does not conflict (in other words,
+   * these cells are not neighbors). Each "color" is represented by
+   * std::vectors of cells. The first argument to this function, a set of sets
+   * of cells (which are represent as a vector of vectors, for efficiency), is
+   * typically constructed by calling GraphColoring::make_graph_coloring().
+   * See there for more information.
    *
-   * This function that can be used for worker and copier objects that
-   * are either pointers to non-member functions or objects that allow to be
+   * This function that can be used for worker and copier objects that are
+   * either pointers to non-member functions or objects that allow to be
    * called with an operator(), for example objects created by std::bind.
    *
    * The two data types <tt>ScratchData</tt> and <tt>CopyData</tt> need to
@@ -987,13 +962,13 @@ namespace WorkStream
 
 
   /**
-   * This is one of two main functions of the WorkStream concept, doing work as
-   * described in the introduction to this namespace. It corresponds to
-   * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth
-   * (see @ref workstream_paper).
+   * This is one of two main functions of the WorkStream concept, doing work
+   * as described in the introduction to this namespace. It corresponds to
+   * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth (see
+   * @ref workstream_paper).
    *
-   * This function that can be used for worker and copier objects that
-   * are either pointers to non-member functions or objects that allow to be
+   * This function that can be used for worker and copier objects that are
+   * either pointers to non-member functions or objects that allow to be
    * called with an operator(), for example objects created by std::bind. If
    * the copier is an empty function, it is ignored in the pipeline.
    *
index 9d8a224515a878c0e875ac4630edebe2fb1c032e..7eba9664e7009d7aceb6431ee77ed6a223bed631 100644 (file)
@@ -36,10 +36,9 @@ namespace parallel
 
     /**
      * Collection of functions controlling refinement and coarsening of
-     * parallel::distributed::Triangulation objects. This namespace
-     * provides similar functionality to the dealii::GridRefinement
-     * namespace, except that it works for meshes that are parallel and
-     * distributed.
+     * parallel::distributed::Triangulation objects. This namespace provides
+     * similar functionality to the dealii::GridRefinement namespace, except
+     * that it works for meshes that are parallel and distributed.
      *
      * @ingroup grid
      * @author Wolfgang Bangerth, 2009
@@ -47,39 +46,24 @@ namespace parallel
     namespace GridRefinement
     {
       /**
-       * Like
-       * dealii::GridRefinement::refine_and_coarsen_fixed_number,
-       * but for parallel distributed
-       * triangulation.
+       * Like dealii::GridRefinement::refine_and_coarsen_fixed_number, but for
+       * parallel distributed triangulation.
        *
-       * The vector of criteria needs to be a
-       * vector of refinement criteria for
-       * all cells active on the current
-       * triangulation,
-       * i.e. <code>tria.n_active_cells()</code>
-       * (and not
-       * <code>tria.n_locally_owned_active_cells()</code>). However,
-       * the function will only look at the
-       * indicators that correspond to those
-       * cells that are actually locally
-       * owned, and ignore the indicators for
-       * all other cells. The function will
-       * then coordinate among all processors
-       * that store part of the triangulation
-       * so that at the end @p
-       * top_fraction_of_cells are refined,
-       * where the fraction is enforced as a
-       * fraction of
-       * Triangulation::n_global_active_cells,
-       * not
-       * Triangulation::n_locally_active_cells
-       * on each processor individually. In
-       * other words, it may be that on some
-       * processors, no cells are refined at
-       * all.
+       * The vector of criteria needs to be a vector of refinement criteria
+       * for all cells active on the current triangulation, i.e.
+       * <code>tria.n_active_cells()</code> (and not
+       * <code>tria.n_locally_owned_active_cells()</code>). However, the
+       * function will only look at the indicators that correspond to those
+       * cells that are actually locally owned, and ignore the indicators for
+       * all other cells. The function will then coordinate among all
+       * processors that store part of the triangulation so that at the end @p
+       * top_fraction_of_cells are refined, where the fraction is enforced as
+       * a fraction of Triangulation::n_global_active_cells, not
+       * Triangulation::n_locally_active_cells on each processor individually.
+       * In other words, it may be that on some processors, no cells are
+       * refined at all.
        *
-       * The same is true for the fraction of
-       * cells that is coarsened.
+       * The same is true for the fraction of cells that is coarsened.
        */
       template <int dim, class Vector, int spacedim>
       void
@@ -90,39 +74,24 @@ namespace parallel
         const double                bottom_fraction_of_cells);
 
       /**
-       * Like
-       * dealii::GridRefinement::refine_and_coarsen_fixed_fraction,
-       * but for parallel distributed
-       * triangulation.
+       * Like dealii::GridRefinement::refine_and_coarsen_fixed_fraction, but
+       * for parallel distributed triangulation.
        *
-       * The vector of criteria needs to be a
-       * vector of refinement criteria for
-       * all cells active on the current
-       * triangulation,
-       * <code>tria.n_active_cells()</code>
-       * (and not
-       * <code>tria.n_locally_owned_active_cells()</code>). However,
-       * the function will only look at the
-       * indicators that correspond to those
-       * cells that are actually locally
-       * owned, and ignore the indicators for
-       * all other cells. The function will
-       * then coordinate among all processors
-       * that store part of the triangulation
-       * so that at the end the smallest
-       * fraction of
-       * Triangulation::n_global_active_cells
-       * (not
-       * Triangulation::n_locally_active_cells
-       * on each processor individually) is
-       * refined that together make up a
-       * total of @p top_fraction_of_error of
-       * the total error. In other words, it
-       * may be that on some processors, no
-       * cells are refined at all.
+       * The vector of criteria needs to be a vector of refinement criteria
+       * for all cells active on the current triangulation,
+       * <code>tria.n_active_cells()</code> (and not
+       * <code>tria.n_locally_owned_active_cells()</code>). However, the
+       * function will only look at the indicators that correspond to those
+       * cells that are actually locally owned, and ignore the indicators for
+       * all other cells. The function will then coordinate among all
+       * processors that store part of the triangulation so that at the end
+       * the smallest fraction of Triangulation::n_global_active_cells (not
+       * Triangulation::n_locally_active_cells on each processor individually)
+       * is refined that together make up a total of @p top_fraction_of_error
+       * of the total error. In other words, it may be that on some
+       * processors, no cells are refined at all.
        *
-       * The same is true for the fraction of
-       * cells that is coarsened.
+       * The same is true for the fraction of cells that is coarsened.
        */
       template <int dim, class Vector, int spacedim>
       void
index 2eff19b41e0037cd44262c9c31e31aa20d887d0d..14db87e84ba74ce9d4fa52cc285d9df421d6720e 100644 (file)
@@ -32,70 +32,73 @@ namespace parallel
   {
     /**
      * Transfers a discrete FE function (like a solution vector) by
-     * interpolation while refining and/or
-     * coarsening a distributed grid and
+     * interpolation while refining and/or coarsening a distributed grid and
      * handles the necessary communication.
      *
      * @note It is important to note, that if you use more than one
-     * SolutionTransfer object at the same time, that the calls to
-     * prepare_*() and interpolate()/deserialize() need to be in the same order.
+     * SolutionTransfer object at the same time, that the calls to prepare_*()
+     * and interpolate()/deserialize() need to be in the same order.
      *
-     * <h3>Note on ghost elements</h3>
-     * In a parallel computation PETSc or Trilinos vector may contain ghost
-     * elements or not. For reading in information with
-     * prepare_for_coarsening_and_refinement() or prepare_serialization() you need
-     * to supply vectors with ghost elements, so that all locally_active elements
-     * can be read. On the other hand, ghosted vectors are generally not writable,
-     * so for calls to interpolate() or deserialize() you need to supply
-     * distributed vectors without ghost elements.
+     * <h3>Note on ghost elements</h3> In a parallel computation PETSc or
+     * Trilinos vector may contain ghost elements or not. For reading in
+     * information with prepare_for_coarsening_and_refinement() or
+     * prepare_serialization() you need to supply vectors with ghost elements,
+     * so that all locally_active elements can be read. On the other hand,
+     * ghosted vectors are generally not writable, so for calls to
+     * interpolate() or deserialize() you need to supply distributed vectors
+     * without ghost elements.
      *
-     * <h3>Transfering a solution</h3>
-     * Here VECTOR is your favorite vector type, e.g. PETScWrappers::MPI::Vector,
-     * TrilinosWrappers::MPI::Vector, or corresponding blockvectors.
+     * <h3>Transfering a solution</h3> Here VECTOR is your favorite vector
+     * type, e.g. PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector,
+     * or corresponding blockvectors.
      * @code
-     SolutionTransfer<dim, VECTOR> soltrans(dof_handler);
-                                         // flag some cells for refinement
-                                         // and coarsening, e.g.
-     GridRefinement::refine_and_coarsen_fixed_fraction(
-       tria, error_indicators, 0.3, 0.05);
-                                         // prepare the triangulation,
-     tria.prepare_coarsening_and_refinement();
-                                         // prepare the SolutionTransfer object
-                                         // for coarsening and refinement and give
-                                         // the solution vector that we intend to
-                                         // interpolate later,
-     soltrans.prepare_for_coarsening_and_refinement(solution);
-                                         // actually execute the refinement,
-     tria.execute_coarsening_and_refinement ();
-                                         // redistribute dofs,
-     dof_handler.distribute_dofs (fe);
-                                         // and interpolate the solution
-     VECTOR interpolated_solution;
-     //create VECTOR in the right size here
-     soltrans.interpolate(interpolated_solution);
-    @endcode
+     SolutionTransfer<dim, VECTOR> soltrans(dof_handler);
+     *                                   // flag some cells for refinement
+     *                                   // and coarsening, e.g.
+     GridRefinement::refine_and_coarsen_fixed_fraction(
+     * tria, error_indicators, 0.3, 0.05);
+     *                                   // prepare the triangulation,
+     tria.prepare_coarsening_and_refinement();
+     *                                   // prepare the SolutionTransfer object
+     *                                   // for coarsening and refinement and give
+     *                                   // the solution vector that we intend to
+     *                                   // interpolate later,
+     soltrans.prepare_for_coarsening_and_refinement(solution);
+     *                                   // actually execute the refinement,
+     tria.execute_coarsening_and_refinement ();
+     *                                   // redistribute dofs,
+     dof_handler.distribute_dofs (fe);
+     *                                   // and interpolate the solution
+     VECTOR interpolated_solution;
+     //create VECTOR in the right size here
+     soltrans.interpolate(interpolated_solution);
+     * @endcode
      *
      * <h3>Use for Serialization</h3>
      *
-     * This class can be used to serialize and later deserialize a distributed mesh with solution vectors
-     * to a file. If you use more than one DoFHandler and therefore more than one SolutionTransfer object, they need to be serialized and deserialized in the same order.
+     * This class can be used to serialize and later deserialize a distributed
+     * mesh with solution vectors to a file. If you use more than one
+     * DoFHandler and therefore more than one SolutionTransfer object, they
+     * need to be serialized and deserialized in the same order.
      *
-     * If vector has the locally relevant DoFs, serialization works as follows:
-     *@code
-
-    parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
-    sol_trans.prepare_serialization (vector);
-
-    triangulation.save(filename);
-    @endcode
-    * For deserialization the vector needs to be a distributed vector (without ghost elements):
-    * @code
-    //[create coarse mesh...]
-    triangulation.load(filename);
-
-    parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
-    sol_trans.deserialize (distributed_vector);
-    @endcode
+     * If vector has the locally relevant DoFs, serialization works as
+     * follows:
+     * *@code
+     *
+     * parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
+     * sol_trans.prepare_serialization (vector);
+     *
+     * triangulation.save(filename);
+     * @endcode
+     * For deserialization the vector needs to be a distributed vector
+     * (without ghost elements):
+     * @code
+     * //[create coarse mesh...]
+     * triangulation.load(filename);
+     *
+     * parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
+     * sol_trans.deserialize (distributed_vector);
+     * @endcode
      *
      *
      * <h3>Interaction with hanging nodes</h3>
@@ -114,8 +117,7 @@ namespace parallel
     {
     public:
       /**
-       * Constructor, takes the current DoFHandler
-       * as argument.
+       * Constructor, takes the current DoFHandler as argument.
        */
       SolutionTransfer(const DH &dof);
       /**
@@ -124,128 +126,97 @@ namespace parallel
       ~SolutionTransfer();
 
       /**
-       * Prepares the @p SolutionTransfer for
-       * coarsening and refinement. It
-       * stores the dof indices of each cell and
-       * stores the dof values of the vectors in
-       * @p all_in in each cell that'll be coarsened.
-       * @p all_in includes all vectors
-       * that are to be interpolated
-       * onto the new (refined and/or
-       * coarsenend) grid.
+       * Prepares the @p SolutionTransfer for coarsening and refinement. It
+       * stores the dof indices of each cell and stores the dof values of the
+       * vectors in @p all_in in each cell that'll be coarsened. @p all_in
+       * includes all vectors that are to be interpolated onto the new
+       * (refined and/or coarsenend) grid.
        */
       void prepare_for_coarsening_and_refinement (const std::vector<const VECTOR *> &all_in);
 
       /**
-       * Same as previous function
-       * but for only one discrete function
-       * to be interpolated.
+       * Same as previous function but for only one discrete function to be
+       * interpolated.
        */
       void prepare_for_coarsening_and_refinement (const VECTOR &in);
 
       /**
-       * Interpolate the data previously stored in this object before
-       * the mesh was refined or coarsened onto the current set of
-       * cells. Do so for each of the vectors provided to
-       * prepare_for_coarsening_and_refinement() and write the result into
-       * the given set of vectors.
+       * Interpolate the data previously stored in this object before the mesh
+       * was refined or coarsened onto the current set of cells. Do so for
+       * each of the vectors provided to
+       * prepare_for_coarsening_and_refinement() and write the result into the
+       * given set of vectors.
        */
       void interpolate (std::vector<VECTOR *> &all_out);
 
       /**
-       * Same as the previous function.
-       * It interpolates only one function.
-       * It assumes the vectors having the
-       * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
-       * <tt>out.size()==n_dofs_refined</tt>)
+       * Same as the previous function. It interpolates only one function. It
+       * assumes the vectors having the right sizes (i.e.
+       * <tt>in.size()==n_dofs_old</tt>, <tt>out.size()==n_dofs_refined</tt>)
        *
-       * Multiple calling of this function is
-       * NOT allowed. Interpolating
-       * several functions can be performed
-       * in one step by using
+       * Multiple calling of this function is NOT allowed. Interpolating
+       * several functions can be performed in one step by using
        * <tt>interpolate (all_in, all_out)</tt>
        */
       void interpolate (VECTOR &out);
 
 
       /**
-       * Return the size in bytes that need
-       * to be stored per cell.
+       * Return the size in bytes that need to be stored per cell.
        */
       unsigned int get_data_size() const;
 
 
       /**
-      * Prepare the serialization of the
-      * given vector. The serialization is
-      * done by Triangulation::save(). The
-      * given vector needs all information
-      * on the locally active DoFs (it must
-      * be ghosted). See documentation of
-      * this class for more information.
-      */
+       * Prepare the serialization of the given vector. The serialization is
+       * done by Triangulation::save(). The given vector needs all information
+       * on the locally active DoFs (it must be ghosted). See documentation of
+       * this class for more information.
+       */
       void prepare_serialization(const VECTOR &in);
 
 
       /**
-       * Same as the function above, only
-       * for a list of vectors.
+       * Same as the function above, only for a list of vectors.
        */
       void prepare_serialization(const std::vector<const VECTOR *> &all_in);
 
 
       /**
-       * Execute the deserialization of the
-       * given vector. This needs to be
-       * done after calling
-       * Triangulation::load(). The given
-       * vector must be a fully distributed
-       * vector without ghost elements. See
-       * documentation of this class for
-       * more information.
+       * Execute the deserialization of the given vector. This needs to be
+       * done after calling Triangulation::load(). The given vector must be a
+       * fully distributed vector without ghost elements. See documentation of
+       * this class for more information.
        */
       void deserialize(VECTOR &in);
 
 
       /**
-       * Same as the function above, only
-       * for a list of vectors.
+       * Same as the function above, only for a list of vectors.
        */
       void deserialize(std::vector<VECTOR *> &all_in);
 
     private:
       /**
-       * Pointer to the degree of
-       * freedom handler to work
-       * with.
+       * Pointer to the degree of freedom handler to work with.
        */
       SmartPointer<const DH,SolutionTransfer<dim,VECTOR,DH> > dof_handler;
 
       /**
-       * A vector that stores
-       * pointers to all the
-       * vectors we are supposed to
-       * copy over from the old to
-       * the new mesh.
+       * A vector that stores pointers to all the vectors we are supposed to
+       * copy over from the old to the new mesh.
        */
       std::vector<const VECTOR *> input_vectors;
 
       /**
-       * The offset that the
-       * Triangulation has assigned
-       * to this object starting at
-       * which we are allowed to
-       * write.
+       * The offset that the Triangulation has assigned to this object
+       * starting at which we are allowed to write.
        */
       unsigned int offset;
 
       /**
-       * A callback function used
-       * to pack the data on the
-       * current mesh into objects
-       * that can later be
-       * retrieved after
-       * refinement, coarsening and
+       * A callback function used to pack the data on the current mesh into
+       * objects that can later be retrieved after refinement, coarsening and
        * repartitioning.
        */
       void pack_callback(const typename Triangulation<dim,dim>::cell_iterator &cell,
@@ -253,13 +224,9 @@ namespace parallel
                          void *data);
 
       /**
-       * A callback function used
-       * to unpack the data on the
-       * current mesh that has been
-       * packed up previously on
-       * the mesh before
-       * refinement, coarsening and
-       * repartitioning.
+       * A callback function used to unpack the data on the current mesh that
+       * has been packed up previously on the mesh before refinement,
+       * coarsening and repartitioning.
        */
       void unpack_callback(const typename Triangulation<dim,dim>::cell_iterator &cell,
                            const typename Triangulation<dim,dim>::CellStatus status,
index fc13758a915c48bcb9c523f74e221519cdc2cccc..52040c11f45fdc591bb38a40cb8bc9029dc7de89 100644 (file)
@@ -69,12 +69,11 @@ namespace internal
   namespace p4est
   {
     /**
-     * A structure whose explicit specializations contain typedefs to
-     * the relevant p4est_* and p8est_* types. Using this structure,
-     * for example by saying <code>types@<dim@>::connectivity</code>
-     * we can write code in a dimension independent way, either
-     * referring to p4est_connectivity_t or p8est_connectivity_t,
-     * depending on template argument.
+     * A structure whose explicit specializations contain typedefs to the
+     * relevant p4est_* and p8est_* types. Using this structure, for example
+     * by saying <code>types@<dim@>::connectivity</code> we can write code in
+     * a dimension independent way, either referring to p4est_connectivity_t
+     * or p8est_connectivity_t, depending on template argument.
      */
     template <int> struct types;
 
@@ -114,8 +113,8 @@ namespace internal
 
 
     /**
-     * Initialize the GeometryInfo<dim>::max_children_per_cell
-     * children of the cell p4est_cell.
+     * Initialize the GeometryInfo<dim>::max_children_per_cell children of the
+     * cell p4est_cell.
      */
     template <int dim>
     void
@@ -168,20 +167,20 @@ namespace parallel
 
     /**
      * This class acts like the dealii::Triangulation class, but it
-     * distributes the mesh across a number of different processors when
-     * using MPI. The class's interface does not add a lot to the
+     * distributes the mesh across a number of different processors when using
+     * MPI. The class's interface does not add a lot to the
      * dealii::Triangulation class but there are a number of difficult
-     * algorithms under the hood that ensure we always have a
-     * load-balanced, fully distributed mesh. Use of this class is
-     * explained in step-40, step-32, the @ref distributed documentation
-     * module, as well as the @ref distributed_paper . See there for more
-     * information. This class satisfies the requirements outlined in
-     * @ref GlossMeshAsAContainer "Meshes as containers".
+     * algorithms under the hood that ensure we always have a load-balanced,
+     * fully distributed mesh. Use of this class is explained in step-40,
+     * step-32, the @ref distributed documentation module, as well as the @ref
+     * distributed_paper . See there for more information. This class
+     * satisfies the requirements outlined in @ref GlossMeshAsAContainer
+     * "Meshes as containers".
      *
-     * @note This class does not support anisotropic refinement, because
-     * it relies on the p4est library that does not support this. Attempts
-     * to refine cells anisotropically will result in errors.
-     * @note There is currently no support for distributing 1d triangulations.
+     * @note This class does not support anisotropic refinement, because it
+     * relies on the p4est library that does not support this. Attempts to
+     * refine cells anisotropically will result in errors. @note There is
+     * currently no support for distributing 1d triangulations.
      *
      *
      * <h3> Interaction with boundary description </h3>
@@ -189,48 +188,51 @@ namespace parallel
      * Refining and coarsening a distributed triangulation is a complicated
      * process because cells may have to be migrated from one processor to
      * another. On a single processor, materializing that part of the global
-     * mesh that we want to store here from what we have stored before therefore
-     * may involve several cycles of refining and coarsening the locally stored
-     * set of cells until we have finally gotten from the previous to the next
-     * triangulation. (This process is described in more detail in the
-     * @ref distributed_paper.) Unfortunately, in this process, some information
-     * can get lost relating to flags that are set by user code and that are
-     * inherited from mother to child cell but that are not moved along with
-     * a cell if that cell is migrated from one processor to another.
+     * mesh that we want to store here from what we have stored before
+     * therefore may involve several cycles of refining and coarsening the
+     * locally stored set of cells until we have finally gotten from the
+     * previous to the next triangulation. (This process is described in more
+     * detail in the @ref distributed_paper.) Unfortunately, in this process,
+     * some information can get lost relating to flags that are set by user
+     * code and that are inherited from mother to child cell but that are not
+     * moved along with a cell if that cell is migrated from one processor to
+     * another.
      *
      * An example are boundary indicators. Assume, for example, that you start
-     * with a single cell that is refined once globally, yielding four children.
-     * If you have four processors, each one owns one cell. Assume now that processor
-     * 1 sets the boundary indicators of the external boundaries of the cell it owns
-     * to 42. Since processor 0 does not own this cell, it doesn't set the boundary
-     * indicators of its ghost cell copy of this cell. Now, assume we do several mesh
-     * refinement cycles and end up with a configuration where this processor suddenly finds itself
-     * as the owner of this cell. If boundary indicator 42 means that we need to
-     * integrate Neumann boundary conditions along this boundary, then processor 0
-     * will forget to do so because it has never set the boundary indicator along
-     * this cell's boundary to 42.
+     * with a single cell that is refined once globally, yielding four
+     * children. If you have four processors, each one owns one cell. Assume
+     * now that processor 1 sets the boundary indicators of the external
+     * boundaries of the cell it owns to 42. Since processor 0 does not own
+     * this cell, it doesn't set the boundary indicators of its ghost cell
+     * copy of this cell. Now, assume we do several mesh refinement cycles and
+     * end up with a configuration where this processor suddenly finds itself
+     * as the owner of this cell. If boundary indicator 42 means that we need
+     * to integrate Neumann boundary conditions along this boundary, then
+     * processor 0 will forget to do so because it has never set the boundary
+     * indicator along this cell's boundary to 42.
      *
      * The way to avoid this dilemma is to make sure that things like setting
-     * boundary indicators or material ids is done immediately
-     * every time a parallel triangulation is refined. This is not necessary
-     * for sequential triangulations because, there, these flags are inherited
-     * from mother to child cell and remain with a cell even if it is refined
-     * and the children are later coarsened again, but this does not hold for
+     * boundary indicators or material ids is done immediately every time a
+     * parallel triangulation is refined. This is not necessary for sequential
+     * triangulations because, there, these flags are inherited from mother to
+     * child cell and remain with a cell even if it is refined and the
+     * children are later coarsened again, but this does not hold for
      * distributed triangulations. It is made even more difficult by the fact
      * that in the process of refining a parallel distributed triangulation,
-     * the triangulation may call dealii::Triangulation::execute_coarsening_and_refinement
-     * multiple times and this function needs to know about boundaries. In
-     * other words, it is <i>not</i> enough to just set boundary indicators on
-     * newly created faces only <i>after</i> calling
-     * distributed::parallel::Triangulation::execute_coarsening_and_refinement:
-     * it actually has to happen while that function is still running.
+     * the triangulation may call
+     * dealii::Triangulation::execute_coarsening_and_refinement multiple times
+     * and this function needs to know about boundaries. In other words, it is
+     * <i>not</i> enough to just set boundary indicators on newly created
+     * faces only <i>after</i> calling distributed::parallel::Triangulation::e
+     * xecute_coarsening_and_refinement: it actually has to happen while that
+     * function is still running.
      *
      * The way to do this is by writing a function that sets boundary
-     * indicators and that will be called by the dealii::Triangulation class. The
-     * triangulation does not provide a pointer to itself to the function being
-     * called, nor any other information, so the trick is to get this information
-     * into the function. C++ provides a nice mechanism for this that is best
-     * explained using an example:
+     * indicators and that will be called by the dealii::Triangulation class.
+     * The triangulation does not provide a pointer to itself to the function
+     * being called, nor any other information, so the trick is to get this
+     * information into the function. C++ provides a nice mechanism for this
+     * that is best explained using an example:
      * @code
      *     #include <deal.II/base/std_cxx11/bind.h>
      *
@@ -254,21 +256,23 @@ namespace parallel
      *     }
      * @endcode
      *
-     * What the call to <code>std_cxx11::bind</code> does is to produce an object that
-     * can be called like a function with no arguments. It does so by taking the
-     * address of a function that does, in fact, take an argument but permanently fix
-     * this one argument to a reference to the coarse grid triangulation. After each
-     * refinement step, the triangulation will then call the object so created which
-     * will in turn call <code>set_boundary_indicators<dim></code> with the reference
-     * to the coarse grid as argument.
+     * What the call to <code>std_cxx11::bind</code> does is to produce an
+     * object that can be called like a function with no arguments. It does so
+     * by taking the address of a function that does, in fact, take an
+     * argument but permanently fix this one argument to a reference to the
+     * coarse grid triangulation. After each refinement step, the
+     * triangulation will then call the object so created which will in turn
+     * call <code>set_boundary_indicators<dim></code> with the reference to
+     * the coarse grid as argument.
      *
-     * This approach can be generalized. In the example above, we have used a global
-     * function that will be called. However, sometimes it is necessary that this
-     * function is in fact a member function of the class that generates the mesh,
-     * for example because it needs to access run-time parameters. This can be
-     * achieved as follows: assuming the <code>set_boundary_indicators()</code>
-     * function has been declared as a (non-static, but possibly private) member
-     * function of the <code>MyClass</code> class, then the following will work:
+     * This approach can be generalized. In the example above, we have used a
+     * global function that will be called. However, sometimes it is necessary
+     * that this function is in fact a member function of the class that
+     * generates the mesh, for example because it needs to access run-time
+     * parameters. This can be achieved as follows: assuming the
+     * <code>set_boundary_indicators()</code> function has been declared as a
+     * (non-static, but possibly private) member function of the
+     * <code>MyClass</code> class, then the following will work:
      * @code
      *     #include <deal.II/base/std_cxx11/bind.h>
      *
@@ -293,21 +297,23 @@ namespace parallel
      *                           std_cxx11::ref(coarse_grid)));
      *     }
      * @endcode
-     * Here, like any other member function, <code>set_boundary_indicators</code>
-     * implicitly takes a pointer or reference to the object it belongs to as first
-     * argument. <code>std::bind</code> again creates an object that can be called like a
-     * global function with no arguments, and this object in turn calls
-     * <code>set_boundary_indicators</code> with a pointer to the current object and a
-     * reference to the triangulation to work on. Note that because the
-     * <code>create_coarse_mesh</code> function is declared as <code>const</code>, it is
-     * necessary that the <code>set_boundary_indicators</code> function is also
-     * declared <code>const</code>.
+     * Here, like any other member function,
+     * <code>set_boundary_indicators</code> implicitly takes a pointer or
+     * reference to the object it belongs to as first argument.
+     * <code>std::bind</code> again creates an object that can be called like
+     * a global function with no arguments, and this object in turn calls
+     * <code>set_boundary_indicators</code> with a pointer to the current
+     * object and a reference to the triangulation to work on. Note that
+     * because the <code>create_coarse_mesh</code> function is declared as
+     * <code>const</code>, it is necessary that the
+     * <code>set_boundary_indicators</code> function is also declared
+     * <code>const</code>.
      *
      * <b>Note:</b>For reasons that have to do with the way the
-     *   parallel::distributed::Triangulation is implemented, functions that
-     *   have been attached to the post-refinement signal of the triangulation are
-     *   called more than once, sometimes several times, every time the triangulation
-     *  is actually refined.
+     * parallel::distributed::Triangulation is implemented, functions that
+     * have been attached to the post-refinement signal of the triangulation
+     * are called more than once, sometimes several times, every time the
+     * triangulation is actually refined.
      *
      *
      * @author Wolfgang Bangerth, Timo Heister 2008, 2009, 2010, 2011
@@ -318,41 +324,38 @@ namespace parallel
     {
     public:
       /**
-       * A typedef that is used to to identify cell iterators. The
-       * concept of iterators is discussed at length in the
-       * @ref Iterators "iterators documentation module".
+       * A typedef that is used to to identify cell iterators. The concept of
+       * iterators is discussed at length in the @ref Iterators "iterators
+       * documentation module".
        *
-       * The current typedef identifies cells in a triangulation. You
-       * can find the exact type it refers to in the base class's own
-       * typedef, but it should be TriaIterator<CellAccessor<dim,spacedim> >. The
-       * TriaIterator class works like a pointer that when you
-       * dereference it yields an object of type CellAccessor.
-       * CellAccessor is a class that identifies properties that
-       * are specific to cells in a triangulation, but it is derived
-       * (and consequently inherits) from TriaAccessor that describes
-       * what you can ask of more general objects (lines, faces, as
-       * well as cells) in a triangulation.
+       * The current typedef identifies cells in a triangulation. You can find
+       * the exact type it refers to in the base class's own typedef, but it
+       * should be TriaIterator<CellAccessor<dim,spacedim> >. The TriaIterator
+       * class works like a pointer that when you dereference it yields an
+       * object of type CellAccessor. CellAccessor is a class that identifies
+       * properties that are specific to cells in a triangulation, but it is
+       * derived (and consequently inherits) from TriaAccessor that describes
+       * what you can ask of more general objects (lines, faces, as well as
+       * cells) in a triangulation.
        *
        * @ingroup Iterators
        */
       typedef typename dealii::Triangulation<dim,spacedim>::cell_iterator        cell_iterator;
 
       /**
-       * A typedef that is used to to identify
-       * @ref GlossActive "active cell iterators". The
-       * concept of iterators is discussed at length in the
+       * A typedef that is used to to identify @ref GlossActive "active cell
+       * iterators". The concept of iterators is discussed at length in the
        * @ref Iterators "iterators documentation module".
        *
        * The current typedef identifies active cells in a triangulation. You
-       * can find the exact type it refers to in the base class's own
-       * typedef, but it should be TriaActiveIterator<CellAccessor<dim,spacedim> >. The
-       * TriaActiveIterator class works like a pointer to active objects that when you
-       * dereference it yields an object of type CellAccessor.
-       * CellAccessor is a class that identifies properties that
-       * are specific to cells in a triangulation, but it is derived
-       * (and consequently inherits) from TriaAccessor that describes
-       * what you can ask of more general objects (lines, faces, as
-       * well as cells) in a triangulation.
+       * can find the exact type it refers to in the base class's own typedef,
+       * but it should be TriaActiveIterator<CellAccessor<dim,spacedim> >. The
+       * TriaActiveIterator class works like a pointer to active objects that
+       * when you dereference it yields an object of type CellAccessor.
+       * CellAccessor is a class that identifies properties that are specific
+       * to cells in a triangulation, but it is derived (and consequently
+       * inherits) from TriaAccessor that describes what you can ask of more
+       * general objects (lines, faces, as well as cells) in a triangulation.
        *
        * @ingroup Iterators
        */
@@ -360,18 +363,17 @@ namespace parallel
 
       /**
        * Generic settings for distributed Triangulations. If
-       * mesh_reconstruction_after_repartitioning is set, the deal.II
-       * mesh will be reconstructed from the coarse mesh every time a
-       * repartioning in p4est happens. This can be a bit more
-       * expensive, but guarantees the same memory layout and
-       * therefore cell ordering in the deal.II mesh. As assembly is
-       * done in the deal.II cell ordering, this flag is required to
-       * get reproducible behaviour after snapshot/resume.
+       * mesh_reconstruction_after_repartitioning is set, the deal.II mesh
+       * will be reconstructed from the coarse mesh every time a repartioning
+       * in p4est happens. This can be a bit more expensive, but guarantees
+       * the same memory layout and therefore cell ordering in the deal.II
+       * mesh. As assembly is done in the deal.II cell ordering, this flag is
+       * required to get reproducible behaviour after snapshot/resume.
        *
-       * The flag construct_multigrid_hierarchy needs to be set to use
-       * the geometric multigrid functionality. This option requires
-       * additional computation and communication. Note: geometric
-       * multigrid is still a work in progress.
+       * The flag construct_multigrid_hierarchy needs to be set to use the
+       * geometric multigrid functionality. This option requires additional
+       * computation and communication. Note: geometric multigrid is still a
+       * work in progress.
        */
       enum Settings
       {
@@ -385,33 +387,30 @@ namespace parallel
       /**
        * Constructor.
        *
-       * @param mpi_communicator denotes the MPI communicator to be
-       * used for the triangulation.
+       * @param mpi_communicator denotes the MPI communicator to be used for
+       * the triangulation.
        *
-       * @param smooth_grid Degree and kind of mesh smoothing to be
-       * applied to the mesh. See the dealii::Triangulation class for
-       * a description of the kinds of smoothing operations that can
-       * be applied.
+       * @param smooth_grid Degree and kind of mesh smoothing to be applied to
+       * the mesh. See the dealii::Triangulation class for a description of
+       * the kinds of smoothing operations that can be applied.
        *
-       * @param settings See the description of the Settings
-       * enumerator.
+       * @param settings See the description of the Settings enumerator.
        *
        * @note This class does not currently support the
-       * <code>check_for_distorted_cells</code> argument provided by
-       * the base class.
+       * <code>check_for_distorted_cells</code> argument provided by the base
+       * class.
        *
-       * @note While it is possible to pass all of the mesh smoothing
-       * flags listed in the base class to objects of this type, it is
-       * not always possible to honor all of these smoothing options
-       * if they would require knowledge of refinement/coarsening
-       * flags on cells not locally owned by this processor. As a
-       * consequence, for some of these flags, the ultimate number of
-       * cells of the parallel triangulation may depend on the number
-       * of processors into which it is partitioned. On the other
-       * hand, if no smoothing flags are passed, if you always mark
-       * the same cells of the mesh, you will always get the exact
-       * same refined mesh independent of the number of processors
-       * into which the triangulation is partitioned.
+       * @note While it is possible to pass all of the mesh smoothing flags
+       * listed in the base class to objects of this type, it is not always
+       * possible to honor all of these smoothing options if they would
+       * require knowledge of refinement/coarsening flags on cells not locally
+       * owned by this processor. As a consequence, for some of these flags,
+       * the ultimate number of cells of the parallel triangulation may depend
+       * on the number of processors into which it is partitioned. On the
+       * other hand, if no smoothing flags are passed, if you always mark the
+       * same cells of the mesh, you will always get the exact same refined
+       * mesh independent of the number of processors into which the
+       * triangulation is partitioned.
        */
       Triangulation (MPI_Comm mpi_communicator,
                      const typename dealii::Triangulation<dim,spacedim>::MeshSmoothing
@@ -424,12 +423,10 @@ namespace parallel
       virtual ~Triangulation ();
 
       /**
-       * Reset this triangulation into a virgin state by deleting all
-       * data.
+       * Reset this triangulation into a virgin state by deleting all data.
        *
-       * Note that this operation is only allowed if no subscriptions
-       * to this object exist any more, such as DoFHandler objects
-       * using it.
+       * Note that this operation is only allowed if no subscriptions to this
+       * object exist any more, such as DoFHandler objects using it.
        */
       virtual void clear ();
 
@@ -441,128 +438,125 @@ namespace parallel
       /**
        * Create a triangulation as documented in the base class.
        *
-       * This function also sets up the various data structures
-       * necessary to distribute a mesh across a number of
-       * processors. This will be necessary once the mesh is being
-       * refined, though we will always keep the entire coarse mesh
-       * that is generated by this function on all processors.
+       * This function also sets up the various data structures necessary to
+       * distribute a mesh across a number of processors. This will be
+       * necessary once the mesh is being refined, though we will always keep
+       * the entire coarse mesh that is generated by this function on all
+       * processors.
        */
       virtual void create_triangulation (const std::vector<Point<spacedim> >    &vertices,
                                          const std::vector<CellData<dim> > &cells,
                                          const SubCellData                 &subcelldata);
 
       /**
-       * Coarsen and refine the mesh according to refinement and
-       * coarsening flags set.
+       * Coarsen and refine the mesh according to refinement and coarsening
+       * flags set.
        *
-       * Since the current processor only has control over those cells
-       * it owns (i.e. the ones for which <code>cell-@>subdomain_id() ==
-       * this-@>locally_owned_subdomain()</code>), refinement and
-       * coarsening flags are only respected for those locally owned
-       * cells. Flags may be set on other cells as well (and may
-       * often, in fact, if you call
-       * dealii::Triangulation::prepare_coarsening_and_refinement) but
-       * will be largely ignored: the decision to refine the global
-       * mesh will only be affected by flags set on locally owned
-       * cells.
+       * Since the current processor only has control over those cells it owns
+       * (i.e. the ones for which <code>cell-@>subdomain_id() ==
+       * this-@>locally_owned_subdomain()</code>), refinement and coarsening
+       * flags are only respected for those locally owned cells. Flags may be
+       * set on other cells as well (and may often, in fact, if you call
+       * dealii::Triangulation::prepare_coarsening_and_refinement) but will be
+       * largely ignored: the decision to refine the global mesh will only be
+       * affected by flags set on locally owned cells.
        */
       virtual void execute_coarsening_and_refinement ();
 
       /**
-       * When vertices have been moved locally, for example using code
-       * like
+       * When vertices have been moved locally, for example using code like
        * @code
        *   cell->vertex(0) = new_location;
        * @endcode
-       * then this function can be used to update the location of
-       * vertices between MPI processes.
+       * then this function can be used to update the location of vertices
+       * between MPI processes.
        *
        * All the vertices that have been moved and might be in the ghost layer
-       * of a process have to be reported in the @p vertex_locally_moved argument.
-       * This ensures that that part of the information that has to be send
-       * between processes is actually sent. Additionally, it is quite important that vertices
-       * on the boundary between processes are reported on exactly one process
-       * (e.g. the one with the highest id). Otherwise we could expect
-       * undesirable results if multiple processes move a vertex differently.
-       * A typical strategy is to let processor $i$ move those vertices that
-       * are adjacent to cells whose owners include processor $i$ but no
-       * other processor $j$ with $j<i$; in other words, for vertices
-       * at the boundary of a subdomain, the processor with the lowest subdomain
-       * id "owns" a vertex.
+       * of a process have to be reported in the @p vertex_locally_moved
+       * argument. This ensures that that part of the information that has to
+       * be send between processes is actually sent. Additionally, it is quite
+       * important that vertices on the boundary between processes are
+       * reported on exactly one process (e.g. the one with the highest id).
+       * Otherwise we could expect undesirable results if multiple processes
+       * move a vertex differently. A typical strategy is to let processor $i$
+       * move those vertices that are adjacent to cells whose owners include
+       * processor $i$ but no other processor $j$ with $j<i$; in other words,
+       * for vertices at the boundary of a subdomain, the processor with the
+       * lowest subdomain id "owns" a vertex.
        *
-       * @note It only makes sense to move vertices that are either located
-       * on locally owned cells or on cells in the ghost layer. This is
-       * because you can be sure that these vertices indeed exist on the
-       * finest mesh aggregated over all processors, whereas vertices on
-       * artificial cells but not at least in the ghost layer may or may
-       * not exist on the globally finest mesh. Consequently, the
-       * @p vertex_locally_moved argument may not contain vertices that
-       * aren't at least on ghost cells.
+       * @note It only makes sense to move vertices that are either located on
+       * locally owned cells or on cells in the ghost layer. This is because
+       * you can be sure that these vertices indeed exist on the finest mesh
+       * aggregated over all processors, whereas vertices on artificial cells
+       * but not at least in the ghost layer may or may not exist on the
+       * globally finest mesh. Consequently, the @p vertex_locally_moved
+       * argument may not contain vertices that aren't at least on ghost
+       * cells.
        *
-       * @note This function moves vertices in such a way that on every processor,
-       * the vertices of every locally owned and ghost cell is consistent with
-       * the corresponding location of these cells on other processors. On the
-       * other hand, the locations of artificial cells will in general be wrong
-       * since artificial cells may or may not exist on other processors
-       * and consequently it is not possible to determine their location
-       * in any way. This is not usually a problem since one never does anything
-       * on artificial cells. However, it may lead to problems if the mesh
-       * with moved vertices is refined in a later step. If that's what you
-       * want to do, the right way to do it is to save the offset applied to
-       * every vertex, call this function, and before refining or coarsening
-       * the mesh apply the opposite offset and call this function again.
+       * @note This function moves vertices in such a way that on every
+       * processor, the vertices of every locally owned and ghost cell is
+       * consistent with the corresponding location of these cells on other
+       * processors. On the other hand, the locations of artificial cells will
+       * in general be wrong since artificial cells may or may not exist on
+       * other processors and consequently it is not possible to determine
+       * their location in any way. This is not usually a problem since one
+       * never does anything on artificial cells. However, it may lead to
+       * problems if the mesh with moved vertices is refined in a later step.
+       * If that's what you want to do, the right way to do it is to save the
+       * offset applied to every vertex, call this function, and before
+       * refining or coarsening the mesh apply the opposite offset and call
+       * this function again.
        *
        * @param vertex_locally_moved A bitmap indicating which vertices have
-       *   been moved. The size of this array must be equal to
-       *   Triangulation::n_vertices() and must be a subset of those vertices
-       *   flagged by GridTools::get_locally_owned_vertices().
+       * been moved. The size of this array must be equal to
+       * Triangulation::n_vertices() and must be a subset of those vertices
+       * flagged by GridTools::get_locally_owned_vertices().
        *
-       * @see This function is used, for example, in GridTools::distort_random().
+       * @see This function is used, for example, in
+       * GridTools::distort_random().
        */
       void
       communicate_locally_moved_vertices (const std::vector<bool> &vertex_locally_moved);
 
       /**
-       * Return the subdomain id of those cells that are owned by the
-       * current processor. All cells in the triangulation that do not
-       * have this subdomain id are either owned by another processor
-       * or have children that only exist on other processors.
+       * Return the subdomain id of those cells that are owned by the current
+       * processor. All cells in the triangulation that do not have this
+       * subdomain id are either owned by another processor or have children
+       * that only exist on other processors.
        */
       types::subdomain_id locally_owned_subdomain () const;
 
       /**
-       * Return the number of active cells in the triangulation that
-       * are locally owned, i.e. that have a subdomain_id equal to
-       * locally_owned_subdomain(). Note that there may be more active
-       * cells in the triangulation stored on the present processor,
-       * such as for example ghost cells, or cells further away from
-       * the locally owned block of cells but that are needed to
-       * ensure that the triangulation that stores this processor's
-       * set of active cells still remains balanced with respect to
-       * the 2:1 size ratio of adjacent cells.
+       * Return the number of active cells in the triangulation that are
+       * locally owned, i.e. that have a subdomain_id equal to
+       * locally_owned_subdomain(). Note that there may be more active cells
+       * in the triangulation stored on the present processor, such as for
+       * example ghost cells, or cells further away from the locally owned
+       * block of cells but that are needed to ensure that the triangulation
+       * that stores this processor's set of active cells still remains
+       * balanced with respect to the 2:1 size ratio of adjacent cells.
        *
-       * As a consequence of the remark above, the result of this
-       * function is always smaller or equal to the result of the
-       * function with the same name in the ::Triangulation base
-       * class, which includes the active ghost and artificial cells
-       * (see also @ref GlossArtificialCell and @ref GlossGhostCell).
+       * As a consequence of the remark above, the result of this function is
+       * always smaller or equal to the result of the function with the same
+       * name in the ::Triangulation base class, which includes the active
+       * ghost and artificial cells (see also @ref GlossArtificialCell and
+       * @ref GlossGhostCell).
        */
       unsigned int n_locally_owned_active_cells () const;
 
       /**
-       * Return the sum over all processors of the number of active
-       * cells owned by each processor. This equals the overall number
-       * of active cells in the distributed triangulation.
+       * Return the sum over all processors of the number of active cells
+       * owned by each processor. This equals the overall number of active
+       * cells in the distributed triangulation.
        */
       virtual types::global_dof_index n_global_active_cells () const;
 
       /**
-       * Returns the global maximum level. This may be bigger than
-       * the number dealii::Triangulation::n_levels() (a function in this
-       * class's base class) returns if the current processor only stores
-       * cells in parts of the domain that are not very refined, but
-       * if other processors store cells in more deeply refined parts of
-       * the domain.
+       * Returns the global maximum level. This may be bigger than the number
+       * dealii::Triangulation::n_levels() (a function in this class's base
+       * class) returns if the current processor only stores cells in parts of
+       * the domain that are not very refined, but if other processors store
+       * cells in more deeply refined parts of the domain.
        */
       virtual unsigned int n_global_levels () const;
 
@@ -570,26 +564,24 @@ namespace parallel
        * Returns true if the triangulation has hanging nodes.
        *
        * In the context of parallel distributed triangulations, every
-       * processor stores only that part of the triangulation it
-       * locally owns. However, it also stores the entire coarse
-       * mesh, and to guarantee the 2:1 relationship between cells,
-       * this may mean that there are hanging nodes between cells that
-       * are not locally owned or ghost cells (i.e., between ghost cells
-       * and artificial cells, or between artificial and artificial cells;
-       * see @ref GlossArtificialCell "the glossary").
-       * One is not typically interested in this case, so the function
-       * returns whether there are hanging nodes between any two cells
-       * of the "global" mesh, i.e., the union of locally owned cells
-       * on all processors.
+       * processor stores only that part of the triangulation it locally owns.
+       * However, it also stores the entire coarse mesh, and to guarantee the
+       * 2:1 relationship between cells, this may mean that there are hanging
+       * nodes between cells that are not locally owned or ghost cells (i.e.,
+       * between ghost cells and artificial cells, or between artificial and
+       * artificial cells; see @ref GlossArtificialCell "the glossary"). One
+       * is not typically interested in this case, so the function returns
+       * whether there are hanging nodes between any two cells of the "global"
+       * mesh, i.e., the union of locally owned cells on all processors.
        */
       virtual
       bool has_hanging_nodes() const;
 
       /**
-       * Return the number of active cells owned by each of the MPI
-       * processes that contribute to this triangulation. The element
-       * of this vector indexed by locally_owned_subdomain() equals
-       * the result of n_locally_owned_active_cells().
+       * Return the number of active cells owned by each of the MPI processes
+       * that contribute to this triangulation. The element of this vector
+       * indexed by locally_owned_subdomain() equals the result of
+       * n_locally_owned_active_cells().
        */
       const std::vector<unsigned int> &
       n_locally_owned_active_cells_per_processor () const;
@@ -605,73 +597,69 @@ namespace parallel
       virtual std::size_t memory_consumption () const;
 
       /**
-       * Return the local memory consumption contained in the p4est
-       * data structures alone. This is already contained in
-       * memory_consumption() but made available separately for
-       * debugging purposes.
+       * Return the local memory consumption contained in the p4est data
+       * structures alone. This is already contained in memory_consumption()
+       * but made available separately for debugging purposes.
        */
       virtual std::size_t memory_consumption_p4est () const;
 
       /**
-       * A collective operation that produces a sequence of output
-       * files with the given file base name that contain the mesh in
-       * VTK format.
+       * A collective operation that produces a sequence of output files with
+       * the given file base name that contain the mesh in VTK format.
        *
-       * More than anything else, this function is useful for
-       * debugging the interface between deal.II and p4est.
+       * More than anything else, this function is useful for debugging the
+       * interface between deal.II and p4est.
        */
       void write_mesh_vtk (const char *file_basename) const;
 
       /**
-       * Produce a check sum of the triangulation.  This is a
-       * collective operation and is mostly useful for debugging
-       * purposes.
+       * Produce a check sum of the triangulation.  This is a collective
+       * operation and is mostly useful for debugging purposes.
        */
       unsigned int get_checksum () const;
 
       /**
        * Save the refinement information from the coarse mesh into the given
-       * file. This file needs to be reachable from all nodes in the computation
-       * on a shared network file system. See the SolutionTransfer class
-       * on how to store solution vectors into this file. Additional cell-based data can be saved
-       * using register_data_attach().
+       * file. This file needs to be reachable from all nodes in the
+       * computation on a shared network file system. See the SolutionTransfer
+       * class on how to store solution vectors into this file. Additional
+       * cell-based data can be saved using register_data_attach().
        */
       void save(const char *filename) const;
 
       /**
-       * Load the refinement information saved with save() back in. The
-       * mesh must contain the same coarse mesh that was used in save()
-       * before calling this function.
+       * Load the refinement information saved with save() back in. The mesh
+       * must contain the same coarse mesh that was used in save() before
+       * calling this function.
        *
        * You do not need to load with the same number of MPI processes that
-       * you saved with. Rather, if a mesh is loaded with a different
-       * number of MPI processes than used at the time of saving, the mesh
-       * is repartitioned appropriately. Cell-based data that was saved
-       * with register_data_attach() can be read in with
-       * notify_ready_to_unpack() after calling load().
+       * you saved with. Rather, if a mesh is loaded with a different number
+       * of MPI processes than used at the time of saving, the mesh is
+       * repartitioned appropriately. Cell-based data that was saved with
+       * register_data_attach() can be read in with notify_ready_to_unpack()
+       * after calling load().
        *
        * If you use p4est version > 0.3.4.2 the @p autopartition flag tells
-       * p4est to ignore the partitioning that the triangulation had when
-       * it was saved and make it uniform upon loading. If @p autopartition
-       * is set to false, the triangulation is only repartitioned if needed
-       * (i.e. if a different number of MPI processes is encountered).
+       * p4est to ignore the partitioning that the triangulation had when it
+       * was saved and make it uniform upon loading. If @p autopartition is
+       * set to false, the triangulation is only repartitioned if needed (i.e.
+       * if a different number of MPI processes is encountered).
        */
       void load(const char *filename,
                 const bool autopartition = true);
 
       /**
        * Used to inform in the callbacks of register_data_attach() and
-       * notify_ready_to_unpack() how the cell with the given
-       * cell_iterator is going to change.  Note that this may me
-       * different than the refine_flag() and coarsen_flag() in the
-       * cell_iterator because of refinement constraints that this
-       * machine does not see.
+       * notify_ready_to_unpack() how the cell with the given cell_iterator is
+       * going to change.  Note that this may me different than the
+       * refine_flag() and coarsen_flag() in the cell_iterator because of
+       * refinement constraints that this machine does not see.
        */
       enum CellStatus
       {
         /**
-         * The cell will not be refined or coarsened and might or might
-         * not move to a different processor.
+         * The cell will not be refined or coarsened and might or might not
+         * move to a different processor.
          */
         CELL_PERSIST,
         /**
@@ -689,19 +677,18 @@ namespace parallel
       };
 
       /**
-       * Register a function with the current Triangulation object
-       * that will be used to attach data to active cells before
+       * Register a function with the current Triangulation object that will
+       * be used to attach data to active cells before
        * execute_coarsening_and_refinement(). In
-       * execute_coarsening_and_refinement() the Triangulation will
-       * call the given function pointer and provide @p size bytes to
-       * store data. If necessary, this data will be transferred to
-       * the new owner of that cell during repartitioning the
-       * tree. See notify_ready_to_unpack() on how to retrieve the
-       * data.
+       * execute_coarsening_and_refinement() the Triangulation will call the
+       * given function pointer and provide @p size bytes to store data. If
+       * necessary, this data will be transferred to the new owner of that
+       * cell during repartitioning the tree. See notify_ready_to_unpack() on
+       * how to retrieve the data.
        *
-       * Callers need to store the return value.  It specifies an
-       * offset of the position at which data can later be retrieved
-       * during a call to notify_ready_to_unpack().
+       * Callers need to store the return value.  It specifies an offset of
+       * the position at which data can later be retrieved during a call to
+       * notify_ready_to_unpack().
        *
        * The CellStatus argument in the callback function will tell you if the
        * given cell will be coarsened, refined, or will persist as is (this
@@ -709,11 +696,10 @@ namespace parallel
        * is
        *
        * - CELL_PERIST: the cell won't be refined/coarsened, but might be
-       *   moved to a different processor
-       * - CELL_REFINE: this cell will be refined into 4/8 cells, you can not
-       *   access the children (because they don't exist yet)
-       * - CELL_COARSEN: the children of this cell will be coarsened into the
-       *   given cell (you can access the active children!)
+       * moved to a different processor - CELL_REFINE: this cell will be
+       * refined into 4/8 cells, you can not access the children (because they
+       * don't exist yet) - CELL_COARSEN: the children of this cell will be
+       * coarsened into the given cell (you can access the active children!)
        *
        * When unpacking the data with notify_ready_to_unpack() you can access
        * the children of the cell if the status is CELL_REFINE but not for
@@ -739,10 +725,10 @@ namespace parallel
        * The CellStatus will indicate if the cell was refined, coarsened, or
        * persisted unchanged. The cell_iterator will either by an active,
        * locally owned cell (if the cell was not refined), or the immediate
-       * parent if it was refined during
-       * execute_coarsening_and_refinement(). Therefore, contrary to during
-       * register_data_attach(), you can now access the children if the status
-       * is CELL_REFINE but no longer for callbacks with status CELL_COARSEN.
+       * parent if it was refined during execute_coarsening_and_refinement().
+       * Therefore, contrary to during register_data_attach(), you can now
+       * access the children if the status is CELL_REFINE but no longer for
+       * callbacks with status CELL_COARSEN.
        */
       void
       notify_ready_to_unpack (const unsigned int offset,
@@ -751,27 +737,26 @@ namespace parallel
                                                               const void *)> &unpack_callback);
 
       /**
-       * Return a permutation vector for the order the coarse cells
-       * are handed off to p4est. For example the value of the $i$th element
-       * in this vector is the index of the deal.II coarse cell (counting
-       * from begin(0)) that corresponds to the $i$th tree managed by p4est.
+       * Return a permutation vector for the order the coarse cells are handed
+       * off to p4est. For example the value of the $i$th element in this
+       * vector is the index of the deal.II coarse cell (counting from
+       * begin(0)) that corresponds to the $i$th tree managed by p4est.
        */
       const std::vector<types::global_dof_index> &
       get_p4est_tree_to_coarse_cell_permutation() const;
 
       /**
-       * Return a permutation vector for the mapping from the
-       * coarse deal cells to the p4est trees. This is the inverse
-       * of get_p4est_tree_to_coarse_cell_permutation.
+       * Return a permutation vector for the mapping from the coarse deal
+       * cells to the p4est trees. This is the inverse of
+       * get_p4est_tree_to_coarse_cell_permutation.
        */
       const std::vector<types::global_dof_index> &
       get_coarse_cell_to_p4est_tree_permutation() const;
 
       /**
-       * Join faces in the p4est forest for periodic boundary
-       * conditions. As a result, each pair of faces will differ by at
-       * most one refinement level and ghost neighbors will be
-       * available across these faces.
+       * Join faces in the p4est forest for periodic boundary conditions. As a
+       * result, each pair of faces will differ by at most one refinement
+       * level and ghost neighbors will be available across these faces.
        *
        * The vector can be filled by the function
        * GridTools::collect_periodic_faces.
@@ -779,10 +764,9 @@ namespace parallel
        * @todo At the moment just default orientation is implemented.
        *
        * @note Before this function can be used the Triangulation has to be
-       * initialized and must not be refined.
-       * Calling this function more than once is possible, but not recommended:
-       * The function destroys and rebuilds the p4est forest each time it is
-       * called.
+       * initialized and must not be refined. Calling this function more than
+       * once is possible, but not recommended: The function destroys and
+       * rebuilds the p4est forest each time it is called.
        */
       void
       add_periodicity
@@ -792,9 +776,9 @@ namespace parallel
 
     private:
       /**
-       * MPI communicator to be used for the triangulation. We create
-       * a unique communicator for this class, which is a duplicate of
-       * the one passed to the constructor.
+       * MPI communicator to be used for the triangulation. We create a unique
+       * communicator for this class, which is a duplicate of the one passed
+       * to the constructor.
        */
       MPI_Comm mpi_communicator;
 
@@ -809,8 +793,7 @@ namespace parallel
       types::subdomain_id my_subdomain;
 
       /**
-       * A flag that indicates whether the triangulation has actual
-       * content.
+       * A flag that indicates whether the triangulation has actual content.
        */
       bool triangulation_has_content;
 
@@ -830,10 +813,9 @@ namespace parallel
       NumberCache number_cache;
 
       /**
-       * A data structure that holds the connectivity between
-       * trees. Since each tree is rooted in a coarse grid cell, this
-       * data structure holds the connectivity between the cells of
-       * the coarse grid.
+       * A data structure that holds the connectivity between trees. Since
+       * each tree is rooted in a coarse grid cell, this data structure holds
+       * the connectivity between the cells of the coarse grid.
        */
       typename dealii::internal::p4est::types<dim>::connectivity *connectivity;
 
@@ -843,41 +825,39 @@ namespace parallel
        */
       typename dealii::internal::p4est::types<dim>::forest *parallel_forest;
       /**
-       * A data structure that holds some information about the ghost
-       * cells of the triangulation.
+       * A data structure that holds some information about the ghost cells of
+       * the triangulation.
        */
       typename dealii::internal::p4est::types<dim>::ghost  *parallel_ghost;
 
       /**
-       * A flag that indicates whether refinement of a triangulation
-       * is currently in progress. This flag is used to disambiguate
-       * whether a call to execute_coarsening_and_triangulation came
-       * from the outside or through a recursive call. While the first
-       * time we want to take over work to copy things from a refined
-       * p4est, the other times we don't want to get in the way as
-       * these latter calls to
-       * Triangulation::execute_coarsening_and_refinement() are simply
-       * there in order to re-create a triangulation that matches the
-       * p4est.
+       * A flag that indicates whether refinement of a triangulation is
+       * currently in progress. This flag is used to disambiguate whether a
+       * call to execute_coarsening_and_triangulation came from the outside or
+       * through a recursive call. While the first time we want to take over
+       * work to copy things from a refined p4est, the other times we don't
+       * want to get in the way as these latter calls to
+       * Triangulation::execute_coarsening_and_refinement() are simply there
+       * in order to re-create a triangulation that matches the p4est.
        */
       bool refinement_in_progress;
 
 
       /**
-       * number of bytes that get attached to the Triangulation
-       * through register_data_attach() for example SolutionTransfer.
+       * number of bytes that get attached to the Triangulation through
+       * register_data_attach() for example SolutionTransfer.
        */
       unsigned int attached_data_size;
 
       /**
-       * number of functions that get attached to the Triangulation
-       * through register_data_attach() for example SolutionTransfer.
+       * number of functions that get attached to the Triangulation through
+       * register_data_attach() for example SolutionTransfer.
        */
       unsigned int n_attached_datas;
 
       /**
-       * number of functions that need to unpack their data after a
-       * call from load()
+       * number of functions that need to unpack their data after a call from
+       * load()
        */
       unsigned int n_attached_deserialize;
 
@@ -890,25 +870,22 @@ namespace parallel
       typedef std::list<callback_pair_t> callback_list_t;
 
       /**
-       * List of callback functions registered by
-       * register_data_attach() that are going to be called for
-       * packing data.
+       * List of callback functions registered by register_data_attach() that
+       * are going to be called for packing data.
        */
       callback_list_t attached_data_pack_callbacks;
 
 
       /**
-       * Two arrays that store which p4est tree corresponds to which
-       * coarse grid cell and vice versa. We need these arrays because
-       * p4est goes with the original order of coarse cells when it
-       * sets up its forest, and then applies the Morton ordering
-       * within each tree. But if coarse grid cells are badly ordered
-       * this may mean that individual parts of the forest stored on a
-       * local machine may be split across coarse grid cells that are
-       * not geometrically close. Consequently, we apply a
-       * Cuthill-McKee preordering to ensure that the part of the
-       * forest stored by p4est is located on geometrically close
-       * coarse grid cells.
+       * Two arrays that store which p4est tree corresponds to which coarse
+       * grid cell and vice versa. We need these arrays because p4est goes
+       * with the original order of coarse cells when it sets up its forest,
+       * and then applies the Morton ordering within each tree. But if coarse
+       * grid cells are badly ordered this may mean that individual parts of
+       * the forest stored on a local machine may be split across coarse grid
+       * cells that are not geometrically close. Consequently, we apply a
+       * Cuthill-McKee preordering to ensure that the part of the forest
+       * stored by p4est is located on geometrically close coarse grid cells.
        */
       std::vector<types::global_dof_index> coarse_cell_to_p4est_tree_permutation;
       std::vector<types::global_dof_index> p4est_tree_to_coarse_cell_permutation;
@@ -921,14 +898,14 @@ namespace parallel
       init_tree(const int dealii_coarse_cell_index) const;
 
       /**
-       * The function that computes the permutation between the two
-       * data storage schemes.
+       * The function that computes the permutation between the two data
+       * storage schemes.
        */
       void setup_coarse_cell_to_p4est_tree_permutation ();
 
       /**
-       * Take the contents of a newly created triangulation we are
-       * attached to and copy it to p4est data structures.
+       * Take the contents of a newly created triangulation we are attached to
+       * and copy it to p4est data structures.
        *
        * This function exists in 2d and 3d variants.
        */
@@ -943,14 +920,13 @@ namespace parallel
 
 
       /**
-       * Update the number_cache variable after mesh creation or
-       * refinement.
+       * Update the number_cache variable after mesh creation or refinement.
        */
       void update_number_cache ();
 
       /**
-       * Internal function notifying all registered classes to attach
-       * their data before repartitioning occurs. Called from
+       * Internal function notifying all registered classes to attach their
+       * data before repartitioning occurs. Called from
        * execute_coarsening_and_refinement().
        */
       void attach_mesh_data();
@@ -970,18 +946,17 @@ namespace parallel
 
 
     /**
-     * Specialization of the general template for the 1d case. There
-     * is currently no support for distributing 1d
-     * triangulations. Consequently, all this class does is throw an
-     * exception.
+     * Specialization of the general template for the 1d case. There is
+     * currently no support for distributing 1d triangulations. Consequently,
+     * all this class does is throw an exception.
      */
     template <int spacedim>
     class Triangulation<1,spacedim> : public dealii::Triangulation<1,spacedim>
     {
     public:
       /**
-       * Constructor. The argument denotes the MPI communicator to be
-       * used for the triangulation.
+       * Constructor. The argument denotes the MPI communicator to be used for
+       * the triangulation.
        */
       Triangulation (MPI_Comm mpi_communicator);
 
@@ -996,69 +971,69 @@ namespace parallel
       MPI_Comm get_communicator () const;
 
       /**
-       * Return the sum over all processors of the number of active
-       * cells owned by each processor. This equals the overall number
-       * of active cells in the distributed triangulation.
+       * Return the sum over all processors of the number of active cells
+       * owned by each processor. This equals the overall number of active
+       * cells in the distributed triangulation.
        */
       types::global_dof_index n_global_active_cells () const;
       virtual unsigned int n_global_levels () const;
 
       /**
-       * Returns a permutation vector for the order the coarse cells
-       * are handed of to p4est. For example the first element i in
-       * this vector denotes that the first cell in hierarchical
-       * ordering is the ith deal cell starting from begin(0).
+       * Returns a permutation vector for the order the coarse cells are
+       * handed of to p4est. For example the first element i in this vector
+       * denotes that the first cell in hierarchical ordering is the ith deal
+       * cell starting from begin(0).
        */
       const std::vector<types::global_dof_index> &
       get_p4est_tree_to_coarse_cell_permutation() const;
 
       /**
-       * When vertices have been moved locally, for example using code
-       * like
+       * When vertices have been moved locally, for example using code like
        * @code
        *   cell->vertex(0) = new_location;
        * @endcode
-       * then this function can be used to update the location of
-       * vertices between MPI processes.
+       * then this function can be used to update the location of vertices
+       * between MPI processes.
        *
        * All the vertices that have been moved and might be in the ghost layer
-       * of a process have to be reported in the @p vertex_locally_moved argument.
-       * This ensures that that part of the information that has to be send
-       * between processes is actually sent. Additionally, it is quite important that vertices
-       * on the boundary between processes are reported on exactly one process
-       * (e.g. the one with the highest id). Otherwise we could expect
-       * undesirable results if multiple processes move a vertex differently.
-       * A typical strategy is to let processor $i$ move those vertices that
-       * are adjacent to cells whose owners include processor $i$ but no
-       * other processor $j$ with $j<i$; in other words, for vertices
-       * at the boundary of a subdomain, the processor with the lowest subdomain
-       * id "owns" a vertex.
+       * of a process have to be reported in the @p vertex_locally_moved
+       * argument. This ensures that that part of the information that has to
+       * be send between processes is actually sent. Additionally, it is quite
+       * important that vertices on the boundary between processes are
+       * reported on exactly one process (e.g. the one with the highest id).
+       * Otherwise we could expect undesirable results if multiple processes
+       * move a vertex differently. A typical strategy is to let processor $i$
+       * move those vertices that are adjacent to cells whose owners include
+       * processor $i$ but no other processor $j$ with $j<i$; in other words,
+       * for vertices at the boundary of a subdomain, the processor with the
+       * lowest subdomain id "owns" a vertex.
        *
-       * @note It only makes sense to move vertices that are either located
-       * on locally owned cells or on cells in the ghost layer. This is
-       * because you can be sure that these vertices indeed exist on the
-       * finest mesh aggregated over all processors, whereas vertices on
-       * artificial cells but not at least in the ghost layer may or may
-       * not exist on the globally finest mesh. Consequently, the
-       * @p vertex_locally_moved argument may not contain vertices that
-       * aren't at least on ghost cells.
+       * @note It only makes sense to move vertices that are either located on
+       * locally owned cells or on cells in the ghost layer. This is because
+       * you can be sure that these vertices indeed exist on the finest mesh
+       * aggregated over all processors, whereas vertices on artificial cells
+       * but not at least in the ghost layer may or may not exist on the
+       * globally finest mesh. Consequently, the @p vertex_locally_moved
+       * argument may not contain vertices that aren't at least on ghost
+       * cells.
        *
-       * @see This function is used, for example, in GridTools::distort_random().
+       * @see This function is used, for example, in
+       * GridTools::distort_random().
        */
       void
       communicate_locally_moved_vertices (const std::vector<bool> &vertex_locally_moved);
 
       /**
-       * Return the subdomain id of those cells that are owned by the
-       * current processor. All cells in the triangulation that do not
-       * have this subdomain id are either owned by another processor
-       * or have children that only exist on other processors.
+       * Return the subdomain id of those cells that are owned by the current
+       * processor. All cells in the triangulation that do not have this
+       * subdomain id are either owned by another processor or have children
+       * that only exist on other processors.
        */
       types::subdomain_id locally_owned_subdomain () const;
 
       /**
-       * Dummy arrays. This class isn't usable but the compiler wants
-       * to see these variables at a couple places anyway.
+       * Dummy arrays. This class isn't usable but the compiler wants to see
+       * these variables at a couple places anyway.
        */
       std::vector<types::global_dof_index> coarse_cell_to_p4est_tree_permutation;
       std::vector<types::global_dof_index> p4est_tree_to_coarse_cell_permutation;
@@ -1102,13 +1077,13 @@ namespace parallel
   {
     /**
      * Dummy class the compiler chooses for parallel distributed
-     * triangulations if we didn't actually configure deal.II with the
-     * p4est library. The existence of this class allows us to refer
-     * to parallel::distributed::Triangulation objects throughout the
-     * library even if it is disabled.
+     * triangulations if we didn't actually configure deal.II with the p4est
+     * library. The existence of this class allows us to refer to
+     * parallel::distributed::Triangulation objects throughout the library
+     * even if it is disabled.
      *
-     * Since the constructor of this class is private, no such objects
-     * can actually be created if we don't have p4est available.
+     * Since the constructor of this class is private, no such objects can
+     * actually be created if we don't have p4est available.
      */
     template <int dim, int spacedim = dim>
     class Triangulation : public dealii::Triangulation<dim,spacedim>
@@ -1127,10 +1102,10 @@ namespace parallel
       virtual ~Triangulation ();
 
       /**
-       * Return the subdomain id of those cells that are owned by the
-       * current processor. All cells in the triangulation that do not
-       * have this subdomain id are either owned by another processor
-       * or have children that only exist on other processors.
+       * Return the subdomain id of those cells that are owned by the current
+       * processor. All cells in the triangulation that do not have this
+       * subdomain id are either owned by another processor or have children
+       * that only exist on other processors.
        */
       types::subdomain_id locally_owned_subdomain () const;
 
index 33acaacd74cb3c23de7ea496bd3bf2ddfb6c76d0..4a85c1ce6b3b46ee0674d61f67a7844967f1c92d 100644 (file)
@@ -37,51 +37,46 @@ namespace hp
  * @brief A small class collecting the different BlockIndices involved in
  * global, multilevel and local computations.
  *
- * Once a DoFHandler has been initialized with an FESystem, a data
- * object of type BlockInfo (accessed by DoFHandler::block_info() ) is
- * filled, which reflects the block structure of the degrees of
- * freedom.
+ * Once a DoFHandler has been initialized with an FESystem, a data object of
+ * type BlockInfo (accessed by DoFHandler::block_info() ) is filled, which
+ * reflects the block structure of the degrees of freedom.
  *
- * BlockInfo consists of several BlockIndices objects. The member
- * global() reflects the block structure of the system on the active
- * cell level, usually referred to as the global system. As soon as
+ * BlockInfo consists of several BlockIndices objects. The member global()
+ * reflects the block structure of the system on the active cell level,
+ * usually referred to as the global system. As soon as
  * DoFHandler::distribute_dofs() has been called, the function
- * BlockIndices::block_size() in global() will return the correct
- * sizes of each block. After DoFRenumbering::block_wise(),
- * BlockIndices::block_start() will return the start index for each of
- * the blocks.
+ * BlockIndices::block_size() in global() will return the correct sizes of
+ * each block. After DoFRenumbering::block_wise(), BlockIndices::block_start()
+ * will return the start index for each of the blocks.
  *
  * When a DoFHandler with levels is used, the same structure is automatically
- * generated for each level. The level blocks can be accessed through
- * level().
+ * generated for each level. The level blocks can be accessed through level().
  *
- * Finally, there are local() BlockIndices, which describe the block
- * structure on a single cell. This is used for instance by
- * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local
- * indices are not filled automatically, since they change the
- * behavior of the MeshWorker::Assembler classes relying on
- * BlockInfo. They must be initialized by hand through initialize_local().
+ * Finally, there are local() BlockIndices, which describe the block structure
+ * on a single cell. This is used for instance by
+ * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local indices
+ * are not filled automatically, since they change the behavior of the
+ * MeshWorker::Assembler classes relying on BlockInfo. They must be
+ * initialized by hand through initialize_local().
  *
  * <h3>Usage</h3>
  *
- * The most common usage for this object is initializing vectors as in
- * the following code:
+ * The most common usage for this object is initializing vectors as in the
+ * following code:
  *
- * <code>
- * MGDofHandler<dim> dof_handler(triangulation);
+ * <code> MGDofHandler<dim> dof_handler(triangulation);
  * dof_handler.distribute_dofs(fesystem);
  * DoFRenumbering::block_wise(dof_handler);
  *
  * BlockVector<double> solution(dof_handler.block_info().global());
  *
- * MGLevelObject<BlockVector<double> > mg_vector(0, triangulation.n_levels()-1);
- * for (unsigned int i=0;i<triangulation.n_levels();++i)
- *   mg_vector[i].reinit(dof_handler.block_info().level(i));
- *</code>
- * In this example, <tt>solution</tt> obtains the block structure needed to
- * represent a finite element function on the DoFHandler. Similarly,
- * all levels of <tt>mg_vector</tt> will have the block structure
- * needed on that level.
+ * MGLevelObject<BlockVector<double> > mg_vector(0,
+ * triangulation.n_levels()-1); for (unsigned int
+ * i=0;i<triangulation.n_levels();++i)
+ * mg_vector[i].reinit(dof_handler.block_info().level(i)); </code> In this
+ * example, <tt>solution</tt> obtains the block structure needed to represent
+ * a finite element function on the DoFHandler. Similarly, all levels of
+ * <tt>mg_vector</tt> will have the block structure needed on that level.
  *
  * @todo Extend the functions local() and renumber() to the concept to
  * hpDoFHandler.
@@ -93,73 +88,50 @@ class BlockInfo : public Subscriptor
 {
 public:
   /**
-   * @brief Fill the object with values
-   * describing block structure
-   * of the DoFHandler.
+   * @brief Fill the object with values describing block structure of the
+   * DoFHandler.
    *
-  * By default, this function will
-  * attempt to initialize whatever
-  * is possible. If active dofs
-  * have been assigned int the
-  * DoFHandler argument, they
-  * BlockIndices for those will be
-  * generated. The same for level
-  * dofs.
-  *
-  * This default behavior can be
-  * overridden by the two
-  * parameters, which can switch
-  * off active dofs or level dofs.
-  *
-   * This function will also clear
-   * the local() indices.
+   * By default, this function will attempt to initialize whatever is
+   * possible. If active dofs have been assigned int the DoFHandler argument,
+   * they BlockIndices for those will be generated. The same for level dofs.
+   *
+   * This default behavior can be overridden by the two parameters, which can
+   * switch off active dofs or level dofs.
+   *
+   * This function will also clear the local() indices.
    */
   template <int dim, int spacedim>
   void initialize(const DoFHandler<dim, spacedim> &, bool levels_only = false, bool active_only = false);
 
   /**
-   * @brief Initialize block structure
-   * on cells and compute
-   * renumbering between cell
-   * dofs and block cell dofs.
+   * @brief Initialize block structure on cells and compute renumbering
+   * between cell dofs and block cell dofs.
    */
   template <int dim, int spacedim>
   void initialize_local(const DoFHandler<dim, spacedim> &);
 
   /**
-   * Access the BlockIndices
-   * structure of the global
-   * system.
+   * Access the BlockIndices structure of the global system.
    */
   const BlockIndices &global() const;
 
   /**
-   * Access BlockIndices for the
-   * local system on a cell.
+   * Access BlockIndices for the local system on a cell.
    */
   const BlockIndices &local() const;
 
   /**
-   * Access the BlockIndices
-   * structure of a level in the
-   * multilevel hierarchy.
+   * Access the BlockIndices structure of a level in the multilevel hierarchy.
    */
   const BlockIndices &level(unsigned int level) const;
 
   /**
-   * Return the index after local
-   * renumbering.
+   * Return the index after local renumbering.
    *
-   * The input of this function is
-   * an index between zero and the
-   * number of dofs per cell,
-   * numbered in local block
-   * ordering, that is first all
-   * indices of the first system
-   * block, then all of the second
-   * block and so forth. The
-   * function then outputs the index
-   * in the standard local
+   * The input of this function is an index between zero and the number of
+   * dofs per cell, numbered in local block ordering, that is first all
+   * indices of the first system block, then all of the second block and so
+   * forth. The function then outputs the index in the standard local
    * numbering of DoFAccessor.
    */
   types::global_dof_index renumber (const unsigned int i) const;
@@ -170,29 +142,26 @@ public:
   unsigned int n_base_elements() const;
 
   /**
-   * Return the base element of
-   * this index.
+   * Return the base element of this index.
    */
   unsigned int base_element (const unsigned int i) const;
 
   /**
-   * Write a summary of the block
-   * structure to the stream.
+   * Write a summary of the block structure to the stream.
    */
   template <class OS>
   void
   print(OS &stream) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-   * Read or write the data of this object to or
-   * from a stream for the purpose of serialization
+   * Read or write the data of this object to or from a stream for the purpose
+   * of serialization
    */
   template <class Archive>
   void serialize (Archive &ar,
@@ -200,8 +169,7 @@ public:
 
 private:
   /**
-   * @brief The block structure
-   * of the global system.
+   * @brief The block structure of the global system.
    */
   BlockIndices bi_global;
   /**
@@ -210,25 +178,18 @@ private:
   std::vector<BlockIndices> levels;
 
   /**
-   * @brief The block structure
-   * of the cell systems.
+   * @brief The block structure of the cell systems.
    */
   BlockIndices bi_local;
 
   /**
-   * The base element associated
-   * with each block.
+   * The base element associated with each block.
    */
   std::vector<unsigned int> base_elements;
 
   /**
-   * A vector containing the
-   * renumbering from the
-   * standard order of degrees of
-   * freedom on a cell to a
-   * component wise
-   * ordering. Filled by
-   * initialize().
+   * A vector containing the renumbering from the standard order of degrees of
+   * freedom on a cell to a component wise ordering. Filled by initialize().
    */
   std::vector<types::global_dof_index> local_renumbering;
 };
index b993a906e3ac319ed074a86813c8669809db151b..abd63aca1c6a1e944a7e159f839368accba25e86 100644 (file)
@@ -74,15 +74,15 @@ namespace internal
     /**
      * This is a switch class which only declares a @p typedef. It is meant to
      * determine which class a DoFAccessor class is to be derived from. By
-     * default, <tt>DoFAccessor@<structdim,dim,spacedim@></tt> derives from the
-     * typedef in the general
+     * default, <tt>DoFAccessor@<structdim,dim,spacedim@></tt> derives from
+     * the typedef in the general
      * <tt>Inheritance@<structdim,dim,spacedim@></tt> class, which is
      * <tt>TriaAccessor@<structdim,dim,spacedim@></tt>, but if
      * <tt>structdim==dim</tt>, then the specialization
-     * <tt>Inheritance@<dim,dim,spacedim@></tt> is used which declares
-     * its local type to be <tt>CellAccessor@<dim,spacedim@></tt>. Therefore, the
-     * inheritance is automatically chosen to be from CellAccessor if the object
-     * under consideration has full dimension, i.e. constitutes a cell.
+     * <tt>Inheritance@<dim,dim,spacedim@></tt> is used which declares its
+     * local type to be <tt>CellAccessor@<dim,spacedim@></tt>. Therefore, the
+     * inheritance is automatically chosen to be from CellAccessor if the
+     * object under consideration has full dimension, i.e. constitutes a cell.
      *
      * @ingroup dofs
      * @ingroup Accessors
@@ -92,24 +92,24 @@ namespace internal
     struct Inheritance
     {
       /**
-       * Declaration of the @p typedef.  See the full documentation
-       * for more information.
+       * Declaration of the @p typedef.  See the full documentation for more
+       * information.
        */
       typedef dealii::TriaAccessor<structdim,dim,spacedim> BaseClass;
     };
 
 
     /**
-     * This is the specialization of the general template used for the case where
-     * an object has full dimension, i.e. is a cell. See the general template for
-     * more details.
+     * This is the specialization of the general template used for the case
+     * where an object has full dimension, i.e. is a cell. See the general
+     * template for more details.
      */
     template <int dim, int spacedim>
     struct Inheritance<dim,dim,spacedim>
     {
       /**
-       * Declaration of the @p typedef.  See the full documentation
-       * for more information.
+       * Declaration of the @p typedef.  See the full documentation for more
+       * information.
        */
       typedef dealii::CellAccessor<dim,spacedim> BaseClass;
     };
@@ -123,64 +123,62 @@ namespace internal
 
 /**
  * A class that gives access to the degrees of freedom stored in a DoFHandler,
- * MGSoDHandler, or hp::DoFHandler object. Accessors are used to, access the data that
- * pertains to edges, faces, and cells of a triangulation. The concept is
- * explained in more detail in connection to @ref Iterators.
+ * MGSoDHandler, or hp::DoFHandler object. Accessors are used to, access the
+ * data that pertains to edges, faces, and cells of a triangulation. The
+ * concept is explained in more detail in connection to @ref Iterators.
  *
- * This class follows mainly the route laid out by the accessor
- * library declared in the triangulation library (TriaAccessor). It
- * enables the user to access the degrees of freedom on lines, quads,
- * or hexes. The first template argument of this class determines the
- * dimensionality of the object under consideration: 1 for lines, 2
- * for quads, and 3 for hexes. The second argument denotes the type of
- * DoF handler we should work on. It can either be ::DoFHandler or
- * hp::DoFHandler.  From the second template argument we also deduce
- * the dimension of the Triangulation this object refers to as well as
- * the dimension of the space into which it is embedded. Finally, the
- * template argument <code>level_dof_access</code> governs the
- * behavior of the function get_active_or_mg_dof_indices(). See the section on Generic loops below.
+ * This class follows mainly the route laid out by the accessor library
+ * declared in the triangulation library (TriaAccessor). It enables the user
+ * to access the degrees of freedom on lines, quads, or hexes. The first
+ * template argument of this class determines the dimensionality of the object
+ * under consideration: 1 for lines, 2 for quads, and 3 for hexes. The second
+ * argument denotes the type of DoF handler we should work on. It can either
+ * be ::DoFHandler or hp::DoFHandler.  From the second template argument we
+ * also deduce the dimension of the Triangulation this object refers to as
+ * well as the dimension of the space into which it is embedded. Finally, the
+ * template argument <code>level_dof_access</code> governs the behavior of the
+ * function get_active_or_mg_dof_indices(). See the section on Generic loops
+ * below.
  *
  * <h3>Typedefs</h3>
  *
- * Usage is best to happen through the typedefs to the various kinds
- * of iterators provided by the DoFHandler and hp::DoFHandler classes,
- * since they are more secure to changes in the class naming and
- * template interface as well as providing easier typing (much less
- * complicated names!).
+ * Usage is best to happen through the typedefs to the various kinds of
+ * iterators provided by the DoFHandler and hp::DoFHandler classes, since they
+ * are more secure to changes in the class naming and template interface as
+ * well as providing easier typing (much less complicated names!).
  *
  * <h3>Generic loops and the third template argument</h3>
  *
- * Many loops look very similar, whether they operate on the active
- * dofs of the active cells of the Triangulation or on the level dodfs
- * of a single level or the whole grid hierarchy. In order to use
- * polymorphism in such loops, they access degrees of freedom through
- * the function get_active_or_mg_dof_indices(), which changes behavior according to the
- * third template argument.  If the argument is false, then the active
- * dofs of active cells are accessed. If it is true, the level dofs
- * are used. DoFHandler has functions, for instance begin() and
- * begin_mg(), which return either type or the other. Additionally,
- * they can be cast into each other, in case this is needed, since
- * they access the same data.
+ * Many loops look very similar, whether they operate on the active dofs of
+ * the active cells of the Triangulation or on the level dodfs of a single
+ * level or the whole grid hierarchy. In order to use polymorphism in such
+ * loops, they access degrees of freedom through the function
+ * get_active_or_mg_dof_indices(), which changes behavior according to the
+ * third template argument.  If the argument is false, then the active dofs of
+ * active cells are accessed. If it is true, the level dofs are used.
+ * DoFHandler has functions, for instance begin() and begin_mg(), which return
+ * either type or the other. Additionally, they can be cast into each other,
+ * in case this is needed, since they access the same data.
  *
- * It is highly recommended to use the function get_active_or_mg_dof_indices() in
- * generic loops in lieu of get_dof_indices() or get_mg_dof_indices().
+ * It is highly recommended to use the function get_active_or_mg_dof_indices()
+ * in generic loops in lieu of get_dof_indices() or get_mg_dof_indices().
  *
  * <h3>Inheritance</h3>
  *
- * If the structural dimension given by the first template argument
- * equals the dimension of the DoFHandler (given as the second
- * template argument), then we are obviously dealing with cells,
- * rather than lower-dimensional objects. In that case, inheritance is
- * from CellAccessor, to provide access to all the cell specific
- * information afforded by that class. Otherwise, i.e. for
+ * If the structural dimension given by the first template argument equals the
+ * dimension of the DoFHandler (given as the second template argument), then
+ * we are obviously dealing with cells, rather than lower-dimensional objects.
+ * In that case, inheritance is from CellAccessor, to provide access to all
+ * the cell specific information afforded by that class. Otherwise, i.e. for
  * lower-dimensional objects, inheritance is from TriaAccessor.
  *
- * There is a DoFCellAccessor class that provides the
- * equivalent to the CellAccessor class.
+ * There is a DoFCellAccessor class that provides the equivalent to the
+ * CellAccessor class.
  *
  * @ingroup dofs
  * @ingroup Accessors
- * @author Wolfgang Bangerth, 1998, 2006, 2008, Timo Heister, Guido Kanschat, 2012, 2013
+ * @author Wolfgang Bangerth, 1998, 2006, 2008, Timo Heister, Guido Kanschat,
+ * 2012, 2013
  */
 template <int structdim, class DH, bool level_dof_access>
 class DoFAccessor : public dealii::internal::DoFAccessor::Inheritance<structdim, DH::dimension, DH::space_dimension>::BaseClass
@@ -188,14 +186,14 @@ class DoFAccessor : public dealii::internal::DoFAccessor::Inheritance<structdim,
 public:
 
   /**
-   * A static variable that allows users of this class to discover the
-   * value of the second template argument.
+   * A static variable that allows users of this class to discover the value
+   * of the second template argument.
    */
   static const unsigned int dimension=DH::dimension;
 
   /**
-   * A static variable that allows users of this class to discover the
-   * value of the third template argument.
+   * A static variable that allows users of this class to discover the value
+   * of the third template argument.
    */
   static const unsigned int space_dimension=DH::space_dimension;
 
@@ -234,29 +232,28 @@ public:
 
   /**
    * Conversion constructor. This constructor exists to make certain
-   * constructs simpler to write in dimension independent code. For
-   * example, it allows assigning a face iterator to a line iterator,
-   * an operation that is useful in 2d but doesn't make any sense in
-   * 3d. The constructor here exists for the purpose of making the
-   * code conform to C++ but it will unconditionally abort; in other
-   * words, assigning a face iterator to a line iterator is better put
-   * into an if-statement that checks that the dimension is two, and
-   * assign to a quad iterator in 3d (an operator that, without this
-   * constructor would be illegal if we happen to compile for 2d).
+   * constructs simpler to write in dimension independent code. For example,
+   * it allows assigning a face iterator to a line iterator, an operation that
+   * is useful in 2d but doesn't make any sense in 3d. The constructor here
+   * exists for the purpose of making the code conform to C++ but it will
+   * unconditionally abort; in other words, assigning a face iterator to a
+   * line iterator is better put into an if-statement that checks that the
+   * dimension is two, and assign to a quad iterator in 3d (an operator that,
+   * without this constructor would be illegal if we happen to compile for
+   * 2d).
    */
   template <int structdim2, int dim2, int spacedim2>
   DoFAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Another conversion operator between objects that don't make
-   * sense, just like the previous one.
+   * Another conversion operator between objects that don't make sense, just
+   * like the previous one.
    */
   template <int dim2, class DH2, bool level_dof_access2>
   DoFAccessor (const DoFAccessor<dim2, DH2, level_dof_access2> &);
 
   /**
-   * Copy constructor allowing to switch level access and active
-   * access.
+   * Copy constructor allowing to switch level access and active access.
    */
   template <bool level_dof_access2>
   DoFAccessor(const DoFAccessor<structdim, DH, level_dof_access2> &);
@@ -277,20 +274,19 @@ public:
   void copy_from (const DoFAccessor<structdim, DH, level_dof_access2> &a);
 
   /**
-   * Copy operator used by the iterator class. Keeps the previously
-   * set dof handler, but sets the object coordinates of the
-   * TriaAccessor.
+   * Copy operator used by the iterator class. Keeps the previously set dof
+   * handler, but sets the object coordinates of the TriaAccessor.
    */
   void copy_from (const TriaAccessorBase<structdim, DH::dimension, DH::space_dimension> &da);
 
   /**
-   * Tell the caller whether get_active_or_mg_dof_indices() accesses
-   * active or level dofs.
+   * Tell the caller whether get_active_or_mg_dof_indices() accesses active or
+   * level dofs.
    */
   static bool is_level_cell();
 
   /**
-   *  @name Accessing sub-objects
+   * @name Accessing sub-objects
    */
   /**
    * @{
@@ -303,17 +299,17 @@ public:
   child (const unsigned int c) const;
 
   /**
-   * Pointer to the @p ith line bounding this object. If the current
-   * object is a line itself, then the only valid index is @p i equals
-   * to zero, and the function returns an iterator to itself.
+   * Pointer to the @p ith line bounding this object. If the current object is
+   * a line itself, then the only valid index is @p i equals to zero, and the
+   * function returns an iterator to itself.
    */
   typename dealii::internal::DoFHandler::Iterators<DH, level_dof_access>::line_iterator
   line (const unsigned int i) const;
 
   /**
-   * Pointer to the @p ith quad bounding this object. If the current
-   * object is a quad itself, then the only valid index is @p i equals
-   * to zero, and the function returns an iterator to itself.
+   * Pointer to the @p ith quad bounding this object. If the current object is
+   * a quad itself, then the only valid index is @p i equals to zero, and the
+   * function returns an iterator to itself.
    */
   typename dealii::internal::DoFHandler::Iterators<DH, level_dof_access>::quad_iterator
   quad (const unsigned int i) const;
@@ -323,7 +319,7 @@ public:
    */
 
   /**
-   *  @name Accessing the DoF indices of this object
+   * @name Accessing the DoF indices of this object
    */
   /**
    * @{
@@ -336,33 +332,29 @@ public:
    * etc, dofs on quad 0, etc.) This function is only available on
    * <i>active</i> objects (see @ref GlossActive "this glossary entry").
    *
-   * The cells needs to be an active cell (and not artificial in a
-   * parallel distributed computation).
+   * The cells needs to be an active cell (and not artificial in a parallel
+   * distributed computation).
    *
    * The vector has to have the right size before being passed to this
    * function.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
-   *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
-   *
-   * For cells, there is only a single possible finite element index
-   * (namely the one for that cell, returned by
-   * <code>cell-@>active_fe_index</code>. Consequently, the derived
-   * DoFCellAccessor class has an overloaded version of this function
-   * that calls the present function with
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
+   *
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
+   *
+   * For cells, there is only a single possible finite element index (namely
+   * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
+   * Consequently, the derived DoFCellAccessor class has an overloaded version
+   * of this function that calls the present function with
    * <code>cell-@>active_fe_index</code> as last argument.
    *
    */
@@ -387,33 +379,30 @@ public:
                            const unsigned int fe_index = DH::default_fe_index);
 
   /**
-   * Global DoF index of the <i>i</i> degree associated with the @p
-   * vertexth vertex of the present cell.
+   * Global DoF index of the <i>i</i> degree associated with the @p vertexth
+   * vertex of the present cell.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   types::global_dof_index vertex_dof_index (const unsigned int vertex,
                                             const unsigned int i,
                                             const unsigned int fe_index = DH::default_fe_index) const;
 
   /**
-   * Returns the global DoF index of the <code>i</code>th degree of
-   * freedom associated with the <code>vertex</code>th vertex on level
-   * @p level. Also see vertex_dof_index().
+   * Returns the global DoF index of the <code>i</code>th degree of freedom
+   * associated with the <code>vertex</code>th vertex on level @p level. Also
+   * see vertex_dof_index().
    */
   types::global_dof_index mg_vertex_dof_index (const int level,
                                                const unsigned int vertex,
@@ -423,32 +412,29 @@ public:
   /**
    * Index of the <i>i</i>th degree of freedom of this object.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
-   *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
-   *
-   * @note While the get_dof_indices() function returns an array that
-   * contains the indices of all degrees of freedom that somehow live
-   * on this object (i.e. on the vertices, edges or interior of this
-   * object), the current dof_index() function only considers the DoFs
-   * that really belong to this particular object's interior. In other
-   * words, as an example, if the current object refers to a quad (a
-   * cell in 2d, a face in 3d) and the finite element associated with
-   * it is a bilinear one, then the get_dof_indices() will return an
-   * array of size 4 while dof_index() will produce an exception
-   * because no degrees are defined in the interior of the face.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
+   *
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
+   *
+   * @note While the get_dof_indices() function returns an array that contains
+   * the indices of all degrees of freedom that somehow live on this object
+   * (i.e. on the vertices, edges or interior of this object), the current
+   * dof_index() function only considers the DoFs that really belong to this
+   * particular object's interior. In other words, as an example, if the
+   * current object refers to a quad (a cell in 2d, a face in 3d) and the
+   * finite element associated with it is a bilinear one, then the
+   * get_dof_indices() will return an array of size 4 while dof_index() will
+   * produce an exception because no degrees are defined in the interior of
+   * the face.
    */
   types::global_dof_index dof_index (const unsigned int i,
                                      const unsigned int fe_index = DH::default_fe_index) const;
@@ -463,53 +449,50 @@ public:
    */
 
   /**
-   *  @name Accessing the finite element associated with this object
+   * @name Accessing the finite element associated with this object
    */
   /**
    * @{
    */
 
   /**
-   * Return the number of finite elements that are active on a given
-   * object.
+   * Return the number of finite elements that are active on a given object.
    *
-   * For non-hp DoFHandler objects, the answer is of course always
-   * one. However, for hp::DoFHandler objects, this isn't the case: If
-   * this is a cell, the answer is of course one. If it is a face, the
-   * answer may be one or two, depending on whether the two adjacent
-   * cells use the same finite element or not. If it is an edge in 3d,
-   * the possible return value may be one or any other value larger
-   * than that.
+   * For non-hp DoFHandler objects, the answer is of course always one.
+   * However, for hp::DoFHandler objects, this isn't the case: If this is a
+   * cell, the answer is of course one. If it is a face, the answer may be one
+   * or two, depending on whether the two adjacent cells use the same finite
+   * element or not. If it is an edge in 3d, the possible return value may be
+   * one or any other value larger than that.
    */
   unsigned int
   n_active_fe_indices () const;
 
   /**
-   * Return the @p n-th active fe index on this object. For cells and
-   * all non-hp objects, there is only a single active fe index, so
-   * the argument must be equal to zero. For lower-dimensional hp
-   * objects, there are n_active_fe_indices() active finite elements,
-   * and this function can be queried for their indices.
+   * Return the @p n-th active fe index on this object. For cells and all non-
+   * hp objects, there is only a single active fe index, so the argument must
+   * be equal to zero. For lower-dimensional hp objects, there are
+   * n_active_fe_indices() active finite elements, and this function can be
+   * queried for their indices.
    */
   unsigned int
   nth_active_fe_index (const unsigned int n) const;
 
   /**
-   * Return true if the finite element with given index is active on
-   * the present object. For non-hp DoF accessors, this is of course
-   * the case only if @p fe_index equals zero. For cells, it is the
-   * case if @p fe_index equals active_fe_index() of this cell. For
-   * faces and other lower-dimensional objects, there may be more than
-   * one @p fe_index that are active on any given object (see
-   * n_active_fe_indices()).
+   * Return true if the finite element with given index is active on the
+   * present object. For non-hp DoF accessors, this is of course the case only
+   * if @p fe_index equals zero. For cells, it is the case if @p fe_index
+   * equals active_fe_index() of this cell. For faces and other lower-
+   * dimensional objects, there may be more than one @p fe_index that are
+   * active on any given object (see n_active_fe_indices()).
    */
   bool
   fe_index_is_active (const unsigned int fe_index) const;
 
   /**
-   * Return a reference to the finite element used on this object with
-   * the given @p fe_index. @p fe_index must be used on this object,
-   * i.e. <code>fe_index_is_active(fe_index)</code> must return true.
+   * Return a reference to the finite element used on this object with the
+   * given @p fe_index. @p fe_index must be used on this object, i.e.
+   * <code>fe_index_is_active(fe_index)</code> must return true.
    */
   const FiniteElement<DH::dimension,DH::space_dimension> &
   get_fe (const unsigned int fe_index) const;
@@ -543,9 +526,8 @@ public:
    */
   DeclException0 (ExcMatrixDoesNotMatch);
   /**
-   * A function has been called for
-   * a cell which should be active,
-   * but is refined. @ref GlossActive
+   * A function has been called for a cell which should be active, but is
+   * refined. @ref GlossActive
    *
    * @ingroup Exceptions
    */
@@ -560,24 +542,22 @@ public:
 protected:
 
   /**
-   * Store the address of the DoFHandler object
-   * to be accessed.
+   * Store the address of the DoFHandler object to be accessed.
    */
   DH *dof_handler;
 public:
   /**
-   * Compare for equality. Return <tt>true</tt> if the two accessors
-   * refer to the same object.
+   * Compare for equality. Return <tt>true</tt> if the two accessors refer to
+   * the same object.
    *
-   * The template parameters of this function allow for a comparison
-   * of very different objects. Therefore, some of them are disabled.
-   * Namely, if the dimension, or the dof handler of the two objects
-   * differ, an exception is generated. It can be expected that this
-   * is an unwanted comparison.
+   * The template parameters of this function allow for a comparison of very
+   * different objects. Therefore, some of them are disabled. Namely, if the
+   * dimension, or the dof handler of the two objects differ, an exception is
+   * generated. It can be expected that this is an unwanted comparison.
    *
-   * The template parameter <tt>level_dof_access2</tt> is ignored,
-   * such that an iterator with level access can be equal to one with
-   * access to the active degrees of freedom.
+   * The template parameter <tt>level_dof_access2</tt> is ignored, such that
+   * an iterator with level access can be equal to one with access to the
+   * active degrees of freedom.
    */
   template <int dim2, class DH2, bool level_dof_access2>
   bool operator == (const DoFAccessor<dim2,DH2,level_dof_access2> &) const;
@@ -594,24 +574,21 @@ protected:
   void set_dof_handler (DH *dh);
 
   /**
-   * Set the index of the <i>i</i>th degree of freedom of this object
-   * to @p index.
+   * Set the index of the <i>i</i>th degree of freedom of this object to @p
+   * index.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   void set_dof_index (const unsigned int i,
                       const types::global_dof_index index,
@@ -620,24 +597,21 @@ protected:
   void set_mg_dof_index (const int level, const unsigned int i, const types::global_dof_index index) const;
 
   /**
-   * Set the global index of the <i>i</i> degree on the @p vertex-th
-   * vertex of the present cell to @p index.
+   * Set the global index of the <i>i</i> degree on the @p vertex-th vertex of
+   * the present cell to @p index.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   void set_vertex_dof_index (const unsigned int vertex,
                              const unsigned int i,
@@ -655,22 +629,21 @@ protected:
 
 private:
   /**
-   *  Copy operator. This is normally used in a context like
-   *  <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to
-   *  copy the object pointed to by @p b to the object pointed to by
-   *  @p a. However, the result of dereferencing an iterator is not an
-   *  object but an accessor; consequently, this operation is not
-   *  useful for iterators on triangulations. We declare this function
-   *  here private, thus it may not be used from outside.  Furthermore
-   *  it is not implemented and will give a linker error if used
-   *  anyway.
+   * Copy operator. This is normally used in a context like <tt>iterator a,b;
+   * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+   * by @p b to the object pointed to by @p a. However, the result of
+   * dereferencing an iterator is not an object but an accessor; consequently,
+   * this operation is not useful for iterators on triangulations. We declare
+   * this function here private, thus it may not be used from outside.
+   * Furthermore it is not implemented and will give a linker error if used
+   * anyway.
    */
   DoFAccessor<structdim,DH, level_dof_access> &
   operator = (const DoFAccessor<structdim,DH, level_dof_access> &da);
 
   /**
-   * Make the DoFHandler class a friend so that it can call the
-   * set_xxx() functions.
+   * Make the DoFHandler class a friend so that it can call the set_xxx()
+   * functions.
    */
   template <int dim, int spacedim> friend class DoFHandler;
   template <int dim, int spacedim> friend class hp::DoFHandler;
@@ -685,12 +658,11 @@ private:
 
 
 /**
- * Specialization of the general DoFAccessor class template for the
- * case of zero-dimensional objects (a vertex) that are the face of a
- * one-dimensional cell in spacedim space dimensions. Since vertices
- * function differently than general faces, this class does a few
- * things differently than the general template, but the interface
- * should look the same.
+ * Specialization of the general DoFAccessor class template for the case of
+ * zero-dimensional objects (a vertex) that are the face of a one-dimensional
+ * cell in spacedim space dimensions. Since vertices function differently than
+ * general faces, this class does a few things differently than the general
+ * template, but the interface should look the same.
  *
  * @author Wolfgang Bangerth, 2010
  */
@@ -700,14 +672,14 @@ class DoFAccessor<0,DH<1,spacedim>, level_dof_access> : public TriaAccessor<0,1,
 public:
 
   /**
-   * A static variable that allows users of this class to discover the
-   * value of the second template argument.
+   * A static variable that allows users of this class to discover the value
+   * of the second template argument.
    */
   static const unsigned int dimension=1;
 
   /**
-   * A static variable that allows users of this class to discover the
-   * value of the third template argument.
+   * A static variable that allows users of this class to discover the value
+   * of the third template argument.
    */
   static const unsigned int space_dimension=spacedim;
 
@@ -735,22 +707,20 @@ public:
   DoFAccessor ();
 
   /**
-   * Constructor to be used if the object here refers to a vertex of a
-   * one-dimensional triangulation, i.e. a face of the triangulation.
+   * Constructor to be used if the object here refers to a vertex of a one-
+   * dimensional triangulation, i.e. a face of the triangulation.
    *
-   * Since there is no mapping from vertices to cells, an accessor
-   * object for a point has no way to figure out whether it is at the
-   * boundary of the domain or not. Consequently, the second argument
-   * must be passed by the object that generates this accessor --
-   * e.g. a 1d cell that can figure out whether its left or right
-   * vertex are at the boundary.
+   * Since there is no mapping from vertices to cells, an accessor object for
+   * a point has no way to figure out whether it is at the boundary of the
+   * domain or not. Consequently, the second argument must be passed by the
+   * object that generates this accessor -- e.g. a 1d cell that can figure out
+   * whether its left or right vertex are at the boundary.
    *
    * The third argument is the global index of the vertex we point to.
    *
    * The fourth argument is a pointer to the DoFHandler object.
    *
-   * This iterator can only be called for one-dimensional
-   * triangulations.
+   * This iterator can only be called for one-dimensional triangulations.
    */
   DoFAccessor (const Triangulation<1,spacedim> *tria,
                const typename TriaAccessor<0,1,spacedim>::VertexKind vertex_kind,
@@ -758,10 +728,9 @@ public:
                const DH<1,spacedim> *dof_handler);
 
   /**
-   * Constructor. This constructor exists in order to maintain
-   * interface compatibility with the other accessor classes. However,
-   * it doesn't do anything useful here and so may not actually be
-   * called.
+   * Constructor. This constructor exists in order to maintain interface
+   * compatibility with the other accessor classes. However, it doesn't do
+   * anything useful here and so may not actually be called.
    */
   DoFAccessor (const Triangulation<1,spacedim> *,
                const int = 0,
@@ -770,22 +739,22 @@ public:
 
   /**
    * Conversion constructor. This constructor exists to make certain
-   * constructs simpler to write in dimension independent code. For
-   * example, it allows assigning a face iterator to a line iterator,
-   * an operation that is useful in 2d but doesn't make any sense in
-   * 3d. The constructor here exists for the purpose of making the
-   * code conform to C++ but it will unconditionally abort; in other
-   * words, assigning a face iterator to a line iterator is better put
-   * into an if-statement that checks that the dimension is two, and
-   * assign to a quad iterator in 3d (an operator that, without this
-   * constructor would be illegal if we happen to compile for 2d).
+   * constructs simpler to write in dimension independent code. For example,
+   * it allows assigning a face iterator to a line iterator, an operation that
+   * is useful in 2d but doesn't make any sense in 3d. The constructor here
+   * exists for the purpose of making the code conform to C++ but it will
+   * unconditionally abort; in other words, assigning a face iterator to a
+   * line iterator is better put into an if-statement that checks that the
+   * dimension is two, and assign to a quad iterator in 3d (an operator that,
+   * without this constructor would be illegal if we happen to compile for
+   * 2d).
    */
   template <int structdim2, int dim2, int spacedim2>
   DoFAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Another conversion operator between objects that don't make
-   * sense, just like the previous one.
+   * Another conversion operator between objects that don't make sense, just
+   * like the previous one.
    */
   template <int dim2, class DH2, bool level_dof_access2>
   DoFAccessor (const DoFAccessor<dim2, DH2, level_dof_access2> &);
@@ -813,14 +782,13 @@ public:
   void copy_from (const DoFAccessor<0, DH<1,spacedim>, level_dof_access2> &a);
 
   /**
-   * Copy operator used by the iterator class. Keeps the previously
-   * set dof handler, but sets the object coordinates of the
-   * TriaAccessor.
+   * Copy operator used by the iterator class. Keeps the previously set dof
+   * handler, but sets the object coordinates of the TriaAccessor.
    */
   void copy_from (const TriaAccessorBase<0, 1, spacedim> &da);
 
   /**
-   *  @name Accessing sub-objects
+   * @name Accessing sub-objects
    */
   /**
    * @{
@@ -833,17 +801,17 @@ public:
   child (const unsigned int c) const;
 
   /**
-   * Pointer to the @p ith line bounding this object. If the current
-   * object is a line itself, then the only valid index is @p i equals
-   * to zero, and the function returns an iterator to itself.
+   * Pointer to the @p ith line bounding this object. If the current object is
+   * a line itself, then the only valid index is @p i equals to zero, and the
+   * function returns an iterator to itself.
    */
   typename dealii::internal::DoFHandler::Iterators<DH<1,spacedim>, level_dof_access>::line_iterator
   line (const unsigned int i) const;
 
   /**
-   * Pointer to the @p ith quad bounding this object. If the current
-   * object is a quad itself, then the only valid index is @p i equals
-   * to zero, and the function returns an iterator to itself.
+   * Pointer to the @p ith quad bounding this object. If the current object is
+   * a quad itself, then the only valid index is @p i equals to zero, and the
+   * function returns an iterator to itself.
    */
   typename dealii::internal::DoFHandler::Iterators<DH<1,spacedim>, level_dof_access>::quad_iterator
   quad (const unsigned int i) const;
@@ -853,71 +821,63 @@ public:
    */
 
   /**
-   *  @name Accessing the DoF indices of this object
+   * @name Accessing the DoF indices of this object
    */
   /**
    * @{
    */
 
   /**
-   * Return the <i>global</i> indices of the degrees of freedom
-   * located on this object in the standard ordering defined by the
-   * finite element (i.e., dofs on vertex 0, dofs on vertex 1, etc,
-   * dofs on line 0, dofs on line 1, etc, dofs on quad 0, etc.) This
-   * function is only available on <i>active</i> objects (see @ref
-   * GlossActive "this glossary entry").
+   * Return the <i>global</i> indices of the degrees of freedom located on
+   * this object in the standard ordering defined by the finite element (i.e.,
+   * dofs on vertex 0, dofs on vertex 1, etc, dofs on line 0, dofs on line 1,
+   * etc, dofs on quad 0, etc.) This function is only available on
+   * <i>active</i> objects (see @ref GlossActive "this glossary entry").
    *
-   * The cells needs to be an active cell (and not artificial in a
-   * parallel distributed computation).
+   * The cells needs to be an active cell (and not artificial in a parallel
+   * distributed computation).
    *
    * The vector has to have the right size before being passed to this
    * function.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
-   *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
-   *
-   * For cells, there is only a single possible finite element index
-   * (namely the one for that cell, returned by
-   * <code>cell-@>active_fe_index</code>. Consequently, the derived
-   * DoFCellAccessor class has an overloaded version of this function
-   * that calls the present function with
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
+   *
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
+   *
+   * For cells, there is only a single possible finite element index (namely
+   * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
+   * Consequently, the derived DoFCellAccessor class has an overloaded version
+   * of this function that calls the present function with
    * <code>cell-@>active_fe_index</code> as last argument.
    */
   void get_dof_indices (std::vector<types::global_dof_index> &dof_indices,
                         const unsigned int fe_index = AccessorData::default_fe_index) const;
 
   /**
-   * Global DoF index of the <i>i</i> degree associated with the @p
-   * vertexth vertex of the present cell.
+   * Global DoF index of the <i>i</i> degree associated with the @p vertexth
+   * vertex of the present cell.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   types::global_dof_index vertex_dof_index (const unsigned int vertex,
                                             const unsigned int i,
@@ -926,32 +886,29 @@ public:
   /**
    * Index of the <i>i</i>th degree of freedom of this object.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
-   *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
-   *
-   * @note While the get_dof_indices() function returns an array that
-   * contains the indices of all degrees of freedom that somehow live
-   * on this object (i.e. on the vertices, edges or interior of this
-   * object), the current dof_index() function only considers the DoFs
-   * that really belong to this particular object's interior. In other
-   * words, as an example, if the current object refers to a quad (a
-   * cell in 2d, a face in 3d) and the finite element associated with
-   * it is a bilinear one, then the get_dof_indices() will return an
-   * array of size 4 while dof_index() will produce an exception
-   * because no degrees are defined in the interior of the face.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
+   *
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
+   *
+   * @note While the get_dof_indices() function returns an array that contains
+   * the indices of all degrees of freedom that somehow live on this object
+   * (i.e. on the vertices, edges or interior of this object), the current
+   * dof_index() function only considers the DoFs that really belong to this
+   * particular object's interior. In other words, as an example, if the
+   * current object refers to a quad (a cell in 2d, a face in 3d) and the
+   * finite element associated with it is a bilinear one, then the
+   * get_dof_indices() will return an array of size 4 while dof_index() will
+   * produce an exception because no degrees are defined in the interior of
+   * the face.
    */
   types::global_dof_index dof_index (const unsigned int i,
                                      const unsigned int fe_index = AccessorData::default_fe_index) const;
@@ -961,53 +918,50 @@ public:
    */
 
   /**
-   *  @name Accessing the finite element associated with this object
+   * @name Accessing the finite element associated with this object
    */
   /**
    * @{
    */
 
   /**
-   * Return the number of finite elements that are active on a given
-   * object.
+   * Return the number of finite elements that are active on a given object.
    *
-   * For non-hp DoFHandler objects, the answer is of course always
-   * one. However, for hp::DoFHandler objects, this isn't the case: If
-   * this is a cell, the answer is of course one. If it is a face, the
-   * answer may be one or two, depending on whether the two adjacent
-   * cells use the same finite element or not. If it is an edge in 3d,
-   * the possible return value may be one or any other value larger
-   * than that.
+   * For non-hp DoFHandler objects, the answer is of course always one.
+   * However, for hp::DoFHandler objects, this isn't the case: If this is a
+   * cell, the answer is of course one. If it is a face, the answer may be one
+   * or two, depending on whether the two adjacent cells use the same finite
+   * element or not. If it is an edge in 3d, the possible return value may be
+   * one or any other value larger than that.
    */
   unsigned int
   n_active_fe_indices () const;
 
   /**
-   * Return the @p n-th active fe index on this object. For cells and
-   * all non-hp objects, there is only a single active fe index, so
-   * the argument must be equal to zero. For lower-dimensional hp
-   * objects, there are n_active_fe_indices() active finite elements,
-   * and this function can be queried for their indices.
+   * Return the @p n-th active fe index on this object. For cells and all non-
+   * hp objects, there is only a single active fe index, so the argument must
+   * be equal to zero. For lower-dimensional hp objects, there are
+   * n_active_fe_indices() active finite elements, and this function can be
+   * queried for their indices.
    */
   unsigned int
   nth_active_fe_index (const unsigned int n) const;
 
   /**
-   * Return true if the finite element with given index is active on
-   * the present object. For non-hp DoF accessors, this is of course
-   * the case only if @p fe_index equals zero. For cells, it is the
-   * case if @p fe_index equals active_fe_index() of this cell. For
-   * faces and other lower-dimensional objects, there may be more than
-   * one @p fe_index that are active on any given object (see
-   * n_active_fe_indices()).
+   * Return true if the finite element with given index is active on the
+   * present object. For non-hp DoF accessors, this is of course the case only
+   * if @p fe_index equals zero. For cells, it is the case if @p fe_index
+   * equals active_fe_index() of this cell. For faces and other lower-
+   * dimensional objects, there may be more than one @p fe_index that are
+   * active on any given object (see n_active_fe_indices()).
    */
   bool
   fe_index_is_active (const unsigned int fe_index) const;
 
   /**
-   * Return a reference to the finite element used on this object with
-   * the given @p fe_index. @p fe_index must be used on this object,
-   * i.e. <code>fe_index_is_active(fe_index)</code> must return true.
+   * Return a reference to the finite element used on this object with the
+   * given @p fe_index. @p fe_index must be used on this object, i.e.
+   * <code>fe_index_is_active(fe_index)</code> must return true.
    */
   const FiniteElement<DH<1,spacedim>::dimension,DH<1,spacedim>::space_dimension> &
   get_fe (const unsigned int fe_index) const;
@@ -1041,8 +995,8 @@ public:
    */
   DeclException0 (ExcMatrixDoesNotMatch);
   /**
-   * A function has been called for a cell which should be active, but
-   * is refined. @ref GlossActive
+   * A function has been called for a cell which should be active, but is
+   * refined. @ref GlossActive
    *
    * @ingroup Exceptions
    */
@@ -1057,13 +1011,12 @@ public:
 protected:
 
   /**
-   * Store the address of the DoFHandler object
-   * to be accessed.
+   * Store the address of the DoFHandler object to be accessed.
    */
   DH<1,spacedim> *dof_handler;
 
   /**
-   *  Compare for equality.
+   * Compare for equality.
    */
   template <int dim2, class DH2, bool level_dof_access2>
   bool operator == (const DoFAccessor<dim2,DH2,level_dof_access2> &) const;
@@ -1080,48 +1033,42 @@ protected:
   void set_dof_handler (DH<1,spacedim> *dh);
 
   /**
-   * Set the index of the <i>i</i>th degree of freedom of this object
-   * to @p index.
+   * Set the index of the <i>i</i>th degree of freedom of this object to @p
+   * index.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   void set_dof_index (const unsigned int i,
                       const types::global_dof_index index,
                       const unsigned int fe_index = AccessorData::default_fe_index) const;
 
   /**
-   * Set the global index of the <i>i</i> degree on the @p vertex-th
-   * vertex of the present cell to @p index.
+   * Set the global index of the <i>i</i> degree on the @p vertex-th vertex of
+   * the present cell to @p index.
    *
-   * The last argument denotes the finite element index. For the
-   * standard ::DoFHandler class, this value must be equal to its
-   * default value since that class only supports the same finite
-   * element on all cells anyway.
+   * The last argument denotes the finite element index. For the standard
+   * ::DoFHandler class, this value must be equal to its default value since
+   * that class only supports the same finite element on all cells anyway.
    *
-   * However, for hp objects (i.e. the hp::DoFHandler class),
-   * different finite element objects may be used on different
-   * cells. On faces between two cells, as well as vertices, there may
-   * therefore be two sets of degrees of freedom, one for each of the
-   * finite elements used on the adjacent cells. In order to specify
-   * which set of degrees of freedom to work on, the last argument is
-   * used to disambiguate. Finally, if this function is called for a
-   * cell object, there can only be a single set of degrees of
-   * freedom, and fe_index has to match the result of
-   * active_fe_index().
+   * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+   * element objects may be used on different cells. On faces between two
+   * cells, as well as vertices, there may therefore be two sets of degrees of
+   * freedom, one for each of the finite elements used on the adjacent cells.
+   * In order to specify which set of degrees of freedom to work on, the last
+   * argument is used to disambiguate. Finally, if this function is called for
+   * a cell object, there can only be a single set of degrees of freedom, and
+   * fe_index has to match the result of active_fe_index().
    */
   void set_vertex_dof_index (const unsigned int vertex,
                              const unsigned int i,
@@ -1136,8 +1083,8 @@ protected:
 
 
   /**
-   * Make the DoFHandler class a friend so that it can call the
-   * set_xxx() functions.
+   * Make the DoFHandler class a friend so that it can call the set_xxx()
+   * functions.
    */
   template <int, int> friend class DoFHandler;
   template <int, int> friend class hp::DoFHandler;
@@ -1155,10 +1102,10 @@ protected:
 /**
  * Grant access to the degrees of freedom on a cell.
  *
- * Note that since for the class we derive from, i.e. <tt>DoFAccessor<dim></tt>,
- * the two template parameters are equal, the base class is actually derived from
- * CellAccessor, which makes the functions of this class available to the
- * DoFCellAccessor class as well.
+ * Note that since for the class we derive from, i.e.
+ * <tt>DoFAccessor<dim></tt>, the two template parameters are equal, the base
+ * class is actually derived from CellAccessor, which makes the functions of
+ * this class available to the DoFCellAccessor class as well.
  *
  * @ingroup dofs
  * @ingroup Accessors
@@ -1196,8 +1143,8 @@ public:
   typedef DH Container;
 
   /**
-   * A type for an iterator over the faces of a cell. This is
-   * what the face() function returns.
+   * A type for an iterator over the faces of a cell. This is what the face()
+   * function returns.
    */
   typedef
   TriaIterator<DoFAccessor<DH::dimension-1, DH, level_dof_access> >
@@ -1220,22 +1167,22 @@ public:
 
   /**
    * Conversion constructor. This constructor exists to make certain
-   * constructs simpler to write in dimension independent code. For
-   * example, it allows assigning a face iterator to a line iterator,
-   * an operation that is useful in 2d but doesn't make any sense in
-   * 3d. The constructor here exists for the purpose of making the
-   * code conform to C++ but it will unconditionally abort; in other
-   * words, assigning a face iterator to a line iterator is better put
-   * into an if-statement that checks that the dimension is two, and
-   * assign to a quad iterator in 3d (an operator that, without this
-   * constructor would be illegal if we happen to compile for 2d).
+   * constructs simpler to write in dimension independent code. For example,
+   * it allows assigning a face iterator to a line iterator, an operation that
+   * is useful in 2d but doesn't make any sense in 3d. The constructor here
+   * exists for the purpose of making the code conform to C++ but it will
+   * unconditionally abort; in other words, assigning a face iterator to a
+   * line iterator is better put into an if-statement that checks that the
+   * dimension is two, and assign to a quad iterator in 3d (an operator that,
+   * without this constructor would be illegal if we happen to compile for
+   * 2d).
    */
   template <int structdim2, int dim2, int spacedim2>
   DoFCellAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Another conversion operator between objects that don't make
-   * sense, just like the previous one.
+   * Another conversion operator between objects that don't make sense, just
+   * like the previous one.
    */
   template <int dim2, class DH2, bool level_dof_access2>
   explicit
@@ -1246,36 +1193,36 @@ public:
    */
 
   /**
-   * Return the parent of this cell as a DoF cell iterator.
-   * If the parent does not exist (i.e., if the object is at the coarsest level of
-   * the mesh hierarchy), an exception is generated.
+   * Return the parent of this cell as a DoF cell iterator. If the parent does
+   * not exist (i.e., if the object is at the coarsest level of the mesh
+   * hierarchy), an exception is generated.
    *
-   * This function is needed
-   * since the parent function of the base class CellAccessor returns a triangulation
-   * cell accessor without access to the DoF data.
+   * This function is needed since the parent function of the base class
+   * CellAccessor returns a triangulation cell accessor without access to the
+   * DoF data.
    */
   TriaIterator<DoFCellAccessor<DH, level_dof_access> >
   parent () const;
 
   /**
-   *  @name Accessing sub-objects and neighbors
+   * @name Accessing sub-objects and neighbors
    */
   /**
    * @{
    */
 
   /**
-   * Return the @p ith neighbor as a DoF cell iterator. This function
-   * is needed since the neighbor function of the base class returns a
-   * cell accessor without access to the DoF data.
+   * Return the @p ith neighbor as a DoF cell iterator. This function is
+   * needed since the neighbor function of the base class returns a cell
+   * accessor without access to the DoF data.
    */
   TriaIterator<DoFCellAccessor<DH, level_dof_access> >
   neighbor (const unsigned int) const;
 
   /**
-   * Return the @p ith child as a DoF cell iterator. This function is
-   * needed since the child function of the base class returns a cell
-   * accessor without access to the DoF data.
+   * Return the @p ith child as a DoF cell iterator. This function is needed
+   * since the child function of the base class returns a cell accessor
+   * without access to the DoF data.
    */
   TriaIterator<DoFCellAccessor<DH, level_dof_access> >
   child (const unsigned int) const;
@@ -1283,17 +1230,17 @@ public:
   /**
    * Return an iterator to the @p ith face of this cell.
    *
-   * This function is not implemented in 1D, and returns
-   * DoFAccessor::line in 2D and DoFAccessor::quad in 3d.
+   * This function is not implemented in 1D, and returns DoFAccessor::line in
+   * 2D and DoFAccessor::quad in 3d.
    */
   face_iterator
   face (const unsigned int i) const;
 
   /**
-   * Return the result of the @p neighbor_child_on_subface function of
-   * the base class, but convert it so that one can also access the
-   * DoF data (the function in the base class only returns an iterator
-   * with access to the triangulation data).
+   * Return the result of the @p neighbor_child_on_subface function of the
+   * base class, but convert it so that one can also access the DoF data (the
+   * function in the base class only returns an iterator with access to the
+   * triangulation data).
    */
   TriaIterator<DoFCellAccessor<DH, level_dof_access> >
   neighbor_child_on_subface (const unsigned int face_no,
@@ -1304,47 +1251,43 @@ public:
    */
 
   /**
-   *  @name Extracting values from global vectors
+   * @name Extracting values from global vectors
    */
   /**
    * @{
    */
 
   /**
-   * Return the values of the given vector restricted to the dofs of
-   * this cell in the standard ordering: dofs on vertex 0, dofs on
-   * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
-   * 0, etc.
+   * Return the values of the given vector restricted to the dofs of this cell
+   * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
    *
-   * The input vector may be either a <tt>Vector<float></tt>,
-   * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
-   * vector if deal.II is compiled to support these libraries. It is
-   * in the responsibility of the caller to assure that the types of
-   * the numbers stored in input and output vectors are compatible and
-   * with similar accuracy.
+   * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+   * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+   * compiled to support these libraries. It is in the responsibility of the
+   * caller to assure that the types of the numbers stored in input and output
+   * vectors are compatible and with similar accuracy.
    */
   template <class InputVector, typename number>
   void get_dof_values (const InputVector &values,
                        Vector<number>    &local_values) const;
 
   /**
-   * Return the values of the given vector restricted to the dofs of
-   * this cell in the standard ordering: dofs on vertex 0, dofs on
-   * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
-   * 0, etc.
+   * Return the values of the given vector restricted to the dofs of this cell
+   * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
    *
-   * The input vector may be either a <tt>Vector<float></tt>,
-   * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
-   * vector if deal.II is compiled to support these libraries. It is
-   * in the responsibility of the caller to assure that the types of
-   * the numbers stored in input and output vectors are compatible and
-   * with similar accuracy.
+   * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+   * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+   * compiled to support these libraries. It is in the responsibility of the
+   * caller to assure that the types of the numbers stored in input and output
+   * vectors are compatible and with similar accuracy.
    */
   template <class InputVector, typename ForwardIterator>
   void get_dof_values (const InputVector &values,
@@ -1352,22 +1295,20 @@ public:
                        ForwardIterator    local_values_end) const;
 
   /**
-   * Return the values of the given vector restricted to the dofs of
-   * this cell in the standard ordering: dofs on vertex 0, dofs on
-   * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
-   * 0, etc.
+   * Return the values of the given vector restricted to the dofs of this cell
+   * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
    *
-   * The input vector may be either a <tt>Vector<float></tt>,
-   * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
-   * vector if deal.II is compiled to support these libraries. It is
-   * in the responsibility of the caller to assure that the types of
-   * the numbers stored in input and output vectors are compatible and
-   * with similar accuracy. The ConstraintMatrix passed as an argument
-   * to this function makes sure that constraints are correctly
-   * distributed when the dof values are calculated.
+   * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+   * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+   * compiled to support these libraries. It is in the responsibility of the
+   * caller to assure that the types of the numbers stored in input and output
+   * vectors are compatible and with similar accuracy. The ConstraintMatrix
+   * passed as an argument to this function makes sure that constraints are
+   * correctly distributed when the dof values are calculated.
    */
   template <class InputVector, typename ForwardIterator>
   void get_dof_values (const ConstraintMatrix &constraints,
@@ -1376,63 +1317,59 @@ public:
                        ForwardIterator         local_values_end) const;
 
   /**
-   * This function is the counterpart to get_dof_values(): it takes a
-   * vector of values for the degrees of freedom of the cell pointed
-   * to by this iterator and writes these values into the global data
-   * vector @p values. This function is only callable for active
-   * cells.
+   * This function is the counterpart to get_dof_values(): it takes a vector
+   * of values for the degrees of freedom of the cell pointed to by this
+   * iterator and writes these values into the global data vector @p values.
+   * This function is only callable for active cells.
    *
-   * Note that for continuous finite elements, calling this function
-   * affects the dof values on neighboring cells as well. It may also
-   * violate continuity requirements for hanging nodes, if neighboring
-   * cells are less refined than the present one. These requirements
-   * are not taken care of and must be enforced by the user
-   * afterwards.
+   * Note that for continuous finite elements, calling this function affects
+   * the dof values on neighboring cells as well. It may also violate
+   * continuity requirements for hanging nodes, if neighboring cells are less
+   * refined than the present one. These requirements are not taken care of
+   * and must be enforced by the user afterwards.
    *
    * The vector has to have the right size before being passed to this
    * function.
    *
-   * The output vector may be either a Vector<float>, Vector<double>,
-   * or a BlockVector<double>, or a PETSc vector if deal.II is
-   * compiled to support these libraries. It is in the responsibility
-   * of the caller to assure that the types of the numbers stored in
-   * input and output vectors are compatible and with similar
-   * accuracy.
+   * The output vector may be either a Vector<float>, Vector<double>, or a
+   * BlockVector<double>, or a PETSc vector if deal.II is compiled to support
+   * these libraries. It is in the responsibility of the caller to assure that
+   * the types of the numbers stored in input and output vectors are
+   * compatible and with similar accuracy.
    */
   template <class OutputVector, typename number>
   void set_dof_values (const Vector<number> &local_values,
                        OutputVector         &values) const;
 
   /**
-   * Return the interpolation of the given finite element function to
-   * the present cell. In the simplest case, the cell is a terminal
-   * one, i.e., it has no children; then, the returned value is the vector
-   * of nodal values on that cell. You could as well get the
-   * desired values through the @p get_dof_values function. In the
-   * other case, when the cell has children, we use the restriction
-   * matrices provided by the finite element class to compute the
-   * interpolation from the children to the present cell.
+   * Return the interpolation of the given finite element function to the
+   * present cell. In the simplest case, the cell is a terminal one, i.e., it
+   * has no children; then, the returned value is the vector of nodal values
+   * on that cell. You could as well get the desired values through the @p
+   * get_dof_values function. In the other case, when the cell has children,
+   * we use the restriction matrices provided by the finite element class to
+   * compute the interpolation from the children to the present cell.
    *
    * If the cell is part of a hp::DoFHandler object, cells only have an
    * associated finite element space if they are active. However, this
-   * function is supposed to also provide information on inactive cells
-   * with children. Consequently, it carries a third argument that can be
-   * used in the hp context that denotes the finite element space we are
-   * supposed to interpolate onto. If the cell is active, this function
-   * then obtains the finite element function from the <code>values</code>
-   * vector on this cell and interpolates it onto the space described
-   * by the <code>fe_index</code>th element of the hp::FECollection associated
-   * with the hp::DoFHandler of which this cell is a part of. If the cell
-   * is not active, then we first perform this interpolation on all of its
-   * terminal children and then interpolate this function down to the
-   * cell requested keeping the function space the same.
+   * function is supposed to also provide information on inactive cells with
+   * children. Consequently, it carries a third argument that can be used in
+   * the hp context that denotes the finite element space we are supposed to
+   * interpolate onto. If the cell is active, this function then obtains the
+   * finite element function from the <code>values</code> vector on this cell
+   * and interpolates it onto the space described by the
+   * <code>fe_index</code>th element of the hp::FECollection associated with
+   * the hp::DoFHandler of which this cell is a part of. If the cell is not
+   * active, then we first perform this interpolation on all of its terminal
+   * children and then interpolate this function down to the cell requested
+   * keeping the function space the same.
    *
    * It is assumed that both input vectors already have the right size
    * beforehand.
    *
-   * @note Unlike the get_dof_values() function, this function is only available
-   * on cells, rather than on lines, quads, and hexes, since interpolation
-   * is presently only provided for cells by the finite element
+   * @note Unlike the get_dof_values() function, this function is only
+   * available on cells, rather than on lines, quads, and hexes, since
+   * interpolation is presently only provided for cells by the finite element
    * classes.
    */
   template <class InputVector, typename number>
@@ -1441,60 +1378,55 @@ public:
                                     const unsigned int fe_index = DH::default_fe_index) const;
 
   /**
-   * This function is the counterpart to get_interpolated_dof_values():
-   * you specify the dof values on a cell and these are interpolated
-   * to the children of the present cell and set on the terminal
-   * cells.
+   * This function is the counterpart to get_interpolated_dof_values(): you
+   * specify the dof values on a cell and these are interpolated to the
+   * children of the present cell and set on the terminal cells.
    *
-   * In principle, it works as follows: if the cell pointed to by this
-   * object is terminal (i.e., has no children), then the dof values are set in the global
-   * data vector by calling the set_dof_values() function; otherwise,
-   * the values are prolonged to each of the children and this
-   * function is called for each of them.
+   * In principle, it works as follows: if the cell pointed to by this object
+   * is terminal (i.e., has no children), then the dof values are set in the
+   * global data vector by calling the set_dof_values() function; otherwise,
+   * the values are prolonged to each of the children and this function is
+   * called for each of them.
    *
-   * Using the get_interpolated_dof_values() and this function, you
-   * can compute the interpolation of a finite element function to a
-   * coarser grid by first getting the interpolated solution on a cell
-   * of the coarse grid and afterwards redistributing it using this
-   * function.
+   * Using the get_interpolated_dof_values() and this function, you can
+   * compute the interpolation of a finite element function to a coarser grid
+   * by first getting the interpolated solution on a cell of the coarse grid
+   * and afterwards redistributing it using this function.
    *
-   * Note that for continuous finite elements, calling this function
-   * affects the dof values on neighboring cells as well. It may also
-   * violate continuity requirements for hanging nodes, if neighboring
-   * cells are less refined than the present one, or if their children
-   * are less refined than the children of this cell. These
-   * requirements are not taken care of and must be enforced by the
-   * user afterward.
+   * Note that for continuous finite elements, calling this function affects
+   * the dof values on neighboring cells as well. It may also violate
+   * continuity requirements for hanging nodes, if neighboring cells are less
+   * refined than the present one, or if their children are less refined than
+   * the children of this cell. These requirements are not taken care of and
+   * must be enforced by the user afterward.
    *
    * If the cell is part of a hp::DoFHandler object, cells only have an
    * associated finite element space if they are active. However, this
-   * function is supposed to also work on inactive cells
-   * with children. Consequently, it carries a third argument that can be
-   * used in the hp context that denotes the finite element space we are
-   * supposed to interpret the input vector of this function in.
-   * If the cell is active, this function
-   * then interpolates the input vector interpreted as an element of the space described
-   * by the <code>fe_index</code>th element of the hp::FECollection associated
-   * with the hp::DoFHandler of which this cell is a part of, and interpolates
-   * it into the space that is associated with this cell. On the other hand, if the cell
-   * is not active, then we first perform this interpolation from this cell
-   * to its children using the given <code>fe_index</code> until we end
-   * up on an active cell, at which point we follow the procedure outlined
-   * at the beginning of the paragraph.
-   *
-   * It is assumed that both vectors already have the right size
-   * beforehand. This function relies on the existence of a natural
-   * interpolation property of finite element spaces of a cell to its
-   * children, denoted by the prolongation matrices of finite element
-   * classes. For some elements, the spaces on coarse and fine grids
-   * are not nested, in which case the interpolation to a child is not
-   * the identity; refer to the documentation of the respective finite
-   * element class for a description of what the prolongation matrices
-   * represent in this case.
-   *
-   * @note Unlike the get_dof_values() function, this function is only available
-   * on cells, rather than on lines, quads, and hexes, since interpolation
-   * is presently only provided for cells by the finite element
+   * function is supposed to also work on inactive cells with children.
+   * Consequently, it carries a third argument that can be used in the hp
+   * context that denotes the finite element space we are supposed to
+   * interpret the input vector of this function in. If the cell is active,
+   * this function then interpolates the input vector interpreted as an
+   * element of the space described by the <code>fe_index</code>th element of
+   * the hp::FECollection associated with the hp::DoFHandler of which this
+   * cell is a part of, and interpolates it into the space that is associated
+   * with this cell. On the other hand, if the cell is not active, then we
+   * first perform this interpolation from this cell to its children using the
+   * given <code>fe_index</code> until we end up on an active cell, at which
+   * point we follow the procedure outlined at the beginning of the paragraph.
+   *
+   * It is assumed that both vectors already have the right size beforehand.
+   * This function relies on the existence of a natural interpolation property
+   * of finite element spaces of a cell to its children, denoted by the
+   * prolongation matrices of finite element classes. For some elements, the
+   * spaces on coarse and fine grids are not nested, in which case the
+   * interpolation to a child is not the identity; refer to the documentation
+   * of the respective finite element class for a description of what the
+   * prolongation matrices represent in this case.
+   *
+   * @note Unlike the get_dof_values() function, this function is only
+   * available on cells, rather than on lines, quads, and hexes, since
+   * interpolation is presently only provided for cells by the finite element
    * classes.
    */
   template <class OutputVector, typename number>
@@ -1503,13 +1435,12 @@ public:
                                         const unsigned int fe_index = DH::default_fe_index) const;
 
   /**
-   * Distribute a local (cell based) vector to a global one by mapping
-   * the local numbering of the degrees of freedom to the global one
-   * and entering the local values into the global vector.
+   * Distribute a local (cell based) vector to a global one by mapping the
+   * local numbering of the degrees of freedom to the global one and entering
+   * the local values into the global vector.
    *
-   * The elements are <em>added</em> up to the elements in the global
-   * vector, rather than just set, since this is usually what one
-   * wants.
+   * The elements are <em>added</em> up to the elements in the global vector,
+   * rather than just set, since this is usually what one wants.
    */
   template <typename number, typename OutputVector>
   void
@@ -1517,14 +1448,12 @@ public:
                               OutputVector         &global_destination) const;
 
   /**
-   * Distribute a local (cell based) vector in iterator format to a
-   * global one by mapping the local numbering of the degrees of
-   * freedom to the global one and entering the local values into the
-   * global vector.
+   * Distribute a local (cell based) vector in iterator format to a global one
+   * by mapping the local numbering of the degrees of freedom to the global
+   * one and entering the local values into the global vector.
    *
-   * The elements are <em>added</em> up to the elements in the global
-   * vector, rather than just set, since this is usually what one
-   * wants.
+   * The elements are <em>added</em> up to the elements in the global vector,
+   * rather than just set, since this is usually what one wants.
    */
   template <typename ForwardIterator, typename OutputVector>
   void
@@ -1533,15 +1462,14 @@ public:
                               OutputVector     &global_destination) const;
 
   /**
-   * Distribute a local (cell based) vector in iterator format to a
-   * global one by mapping the local numbering of the degrees of
-   * freedom to the global one and entering the local values into the
-   * global vector.
+   * Distribute a local (cell based) vector in iterator format to a global one
+   * by mapping the local numbering of the degrees of freedom to the global
+   * one and entering the local values into the global vector.
    *
-   * The elements are <em>added</em> up to the elements in the global
-   * vector, rather than just set, since this is usually what one
-   * wants. Moreover, the ConstraintMatrix passed to this function
-   * makes sure that also constraints are eliminated in this process.
+   * The elements are <em>added</em> up to the elements in the global vector,
+   * rather than just set, since this is usually what one wants. Moreover, the
+   * ConstraintMatrix passed to this function makes sure that also constraints
+   * are eliminated in this process.
    */
   template <typename ForwardIterator, typename OutputVector>
   void
@@ -1552,10 +1480,9 @@ public:
 
   /**
    * This function does much the same as the
-   * <tt>distribute_local_to_global(Vector,Vector)</tt> function, but
-   * operates on matrices instead of vectors. If the matrix type is a
-   * sparse matrix then it is supposed to have non-zero entry slots
-   * where required.
+   * <tt>distribute_local_to_global(Vector,Vector)</tt> function, but operates
+   * on matrices instead of vectors. If the matrix type is a sparse matrix
+   * then it is supposed to have non-zero entry slots where required.
    */
   template <typename number, typename OutputMatrix>
   void
@@ -1563,9 +1490,8 @@ public:
                               OutputMatrix             &global_destination) const;
 
   /**
-   * This function does what the two
-   * <tt>distribute_local_to_global</tt> functions with vector and
-   * matrix argument do, but all at once.
+   * This function does what the two <tt>distribute_local_to_global</tt>
+   * functions with vector and matrix argument do, but all at once.
    */
   template <typename number, typename OutputMatrix, typename OutputVector>
   void
@@ -1579,7 +1505,7 @@ public:
    */
 
   /**
-   *  @name Accessing the DoF indices of this object
+   * @name Accessing the DoF indices of this object
    */
 
   /**
@@ -1589,12 +1515,12 @@ public:
   /**
    * Obtain the global indices of the local degrees of freedom on this cell.
    *
-   * If this object accesses a level cell (indicated by the third
-   * template argument or #is_level_cell), then return the result of
+   * If this object accesses a level cell (indicated by the third template
+   * argument or #is_level_cell), then return the result of
    * get_mg_dof_indices(), else return get_dof_indices().
    *
-   * You will get a level_cell_iterator when calling begin_mg() and a
-   * normal one otherwise.
+   * You will get a level_cell_iterator when calling begin_mg() and a normal
+   * one otherwise.
    *
    * Examples for this use are in the implementation of DoFRenumbering.
    */
@@ -1608,14 +1534,13 @@ public:
    * <i>active</i> objects (see @ref GlossActive "this glossary entry").
    *
    * @param[out] dof_indices The vector into which the indices will be
-   *     written. It has to have the right size (namely,
-   *     <code>fe.dofs_per_cell</code>, <code>fe.dofs_per_face</code>,
-   *     or <code>fe.dofs_per_line</code>, depending on which kind of
-   *     object this function is called) before being passed to this
-   *     function.
-   *
-   * This function reimplements the same function in the base class.
-   * In contrast to the function in the base class, we do not need the
+   * written. It has to have the right size (namely,
+   * <code>fe.dofs_per_cell</code>, <code>fe.dofs_per_face</code>, or
+   * <code>fe.dofs_per_line</code>, depending on which kind of object this
+   * function is called) before being passed to this function.
+   *
+   * This function reimplements the same function in the base class. In
+   * contrast to the function in the base class, we do not need the
    * <code>fe_index</code> here because there is always a unique finite
    * element index on cells.
    *
@@ -1623,20 +1548,23 @@ public:
    *
    * Also see get_active_or_mg_dof_indices().
    *
-   * @note In many places in the tutorial and elsewhere in the library,
-   *   the argument to this function is called <code>local_dof_indices</code>
-   *   by convention. The name is not meant to indicate the <i>local</i>
-   *   numbers of degrees of freedom (which are always between zero and
-   *   <code>fe.dofs_per_cell</code>) but instead that the returned values
-   *   are the <i>global</i> indices of those degrees of freedom that
-   *   are located locally on the current cell.
+   * @note In many places in the tutorial and elsewhere in the library, the
+   * argument to this function is called <code>local_dof_indices</code> by
+   * convention. The name is not meant to indicate the <i>local</i> numbers of
+   * degrees of freedom (which are always between zero and
+   * <code>fe.dofs_per_cell</code>) but instead that the returned values are
+   * the <i>global</i> indices of those degrees of freedom that are located
+   * locally on the current cell.
    *
-   * @deprecated Currently, this function can also be called for non-active cells, if all degrees of freedom of the FiniteElement are located in vertices. This functionality will vanish in a future release.
+   * @deprecated Currently, this function can also be called for non-active
+   * cells, if all degrees of freedom of the FiniteElement are located in
+   * vertices. This functionality will vanish in a future release.
    */
   void get_dof_indices (std::vector<types::global_dof_index> &dof_indices) const;
 
   /**
-   * @deprecated Use get_active_or_mg_dof_indices() with level_cell_iterator returned from begin_mg().
+   * @deprecated Use get_active_or_mg_dof_indices() with level_cell_iterator
+   * returned from begin_mg().
    *
    * Retrieve the global indices of the degrees of freedom on this cell in the
    * level vector associated to the level of the cell.
@@ -1648,58 +1576,54 @@ public:
    */
 
   /**
-   *  @name Accessing the finite element associated with this object
+   * @name Accessing the finite element associated with this object
    */
   /**
    * @{
    */
 
   /**
-   * Return the finite element that is used on the cell pointed to by
-   * this iterator. For non-hp DoF handlers, this is of course always
-   * the same element, independent of the cell we are presently on,
-   * but for hp DoF handlers, this may change from cell to cell.
+   * Return the finite element that is used on the cell pointed to by this
+   * iterator. For non-hp DoF handlers, this is of course always the same
+   * element, independent of the cell we are presently on, but for hp DoF
+   * handlers, this may change from cell to cell.
    *
-   * @note Since degrees of freedoms only exist on active cells
-   * for hp::DoFHandler (i.e., there is currently no implementation
-   * of multilevel hp::DoFHandler objects), it does not make sense
-   * to query the finite element on non-active cells since they
-   * do not have finite element spaces associated with them without
-   * having any degrees of freedom. Consequently, this function will
-   * produce an exception when called on non-active cells.
+   * @note Since degrees of freedoms only exist on active cells for
+   * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+   * hp::DoFHandler objects), it does not make sense to query the finite
+   * element on non-active cells since they do not have finite element spaces
+   * associated with them without having any degrees of freedom. Consequently,
+   * this function will produce an exception when called on non-active cells.
    */
   const FiniteElement<DH::dimension,DH::space_dimension> &
   get_fe () const;
 
   /**
-   * Returns the index inside the hp::FECollection of the
-   * FiniteElement used for this cell. This function is
-   * only useful if the DoF handler object associated with
-   * the current cell is an hp::DoFHandler.
+   * Returns the index inside the hp::FECollection of the FiniteElement used
+   * for this cell. This function is only useful if the DoF handler object
+   * associated with the current cell is an hp::DoFHandler.
    *
-   * @note Since degrees of freedoms only exist on active cells
-   * for hp::DoFHandler (i.e., there is currently no implementation
-   * of multilevel hp::DoFHandler objects), it does not make sense
-   * to query active FE indices on non-active cells since they
-   * do not have finite element spaces associated with them without
-   * having any degrees of freedom. Consequently, this function will
-   * produce an exception when called on non-active cells.
+   * @note Since degrees of freedoms only exist on active cells for
+   * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+   * hp::DoFHandler objects), it does not make sense to query active FE
+   * indices on non-active cells since they do not have finite element spaces
+   * associated with them without having any degrees of freedom. Consequently,
+   * this function will produce an exception when called on non-active cells.
    */
   unsigned int active_fe_index () const;
 
   /**
-   * Sets the index of the FiniteElement used for this cell. This
-   * determines which element in an hp::FECollection to use. This function is
-   * only useful if the DoF handler object associated with
-   * the current cell is an hp::DoFHandler.
+   * Sets the index of the FiniteElement used for this cell. This determines
+   * which element in an hp::FECollection to use. This function is only useful
+   * if the DoF handler object associated with the current cell is an
+   * hp::DoFHandler.
    *
-   * @note Since degrees of freedoms only exist on active cells
-   * for hp::DoFHandler (i.e., there is currently no implementation
-   * of multilevel hp::DoFHandler objects), it does not make sense
-   * to assign active FE indices to non-active cells since they
-   * do not have finite element spaces associated with them without
-   * having any degrees of freedom. Consequently, this function will
-   * produce an exception when called on non-active cells.
+   * @note Since degrees of freedoms only exist on active cells for
+   * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+   * hp::DoFHandler objects), it does not make sense to assign active FE
+   * indices to non-active cells since they do not have finite element spaces
+   * associated with them without having any degrees of freedom. Consequently,
+   * this function will produce an exception when called on non-active cells.
    */
   void set_active_fe_index (const unsigned int i);
   /**
@@ -1707,9 +1631,8 @@ public:
    */
 
   /**
-   * Set the DoF indices of this cell to the given values. This
-   * function bypasses the DoF cache, if one exists for the given DoF
-   * handler class.
+   * Set the DoF indices of this cell to the given values. This function
+   * bypasses the DoF cache, if one exists for the given DoF handler class.
    */
   void set_dof_indices (const std::vector<types::global_dof_index> &dof_indices);
 
@@ -1725,15 +1648,14 @@ public:
 
 private:
   /**
-   *  Copy operator. This is normally used in a context like
-   *  <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to
-   *  copy the object pointed to by @p b to the object pointed to by
-   *  @p a. However, the result of dereferencing an iterator is not an
-   *  object but an accessor; consequently, this operation is not
-   *  useful for iterators on triangulations. We declare this function
-   *  here private, thus it may not be used from outside.  Furthermore
-   *  it is not implemented and will give a linker error if used
-   *  anyway.
+   * Copy operator. This is normally used in a context like <tt>iterator a,b;
+   * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+   * by @p b to the object pointed to by @p a. However, the result of
+   * dereferencing an iterator is not an object but an accessor; consequently,
+   * this operation is not useful for iterators on triangulations. We declare
+   * this function here private, thus it may not be used from outside.
+   * Furthermore it is not implemented and will give a linker error if used
+   * anyway.
    */
   DoFCellAccessor<DH, level_dof_access> &
   operator = (const DoFCellAccessor<DH, level_dof_access> &da);
index 1a3882701d1877c543e2e60eb54296ef83b551ee..fdb96cbd665f2a5a37d9080db2586bfd0c3bd41b 100644 (file)
@@ -192,15 +192,13 @@ namespace internal
   namespace DoFAccessor
   {
     /**
-     * A class like the one with same
-     * name in tria.cc. See there for
-     * more information.
+     * A class like the one with same name in tria.cc. See there for more
+     * information.
      */
     struct Implementation
     {
       /**
-       * Implementations of the
-       * get_dof_index/set_dof_index functions.
+       * Implementations of the get_dof_index/set_dof_index functions.
        */
       template <int spacedim>
       static
@@ -1048,14 +1046,9 @@ namespace internal
       }
 
       /**
-       * Set the @p local_index-th
-       * degree of freedom
-       * corresponding to the finite
-       * element specified by @p
-       * fe_index on the vertex with
-       * global number @p
-       * vertex_index to @p
-       * global_index.
+       * Set the @p local_index-th degree of freedom corresponding to the
+       * finite element specified by @p fe_index on the vertex with global
+       * number @p vertex_index to @p global_index.
        */
       template <int dim, int spacedim>
       static
@@ -1141,14 +1134,9 @@ namespace internal
 
 
       /**
-       * Get the @p local_index-th
-       * degree of freedom
-       * corresponding to the finite
-       * element specified by @p
-       * fe_index on the vertex with
-       * global number @p
-       * vertex_index to @p
-       * global_index.
+       * Get the @p local_index-th degree of freedom corresponding to the
+       * finite element specified by @p fe_index on the vertex with global
+       * number @p vertex_index to @p global_index.
        */
 
       template <int dim, int spacedim>
@@ -1230,10 +1218,8 @@ namespace internal
 
 
       /**
-       * Return the number of
-       * different finite elements
-       * that are active on a given
-       * vertex.
+       * Return the number of different finite elements that are active on a
+       * given vertex.
        */
       template<int dim, int spacedim>
       static
@@ -1279,9 +1265,8 @@ namespace internal
 
 
       /**
-       * Return the fe index of the
-       * n-th finite element active
-       * on a given vertex.
+       * Return the fe index of the n-th finite element active on a given
+       * vertex.
        */
       template<int dim, int spacedim>
       static
@@ -1337,10 +1322,8 @@ namespace internal
 
 
       /**
-       * Return whether a particular
-       * finite element index is
-       * active on the specified
-       * vertex.
+       * Return whether a particular finite element index is active on the
+       * specified vertex.
        */
       template<int dim, int spacedim>
       static
@@ -2347,10 +2330,8 @@ namespace internal
     struct Implementation
     {
       /**
-       * Implement the updating of the
-       * cache. Currently not
-       * implemented for hp::DoFHandler
-       * objects.
+       * Implement the updating of the cache. Currently not implemented for
+       * hp::DoFHandler objects.
        */
       template <int spacedim, bool level_dof_access>
       static
@@ -2573,11 +2554,8 @@ namespace internal
 
 
       /**
-       * Implement setting dof
-       * indices on a
-       * cell. Currently not
-       * implemented for
-       * hp::DoFHandler objects.
+       * Implement setting dof indices on a cell. Currently not implemented
+       * for hp::DoFHandler objects.
        */
       template <int spacedim, bool level_dof_access>
       static
@@ -2733,9 +2711,8 @@ namespace internal
 
 
       /**
-       * Do what the active_fe_index
-       * function in the parent class
-       * is supposed to do.
+       * Do what the active_fe_index function in the parent class is supposed
+       * to do.
        */
       template <int dim, int spacedim, bool level_dof_access>
       static
@@ -2765,9 +2742,7 @@ namespace internal
 
 
       /**
-       * Do what the
-       * set_active_fe_index function
-       * in the parent class is
+       * Do what the set_active_fe_index function in the parent class is
        * supposed to do.
        */
       template <int dim, int spacedim, bool level_dof_access>
index 089412c651f96963cc031602145c63e483399630..c4259822879af893087af304040321eeeac4f63b 100644 (file)
@@ -27,7 +27,8 @@ DEAL_II_NAMESPACE_OPEN
 namespace internal
 {
   /**
-   * A namespace for internal data structures of the DoFHandler group of classes.
+   * A namespace for internal data structures of the DoFHandler group of
+   * classes.
    *
    * @ingroup dofs
    */
@@ -38,24 +39,28 @@ namespace internal
      *
      * <h4>DoFFaces</h4>
      *
-     * These classes are similar to the DoFLevel classes. We here store information
-     * that is associated with faces, rather than cells, as this information is independent of
-     * the hierarchical structure of cells, which are organized in levels. In 2D we store
-     * information on degrees of freedom located on lines whereas in 3D we store information on
-     * degrees of freedom located on quads and lines. In 1D we do nothing, as the faces of
-     * lines are vertices which are treated separately.
+     * These classes are similar to the DoFLevel classes. We here store
+     * information that is associated with faces, rather than cells, as this
+     * information is independent of the hierarchical structure of cells,
+     * which are organized in levels. In 2D we store information on degrees of
+     * freedom located on lines whereas in 3D we store information on degrees
+     * of freedom located on quads and lines. In 1D we do nothing, as the
+     * faces of lines are vertices which are treated separately.
      *
-     * Apart from the DoFObjects object containing the data to store (degree of freedom
-     * indices) we do not store any data or provide any functionality. However, we do implement
-     * a function to determine an estimate of the memory consumption of the contained
-     * DoFObjects object(s).
+     * Apart from the DoFObjects object containing the data to store (degree
+     * of freedom indices) we do not store any data or provide any
+     * functionality. However, we do implement a function to determine an
+     * estimate of the memory consumption of the contained DoFObjects
+     * object(s).
      *
-     * The data contained isn't usually directly accessed. Rather, except for some access from
-     * the DoFHandler class, access is usually through the DoFAccessor::set_dof_index() and
-     * DoFAccessor::dof_index() functions or similar functions of derived classes that in turn
-     * access the member variables using the DoFHandler::get_dof_index() and corresponding
-     * setter functions. Knowledge of the actual data format is therefore encapsulated to the
-     * present hierarchy of classes as well as the dealii::DoFHandler class.
+     * The data contained isn't usually directly accessed. Rather, except for
+     * some access from the DoFHandler class, access is usually through the
+     * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+     * similar functions of derived classes that in turn access the member
+     * variables using the DoFHandler::get_dof_index() and corresponding
+     * setter functions. Knowledge of the actual data format is therefore
+     * encapsulated to the present hierarchy of classes as well as the
+     * dealii::DoFHandler class.
      *
      * @author Tobias Leicht, 2006
      */
@@ -63,17 +68,16 @@ namespace internal
     class DoFFaces
     {
       /**
-       * Make the constructor private to prevent the use
-       * of this template, only the specializations
-       * should be used
+       * Make the constructor private to prevent the use of this template,
+       * only the specializations should be used
        */
     private:
       DoFFaces();
     };
 
     /**
-     * Store the indices of degrees of freedom on faces in 1D. As these would be vertices, which
-     * are treted separately, don't do anything.
+     * Store the indices of degrees of freedom on faces in 1D. As these would
+     * be vertices, which are treted separately, don't do anything.
      *
      * @author Tobias Leicht, 2006
      */
@@ -82,15 +86,14 @@ namespace internal
     {
     public:
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -98,7 +101,8 @@ namespace internal
     };
 
     /**
-     * Store the indices of degrees of freedom on faces in 2D, which are lines.
+     * Store the indices of degrees of freedom on faces in 2D, which are
+     * lines.
      *
      * @author Tobias Leicht, 2006
      */
@@ -107,21 +111,19 @@ namespace internal
     {
     public:
       /**
-       * The object containing the
-       * data of DoFs on lines.
+       * The object containing the data of DoFs on lines.
        */
       internal::DoFHandler::DoFObjects<1> lines;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -129,7 +131,8 @@ namespace internal
     };
 
     /**
-     * Store the indices of degrees of freedom on faces in 3D, which are quads, additionally also on lines.
+     * Store the indices of degrees of freedom on faces in 3D, which are
+     * quads, additionally also on lines.
      *
      * @author Tobias Leicht, 2006
      */
@@ -138,27 +141,24 @@ namespace internal
     {
     public:
       /**
-       * The object containing the
-       * data of DoFs on lines.
+       * The object containing the data of DoFs on lines.
        */
       internal::DoFHandler::DoFObjects<1> lines;
 
       /**
-       * The object containing the
-       * data of DoFs on quads.
+       * The object containing the data of DoFs on quads.
        */
       internal::DoFHandler::DoFObjects<2> quads;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
index 6a7ce85d739df4b0c8f1e31668289dbeb84d3212..56c171416b644c2a20c4091f747df8a6828536e4 100644 (file)
@@ -65,39 +65,36 @@ namespace internal
 
 
 /**
- * Manage the distribution and numbering of the degrees of freedom for
- * non-multigrid algorithms. This class satisfies the requirements outlined in
+ * Manage the distribution and numbering of the degrees of freedom for non-
+ * multigrid algorithms. This class satisfies the requirements outlined in
  * @ref GlossMeshAsAContainer "Meshes as containers". It is first used in the
  * step-2 tutorial program.
  *
- * For each vertex, line, quad, etc, this class stores a list of the
- * indices of degrees of freedom living on this object. These indices refer
- * to the unconstrained degrees of freedom, i.e. constrained degrees of
- * freedom are numbered in the same way as unconstrained ones, and are only
- * later eliminated.  This leads to the fact that indices in global vectors
- * and matrices also refer to all degrees of freedom and some kind of
- * condensation is needed to restrict the systems of equations to the
- * unconstrained degrees of freedom only. The actual layout of storage of
- * the indices is described in the dealii::internal::DoFHandler::DoFLevel
- * class documentation.
+ * For each vertex, line, quad, etc, this class stores a list of the indices
+ * of degrees of freedom living on this object. These indices refer to the
+ * unconstrained degrees of freedom, i.e. constrained degrees of freedom are
+ * numbered in the same way as unconstrained ones, and are only later
+ * eliminated.  This leads to the fact that indices in global vectors and
+ * matrices also refer to all degrees of freedom and some kind of condensation
+ * is needed to restrict the systems of equations to the unconstrained degrees
+ * of freedom only. The actual layout of storage of the indices is described
+ * in the dealii::internal::DoFHandler::DoFLevel class documentation.
  *
- * The class offers iterators to traverse all cells, in much the same way
- * as the Triangulation class does. Using the begin() and end() functions
- * (and companions, like begin_active()), one can obtain iterators to walk
- * over cells, and query the degree of freedom structures as well as the
+ * The class offers iterators to traverse all cells, in much the same way as
+ * the Triangulation class does. Using the begin() and end() functions (and
+ * companions, like begin_active()), one can obtain iterators to walk over
+ * cells, and query the degree of freedom structures as well as the
  * triangulation data. These iterators are built on top of those of the
  * Triangulation class, but offer the additional information on degrees of
- * freedom functionality compared to pure triangulation iterators. The
- * order in which dof iterators are presented by the <tt>++</tt> and
- * <tt>--</tt> operators is the same as that for the corresponding
- * iterators traversing the triangulation on which this DoFHandler is
- * constructed.
+ * freedom functionality compared to pure triangulation iterators. The order
+ * in which dof iterators are presented by the <tt>++</tt> and <tt>--</tt>
+ * operators is the same as that for the corresponding iterators traversing
+ * the triangulation on which this DoFHandler is constructed.
  *
  * The <tt>spacedim</tt> parameter has to be used if one wants to solve
  * problems on surfaces. If not specified, this parameter takes the default
  * value <tt>=dim</tt> implying that we want to solve problems in a domain
- * whose dimension equals the dimension of the space in which it is
- * embedded.
+ * whose dimension equals the dimension of the space in which it is embedded.
  *
  *
  * <h3>Distribution of indices for degrees of freedom</h3>
@@ -111,67 +108,64 @@ namespace internal
  * children, i.e. they are the most refined ones.
  *
  * Since the triangulation is traversed starting with the cells of the
- * coarsest active level and going to more refined levels, the lowest
- * numbers for dofs are given to the largest cells as well as their
- * bounding lines and vertices, with the dofs of more refined cells getting
- * higher numbers.
+ * coarsest active level and going to more refined levels, the lowest numbers
+ * for dofs are given to the largest cells as well as their bounding lines and
+ * vertices, with the dofs of more refined cells getting higher numbers.
  *
- * This numbering implies very large bandwiths of the resulting matrices
- * and is thus vastly suboptimal for some solution algorithms. For this
- * reason, the DoFRenumbering class offers several algorithms to reorder
- * the dof numbering according. See there for a discussion of the
- * implemented algorithms.
+ * This numbering implies very large bandwiths of the resulting matrices and
+ * is thus vastly suboptimal for some solution algorithms. For this reason,
+ * the DoFRenumbering class offers several algorithms to reorder the dof
+ * numbering according. See there for a discussion of the implemented
+ * algorithms.
  *
  *
  * <h3>Interaction with distributed meshes</h3>
  *
- * Upon construction, this class takes a reference to a triangulation
- * object. In most cases, this will be a reference to an object of type
- * Triangulation, i.e. the class that represents triangulations that
- * entirely reside on a single processor. However, it can also be of type
+ * Upon construction, this class takes a reference to a triangulation object.
+ * In most cases, this will be a reference to an object of type Triangulation,
+ * i.e. the class that represents triangulations that entirely reside on a
+ * single processor. However, it can also be of type
  * parallel::distributed::Triangulation (see, for example, step-32, step-40
- * and in particular the @ref distributed module) in which case the
- * DoFHandler object will proceed to only manage degrees of freedom on
- * locally owned and ghost cells. This process is entirely transparent to
- * the used.
+ * and in particular the @ref distributed module) in which case the DoFHandler
+ * object will proceed to only manage degrees of freedom on locally owned and
+ * ghost cells. This process is entirely transparent to the used.
  *
  *
  * <h3>User defined renumbering schemes</h3>
  *
  * The DoFRenumbering class offers a number of renumbering schemes like the
- * Cuthill-McKey scheme. Basically, the function sets up an array in which
- * for each degree of freedom we store the new index this DoF should have
- * after renumbering. Using this array, the renumber_dofs() function of the
- * present class is called, which actually performs the change from old DoF
- * indices to the ones given in the array. In some cases, however, a user
- * may want to compute her own renumbering order; in this case, one can
- * allocate an array with one element per degree of freedom and fill it
- * with the number that the respective degree of freedom shall be assigned.
- * This number may, for example, be obtained by sorting the support points
- * of the degrees of freedom in downwind direction.  Then call the
- * <tt>renumber_dofs(vector<types::global_dof_index>)</tt> function with
- * the array, which converts old into new degree of freedom indices.
+ * Cuthill-McKey scheme. Basically, the function sets up an array in which for
+ * each degree of freedom we store the new index this DoF should have after
+ * renumbering. Using this array, the renumber_dofs() function of the present
+ * class is called, which actually performs the change from old DoF indices to
+ * the ones given in the array. In some cases, however, a user may want to
+ * compute her own renumbering order; in this case, one can allocate an array
+ * with one element per degree of freedom and fill it with the number that the
+ * respective degree of freedom shall be assigned. This number may, for
+ * example, be obtained by sorting the support points of the degrees of
+ * freedom in downwind direction.  Then call the
+ * <tt>renumber_dofs(vector<types::global_dof_index>)</tt> function with the
+ * array, which converts old into new degree of freedom indices.
  *
  *
  * <h3>Serializing (loading or storing) DoFHandler objects</h3>
  *
- * Like many other classes in deal.II, the DoFHandler class can stream
- * its contents to an archive using BOOST's serialization facilities. The
- * data so stored can later be retrieved again from the archive to restore
- * the contents of this object. This facility is frequently used to save the
- * state of a program to disk for possible later resurrection, often in the
- * context of checkpoint/restart strategies for long running computations or
- * on computers that aren't very reliable (e.g. on very large clusters where
- * individual nodes occasionally fail and then bring down an entire MPI
- * job).
+ * Like many other classes in deal.II, the DoFHandler class can stream its
+ * contents to an archive using BOOST's serialization facilities. The data so
+ * stored can later be retrieved again from the archive to restore the
+ * contents of this object. This facility is frequently used to save the state
+ * of a program to disk for possible later resurrection, often in the context
+ * of checkpoint/restart strategies for long running computations or on
+ * computers that aren't very reliable (e.g. on very large clusters where
+ * individual nodes occasionally fail and then bring down an entire MPI job).
  *
- * The model for doing so is similar for the DoFHandler class as it is for
- * the Triangulation class (see the section in the general documentation of
- * that class). In particular, the load() function does not exactly restore
- * the same state as was stored previously using the save() function. Rather,
- * the function assumes that you load data into a DoFHandler object that is
- * already associated with a triangulation that has a content that matches
- * the one that was used when the data was saved. Likewise, the load() function
+ * The model for doing so is similar for the DoFHandler class as it is for the
+ * Triangulation class (see the section in the general documentation of that
+ * class). In particular, the load() function does not exactly restore the
+ * same state as was stored previously using the save() function. Rather, the
+ * function assumes that you load data into a DoFHandler object that is
+ * already associated with a triangulation that has a content that matches the
+ * one that was used when the data was saved. Likewise, the load() function
  * assumes that the current object is already associated with a finite element
  * object that matches the one that was associated with it when data was
  * saved; the latter can be achieved by calling DoFHandler::distribute_dofs()
@@ -201,22 +195,21 @@ public:
   typedef typename ActiveSelector::active_hex_iterator  active_hex_iterator;
 
   /**
-   * A typedef that is used to to identify
-   * @ref GlossActive "active cell iterators".
-   * The concept of iterators is discussed at length in the
-   * @ref Iterators "iterators documentation module".
+   * A typedef that is used to to identify @ref GlossActive "active cell
+   * iterators". The concept of iterators is discussed at length in the @ref
+   * Iterators "iterators documentation module".
    *
-   * The current typedef identifies active cells in a DoFHandler object.
-   * While the actual data type of the typedef is hidden behind a few
-   * layers of (unfortunately necessary) indirections, it is in essence
-   * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class
-   * works like a pointer to active objects that when you dereference it
-   * yields an object of type DoFCellAccessor. DoFCellAccessor is a class
-   * that identifies properties that are specific to cells in a DoFHandler,
-   * but it is derived (and consequently inherits) from both DoFAccessor,
-   * TriaCellAccessor and TriaAccessor that describe what you can ask of
-   * more general objects (lines, faces, as well as cells) in a
-   * triangulation and DoFHandler objects.
+   * The current typedef identifies active cells in a DoFHandler object. While
+   * the actual data type of the typedef is hidden behind a few layers of
+   * (unfortunately necessary) indirections, it is in essence
+   * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class works
+   * like a pointer to active objects that when you dereference it yields an
+   * object of type DoFCellAccessor. DoFCellAccessor is a class that
+   * identifies properties that are specific to cells in a DoFHandler, but it
+   * is derived (and consequently inherits) from both DoFAccessor,
+   * TriaCellAccessor and TriaAccessor that describe what you can ask of more
+   * general objects (lines, faces, as well as cells) in a triangulation and
+   * DoFHandler objects.
    *
    * @ingroup Iterators
    */
@@ -224,27 +217,26 @@ public:
 
   /**
    * A typedef that is used to to identify cell iterators. The concept of
-   * iterators is discussed at length in the
-   * @ref Iterators "iterators documentation module".
+   * iterators is discussed at length in the @ref Iterators "iterators
+   * documentation module".
    *
    * The current typedef identifies cells in a DoFHandler object. Some of
-   * these cells may in fact be active (see
-   * @ref GlossActive "active cell iterators")
-   * in which case they can in fact be asked for the degrees of freedom
-   * that live on them. On the other hand, if the cell is not active, any
-   * such query will result in an error. Note that this is what
+   * these cells may in fact be active (see @ref GlossActive "active cell
+   * iterators") in which case they can in fact be asked for the degrees of
+   * freedom that live on them. On the other hand, if the cell is not active,
+   * any such query will result in an error. Note that this is what
    * distinguishes this typedef from the level_cell_iterator typedef.
    *
-   * While the actual data type of the typedef is hidden behind a few
-   * layers of (unfortunately necessary) indirections, it is in essence
+   * While the actual data type of the typedef is hidden behind a few layers
+   * of (unfortunately necessary) indirections, it is in essence
    * TriaIterator<DoFCellAccessor>. The TriaIterator class works like a
-   * pointer to objects that when you dereference it yields an object of
-   * type DoFCellAccessor. DoFCellAccessor is a class that identifies
-   * properties that are specific to cells in a DoFHandler, but it is
-   * derived (and consequently inherits) from both DoFAccessor,
-   * TriaCellAccessor and TriaAccessor that describe what you can ask of
-   * more general objects (lines, faces, as well as cells) in a
-   * triangulation and DoFHandler objects.
+   * pointer to objects that when you dereference it yields an object of type
+   * DoFCellAccessor. DoFCellAccessor is a class that identifies properties
+   * that are specific to cells in a DoFHandler, but it is derived (and
+   * consequently inherits) from both DoFAccessor, TriaCellAccessor and
+   * TriaAccessor that describe what you can ask of more general objects
+   * (lines, faces, as well as cells) in a triangulation and DoFHandler
+   * objects.
    *
    * @ingroup Iterators
    */
@@ -276,10 +268,10 @@ public:
   static const unsigned int space_dimension = spacedim;
 
   /**
-   * When the arrays holding the DoF indices are set up, but before they
-   * are filled with actual values, they are set to an invalid value, in
-   * order to monitor possible problems. This invalid value is the constant
-   * defined here.
+   * When the arrays holding the DoF indices are set up, but before they are
+   * filled with actual values, they are set to an invalid value, in order to
+   * monitor possible problems. This invalid value is the constant defined
+   * here.
    *
    * Please note that you should not rely on it having a certain value, but
    * rather take its symbolic name.
@@ -287,14 +279,13 @@ public:
   static const types::global_dof_index invalid_dof_index = numbers::invalid_dof_index;
 
   /**
-   * The default index of the finite element to be used on a given cell.
-   * Since the present class only supports the same finite element to be
-   * used on all cells, the index of the finite element needs to be the
-   * same on all cells anyway, and by convention we pick zero for this
-   * value. The situation is different for hp objects (i.e. the
-   * hp::DoFHandler class) where different finite element indices may be
-   * used on different cells, and the default index there corresponds to an
-   * invalid value.
+   * The default index of the finite element to be used on a given cell. Since
+   * the present class only supports the same finite element to be used on all
+   * cells, the index of the finite element needs to be the same on all cells
+   * anyway, and by convention we pick zero for this value. The situation is
+   * different for hp objects (i.e. the hp::DoFHandler class) where different
+   * finite element indices may be used on different cells, and the default
+   * index there corresponds to an invalid value.
    */
   static const unsigned int default_fe_index = 0;
 
@@ -316,8 +307,8 @@ public:
   virtual ~DoFHandler ();
 
   /**
-   * Assign a Triangulation and a FiniteElement to the DoFHandler and
-   * compute the distribution of degrees of freedom over the mesh.
+   * Assign a Triangulation and a FiniteElement to the DoFHandler and compute
+   * the distribution of degrees of freedom over the mesh.
    */
   void initialize(const Triangulation<dim,spacedim> &tria,
                   const FiniteElement<dim,spacedim> &fe);
@@ -327,29 +318,28 @@ public:
    * needed for the given finite element. "Distributing" degrees of freedom
    * involved allocating memory to store the information that describes it
    * (e.g., whether it is located on a vertex, edge, face, etc) and to
-   * sequentially enumerate all degrees of freedom. In other words, while
-   * the mesh and the finite element object by themselves simply define a
-   * finite element space $V_h$, the process of distributing degrees of
-   * freedom makes sure that there is a basis for this space and that the
-   * shape functions of this basis are enumerated in an indexable,
-   * predictable way.
+   * sequentially enumerate all degrees of freedom. In other words, while the
+   * mesh and the finite element object by themselves simply define a finite
+   * element space $V_h$, the process of distributing degrees of freedom makes
+   * sure that there is a basis for this space and that the shape functions of
+   * this basis are enumerated in an indexable, predictable way.
    *
    * The purpose of this function is first discussed in the introduction to
    * the step-2 tutorial program.
    *
    * @note A pointer of the finite element given as argument is stored.
-   * Therefore, the lifetime of the finite element object shall be longer
-   * than that of this object. If you don't want this behavior, you may
-   * want to call the @p clear member function which also releases the lock
-   * of this object to the finite element.
+   * Therefore, the lifetime of the finite element object shall be longer than
+   * that of this object. If you don't want this behavior, you may want to
+   * call the @p clear member function which also releases the lock of this
+   * object to the finite element.
    */
   virtual void distribute_dofs (const FiniteElement<dim,spacedim> &fe);
 
   /**
    * Distribute level degrees of freedom on each level for geometric
-   * multigrid. The active DoFs need to be distributed using
-   * distribute_dofs() before calling this function and the @p fe needs to
-   * be identical to the finite element passed to distribute_dofs().
+   * multigrid. The active DoFs need to be distributed using distribute_dofs()
+   * before calling this function and the @p fe needs to be identical to the
+   * finite element passed to distribute_dofs().
    *
    * This replaces the functionality of the old MGDoFHandler.
    */
@@ -357,8 +347,8 @@ public:
 
   /**
    * This function returns whether this DoFHandler has DoFs distributed on
-   * each multigrid level or in other words if distribute_mg_dofs() has
-   * been called.
+   * each multigrid level or in other words if distribute_mg_dofs() has been
+   * called.
    */
   bool has_level_dofs() const;
 
@@ -369,28 +359,27 @@ public:
    * distributed actually has degrees of freedom (which is not the case for
    * FE_Nothing, for example).
    *
-   * If this object is based on a parallel::distributed::Triangulation,
-   * then the current function returns true if <i>any</i> partition of the
-   * parallel DoFHandler object has any degrees of freedom. In other words,
-   * the function returns true even if the Triangulation does not own any
-   * active cells on the current MPI process, but at least one process owns
-   * cells and at least this one process has any degrees of freedom
-   * associated with it.
+   * If this object is based on a parallel::distributed::Triangulation, then
+   * the current function returns true if <i>any</i> partition of the parallel
+   * DoFHandler object has any degrees of freedom. In other words, the
+   * function returns true even if the Triangulation does not own any active
+   * cells on the current MPI process, but at least one process owns cells and
+   * at least this one process has any degrees of freedom associated with it.
    */
   bool has_active_dofs() const;
 
   /**
-   * After distribute_dofs() with an FESystem element, the block structure
-   * of global and level vectors is stored in a BlockInfo object accessible
-   * with block_info(). This function initializes the local block structure
-   * on each cell in the same object.
+   * After distribute_dofs() with an FESystem element, the block structure of
+   * global and level vectors is stored in a BlockInfo object accessible with
+   * block_info(). This function initializes the local block structure on each
+   * cell in the same object.
    */
   void initialize_local_block_info();
 
   /**
-   * Clear all data of this object and especially delete the lock this
-   * object has to the finite element used the last time when
-   * @p distribute_dofs was called.
+   * Clear all data of this object and especially delete the lock this object
+   * has to the finite element used the last time when @p distribute_dofs was
+   * called.
    */
   virtual void clear ();
 
@@ -398,30 +387,30 @@ public:
    * Renumber degrees of freedom based on a list of new dof numbers for all
    * the dofs.
    *
-   * This function is called by the functions in DoFRenumbering function
-   * after computing the ordering of the degrees of freedom. This function
-   * is called, for example, by the functions in the DoFRenumbering
-   * namespace, but it can of course also be called from user code.
+   * This function is called by the functions in DoFRenumbering function after
+   * computing the ordering of the degrees of freedom. This function is
+   * called, for example, by the functions in the DoFRenumbering namespace,
+   * but it can of course also be called from user code.
    *
    * @arg new_number This array must have a size equal to the number of
-   * degrees of freedom owned by the current processor, i.e. the size must
-   * be equal to what n_locally_owned_dofs() returns. If only one processor
+   * degrees of freedom owned by the current processor, i.e. the size must be
+   * equal to what n_locally_owned_dofs() returns. If only one processor
    * participates in storing the current mesh, then this equals the total
-   * number of degrees of freedom, i.e. the result of n_dofs(). The
-   * contents of this array are the new global indices for each freedom
-   * listed in the IndexSet returned by locally_owned_dofs(). In the case
-   * of a sequential mesh this means that the array is a list of new
-   * indices for each of the degrees of freedom on the current mesh. In the
-   * case that we have a parallel::distributed::Triangulation underlying
-   * this DoFHandler object, the array is a list of new indices for all the
-   * locally owned degrees of freedom, enumerated in the same order as the
-   * currently locally owned DoFs. In other words, assume that degree of
-   * freedom <code>i</code> is currently locally owned, then
+   * number of degrees of freedom, i.e. the result of n_dofs(). The contents
+   * of this array are the new global indices for each freedom listed in the
+   * IndexSet returned by locally_owned_dofs(). In the case of a sequential
+   * mesh this means that the array is a list of new indices for each of the
+   * degrees of freedom on the current mesh. In the case that we have a
+   * parallel::distributed::Triangulation underlying this DoFHandler object,
+   * the array is a list of new indices for all the locally owned degrees of
+   * freedom, enumerated in the same order as the currently locally owned
+   * DoFs. In other words, assume that degree of freedom <code>i</code> is
+   * currently locally owned, then
    * <code>new_numbers[locally_owned_dofs().index_within_set(i)]</code>
-   * returns the new global DoF index of <code>i</code>. Since the IndexSet
-   * of locally_owned_dofs() is complete in the sequential case, the latter
-   * convention for the content of the array reduces to the former in the
-   * case that only one processor participates in the mesh.
+   * returns the new global DoF index of <code>i</code>. Since the IndexSet of
+   * locally_owned_dofs() is complete in the sequential case, the latter
+   * convention for the content of the array reduces to the former in the case
+   * that only one processor participates in the mesh.
    */
   void renumber_dofs (const std::vector<types::global_dof_index> &new_numbers);
 
@@ -435,42 +424,42 @@ public:
   /**
    * Return the maximum number of degrees of freedom a degree of freedom in
    * the given triangulation with the given finite element may couple with.
-   * This is the maximum number of entries per line in the system matrix;
-   * this information can therefore be used upon construction of the
+   * This is the maximum number of entries per line in the system matrix; this
+   * information can therefore be used upon construction of the
    * SparsityPattern object.
    *
    * The returned number is not really the maximum number but an estimate
-   * based on the finite element and the maximum number of cells meeting at
-   * vertex. The number holds for the constrained matrix as well.
+   * based on the finite element and the maximum number of cells meeting at a
+   * vertex. The number holds for the constrained matrix as well.
    *
    * The determination of the number of couplings can be done by simple
    * picture drawing. An example can be found in the implementation of this
    * function.
    *
    * @note This function is most often used to determine the maximal row
-   * length for sparsity patterns. Unfortunately, while the estimates
-   * returned by this function are rather accurate in 1d and 2d, they are
-   * often significantly too high in 3d, leading the SparsityPattern class
-   * to allocate much too much memory in some cases. Unless someone comes
-   * around to improving the present function for 3d, there is not very
-   * much one can do about these cases. The typical way to work around this
-   * problem is to use an intermediate compressed sparsity pattern that
-   * only allocates memory on demand. Refer to the step-2 and step-11
-   * example programs on how to do this. The problem is also discussed in
-   * the documentation of the module on @ref Sparsity.
+   * length for sparsity patterns. Unfortunately, while the estimates returned
+   * by this function are rather accurate in 1d and 2d, they are often
+   * significantly too high in 3d, leading the SparsityPattern class to
+   * allocate much too much memory in some cases. Unless someone comes around
+   * to improving the present function for 3d, there is not very much one can
+   * do about these cases. The typical way to work around this problem is to
+   * use an intermediate compressed sparsity pattern that only allocates
+   * memory on demand. Refer to the step-2 and step-11 example programs on how
+   * to do this. The problem is also discussed in the documentation of the
+   * module on @ref Sparsity.
    */
   unsigned int max_couplings_between_dofs () const;
 
   /**
-   * Return the number of degrees of freedom located on the boundary
-   * another dof on the boundary can couple with.
+   * Return the number of degrees of freedom located on the boundary another
+   * dof on the boundary can couple with.
    *
    * The number is the same as for max_couplings_between_dofs() in one
    * dimension less.
    *
-   * @note The same applies to this function as to max_couplings_per_dofs()
-   * as regards the performance of this function. Think about one of the
-   * dynamic sparsity pattern classes instead (see @ref Sparsity).
+   * @note The same applies to this function as to max_couplings_per_dofs() as
+   * regards the performance of this function. Think about one of the dynamic
+   * sparsity pattern classes instead (see @ref Sparsity).
    */
   unsigned int max_couplings_between_boundary_dofs () const;
 
@@ -490,34 +479,34 @@ public:
   cell_iterator        begin       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active cell on level @p level. If the
-   *  given level does not contain any active cells (i.e., all cells
-   *  on this level are further refined, then this function returns
-   *  <code>end_active(level)</code> so that loops of the kind
+   * Iterator to the first active cell on level @p level. If the given level
+   * does not contain any active cells (i.e., all cells on this level are
+   * further refined, then this function returns
+   * <code>end_active(level)</code> so that loops of the kind
    *  @code
    *    for (cell=dof_handler.begin_active(level); cell!=dof_handler.end_active(level); ++cell)
    *      ...
    *  @endcode
-   *  have zero iterations, as may be expected if there are no active
-   *  cells on this level.
+   * have zero iterations, as may be expected if there are no active cells on
+   * this level.
    */
   active_cell_iterator begin_active(const unsigned int level = 0) const;
 
   /**
-   * Iterator past the end; this iterator serves for comparisons of
-   * iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   cell_iterator        end () const;
 
   /**
-   * Return an iterator which is the first iterator not on the given level.
-   * If @p level is the last level, then this returns <tt>end()</tt>.
+   * Return an iterator which is the first iterator not on the given level. If
+   * @p level is the last level, then this returns <tt>end()</tt>.
    */
   cell_iterator end (const unsigned int level) const;
 
   /**
-   * Return an active iterator which is the first active iterator not on
-   * the given level. If @p level is the last level, then this returns
+   * Return an active iterator which is the first active iterator not on the
+   * given level. If @p level is the last level, then this returns
    * <tt>end()</tt>.
    */
   active_cell_iterator end_active (const unsigned int level) const;
@@ -525,33 +514,31 @@ public:
 
   /**
    * Iterator to the first used cell on level @p level. This returns a
-   * level_cell_iterator that returns level dofs when dof_indices() is
-   * called.
+   * level_cell_iterator that returns level dofs when dof_indices() is called.
    */
   level_cell_iterator begin_mg (const unsigned int level = 0) const;
 
   /**
    * Iterator past the last cell on level @p level. This returns a
-   * level_cell_iterator that returns level dofs when dof_indices() is
-   * called.
+   * level_cell_iterator that returns level dofs when dof_indices() is called.
    */
   level_cell_iterator end_mg (const unsigned int level) const;
 
   /**
-   * Iterator past the end; this iterator serves for comparisons of
-   * iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   level_cell_iterator end_mg () const;
 
   /**
-   *  @name Cell iterator functions returning ranges of iterators
+   * @name Cell iterator functions returning ranges of iterators
    */
 
   /**
    * Return an iterator range that contains all cells (active or not) that
-   * make up this DoFHandler. Such a range is useful to initialize
-   * range-based for loops as supported by C++11. See the example in the
-   * documentation of active_cell_iterators().
+   * make up this DoFHandler. Such a range is useful to initialize range-based
+   * for loops as supported by C++11. See the example in the documentation of
+   * active_cell_iterators().
    *
    * @return The half open range <code>[this->begin(), this->end())</code>
    *
@@ -560,16 +547,15 @@ public:
   IteratorRange<cell_iterator>        cell_iterators () const;
 
   /**
-   * Return an iterator range that contains all active cells
-   * that make up this DoFHandler. Such a range is useful to
-   * initialize range-based for loops as supported by C++11,
-   * see also @ref CPP11 "C++11 standard".
+   * Return an iterator range that contains all active cells that make up this
+   * DoFHandler. Such a range is useful to initialize range-based for loops as
+   * supported by C++11, see also @ref CPP11 "C++11 standard".
    *
-   * Range-based for loops are useful in that they require much less
-   * code than traditional loops (see
-   * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
-   * for a discussion of how they work). An example is that without
-   * range-based for loops, one often writes code such as the following:
+   * Range-based for loops are useful in that they require much less code than
+   * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
+   * #Range-based_for_loop">here</a> for a discussion of how they work). An
+   * example is that without range-based for loops, one often writes code such
+   * as the following:
    * @code
    *   DoFHandler<dim> dof_handler;
    *   ...
@@ -582,8 +568,8 @@ public:
    *       ...do the local integration on 'cell'...;
    *     }
    * @endcode
-   * Using C++11's range-based for loops, this is now entirely
-   * equivalent to the following:
+   * Using C++11's range-based for loops, this is now entirely equivalent to
+   * the following:
    * @code
    *   DoFHandler<dim> dof_handler;
    *   ...
@@ -595,7 +581,8 @@ public:
    * @endcode
    * To use this feature, you need a compiler that supports C++11.
    *
-   * @return The half open range <code>[this->begin_active(), this->end())</code>
+   * @return The half open range <code>[this->begin_active(),
+   * this->end())</code>
    *
    * @ingroup CPP11
    */
@@ -603,26 +590,26 @@ public:
 
   /**
    * Return an iterator range that contains all cells (active or not) that
-   * make up this DoFHandler in their level-cell form. Such a range is
-   * useful to initialize range-based for loops as supported by C++11. See
-   * the example in the documentation of active_cell_iterators().
+   * make up this DoFHandler in their level-cell form. Such a range is useful
+   * to initialize range-based for loops as supported by C++11. See the
+   * example in the documentation of active_cell_iterators().
    *
-   * @return The half open range <code>[this->begin_mg(), this->end_mg())</code>
+   * @return The half open range <code>[this->begin_mg(),
+   * this->end_mg())</code>
    *
    * @ingroup CPP11
    */
   IteratorRange<level_cell_iterator>  mg_cell_iterators () const;
 
   /**
-   * Return an iterator range that contains all cells (active or not)
-   * that make up the given level of this DoFHandler. Such a range is useful to
-   * initialize range-based for loops as supported by C++11. See the
-   * example in the documentation of active_cell_iterators().
+   * Return an iterator range that contains all cells (active or not) that
+   * make up the given level of this DoFHandler. Such a range is useful to
+   * initialize range-based for loops as supported by C++11. See the example
+   * in the documentation of active_cell_iterators().
    *
    * @param[in] level A given level in the refinement hierarchy of this
-   *   triangulation.
-   * @return The half open range <code>[this->begin(level),
-   *   this->end(level))</code>
+   * triangulation. @return The half open range <code>[this->begin(level),
+   * this->end(level))</code>
    *
    * @pre level must be less than this->n_levels().
    *
@@ -631,14 +618,14 @@ public:
   IteratorRange<cell_iterator>        cell_iterators_on_level (const unsigned int level) const;
 
   /**
-   * Return an iterator range that contains all active cells that make up
-   * the given level of this DoFHandler. Such a range is useful to
-   * initialize range-based for loops as supported by C++11. See the
-   * example in the documentation of active_cell_iterators().
+   * Return an iterator range that contains all active cells that make up the
+   * given level of this DoFHandler. Such a range is useful to initialize
+   * range-based for loops as supported by C++11. See the example in the
+   * documentation of active_cell_iterators().
    *
    * @param[in] level A given level in the refinement hierarchy of this
-   *   triangulation.
-   * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+   * triangulation. @return The half open range
+   * <code>[this->begin_active(level), this->end(level))</code>
    *
    * @pre level must be less than this->n_levels().
    *
@@ -648,14 +635,13 @@ public:
 
   /**
    * Return an iterator range that contains all cells (active or not) that
-   * make up the given level of this DoFHandler in their level-cell form.
-   * Such a range is useful to initialize range-based for loops as
-   * supported by C++11. See the example in the documentation of
-   * active_cell_iterators().
+   * make up the given level of this DoFHandler in their level-cell form. Such
+   * a range is useful to initialize range-based for loops as supported by
+   * C++11. See the example in the documentation of active_cell_iterators().
    *
    * @param[in] level A given level in the refinement hierarchy of this
-   *   triangulation.
-   * @return The half open range <code>[this->begin_mg(level), this->end_mg(level))</code>
+   * triangulation. @return The half open range <code>[this->begin_mg(level),
+   * this->end_mg(level))</code>
    *
    * @pre level must be less than this->n_levels().
    *
@@ -675,27 +661,26 @@ public:
   /**
    * Return the global number of degrees of freedom. If the current object
    * handles all degrees of freedom itself (even if you may intend to solve
-   * your linear system in parallel, such as in step-17 or step-18), then
-   * this number equals the number of locally owned degrees of freedom
-   * since this object doesn't know anything about what you want to do with
-   * it and believes that it owns every degree of freedom it knows about.
+   * your linear system in parallel, such as in step-17 or step-18), then this
+   * number equals the number of locally owned degrees of freedom since this
+   * object doesn't know anything about what you want to do with it and
+   * believes that it owns every degree of freedom it knows about.
    *
    * On the other hand, if this object operates on a
-   * parallel::distributed::Triangulation object, then this function
-   * returns the global number of degrees of freedom, accumulated over all
-   * processors.
+   * parallel::distributed::Triangulation object, then this function returns
+   * the global number of degrees of freedom, accumulated over all processors.
    *
-   * In either case, included in the returned number are those DoFs which
-   * are constrained by hanging nodes, see @ref constraints.
+   * In either case, included in the returned number are those DoFs which are
+   * constrained by hanging nodes, see @ref constraints.
    */
   types::global_dof_index n_dofs () const;
 
   /**
    * The (global) number of multilevel degrees of freedom on a given level.
    *
-   * If no level degrees of freedom have been assigned to this level,
-   * returns numbers::invalid_dof_index. Else returns the number of degrees
-   * of freedom on this level.
+   * If no level degrees of freedom have been assigned to this level, returns
+   * numbers::invalid_dof_index. Else returns the number of degrees of freedom
+   * on this level.
    */
   types::global_dof_index n_dofs (const unsigned int level) const;
 
@@ -722,18 +707,17 @@ public:
   n_boundary_dofs (const std::set<types::boundary_id> &boundary_indicators) const;
 
   /**
-   * Access to an object informing of the block structure of the dof
-   * handler.
+   * Access to an object informing of the block structure of the dof handler.
    *
-   * If an FESystem is used in distribute_dofs(), degrees of freedom
-   * naturally split into several @ref GlossBlock "blocks". For each base
-   * element as many blocks appear as its multiplicity.
+   * If an FESystem is used in distribute_dofs(), degrees of freedom naturally
+   * split into several @ref GlossBlock "blocks". For each base element as
+   * many blocks appear as its multiplicity.
    *
-   * At the end of distribute_dofs(), the number of degrees of freedom in
-   * each block is counted, and stored in a BlockInfo object, which can be
-   * accessed here. In an MGDoFHandler, the same is done on each level.
-   * Additionally, the block structure on each cell can be generated in
-   * this object by calling initialize_local_block_info().
+   * At the end of distribute_dofs(), the number of degrees of freedom in each
+   * block is counted, and stored in a BlockInfo object, which can be accessed
+   * here. In an MGDoFHandler, the same is done on each level. Additionally,
+   * the block structure on each cell can be generated in this object by
+   * calling initialize_local_block_info().
    */
   const BlockInfo &block_info() const;
 
@@ -743,35 +727,34 @@ public:
    *
    * If this is a sequential job, then the result equals that produced by
    * n_dofs(). On the other hand, if we are operating on a
-   * parallel::distributed::Triangulation, then it includes only the
-   * degrees of freedom that the current processor owns. Note that in this
-   * case this does not include all degrees of freedom that have been
-   * distributed on the current processor's image of the mesh: in
-   * particular, some of the degrees of freedom on the interface between
-   * the cells owned by this processor and cells owned by other processors
-   * may be theirs, and degrees of freedom on ghost cells are also not
-   * necessarily included.
+   * parallel::distributed::Triangulation, then it includes only the degrees
+   * of freedom that the current processor owns. Note that in this case this
+   * does not include all degrees of freedom that have been distributed on the
+   * current processor's image of the mesh: in particular, some of the degrees
+   * of freedom on the interface between the cells owned by this processor and
+   * cells owned by other processors may be theirs, and degrees of freedom on
+   * ghost cells are also not necessarily included.
    */
   unsigned int n_locally_owned_dofs() const;
 
   /**
-   * Return an IndexSet describing the set of locally owned DoFs as a
-   * subset of 0..n_dofs(). The number of elements of this set equals
+   * Return an IndexSet describing the set of locally owned DoFs as a subset
+   * of 0..n_dofs(). The number of elements of this set equals
    * n_locally_owned_dofs().
    */
   const IndexSet &locally_owned_dofs() const;
 
   /**
-   * Returns an IndexSet describing the set of locally owned DoFs used for
-   * the given multigrid level as a subset of 0..n_dofs(level).
+   * Returns an IndexSet describing the set of locally owned DoFs used for the
+   * given multigrid level as a subset of 0..n_dofs(level).
    */
   const IndexSet &locally_owned_mg_dofs(const unsigned int level) const;
 
 
   /**
-   * Returns a vector that stores the locally owned DoFs of each processor.
-   * If you are only interested in the number of elements each processor
-   * owns then n_locally_owned_dofs_per_processor() is a better choice.
+   * Returns a vector that stores the locally owned DoFs of each processor. If
+   * you are only interested in the number of elements each processor owns
+   * then n_locally_owned_dofs_per_processor() is a better choice.
    *
    * If this is a sequential job, then the vector has a single element that
    * equals the IndexSet representing the entire range [0,n_dofs()].
@@ -784,16 +767,15 @@ public:
 
   /**
    * Return a vector that stores the number of degrees of freedom each
-   * processor that participates in this triangulation owns locally. The
-   * sum of all these numbers equals the number of degrees of freedom that
-   * exist globally, i.e. what n_dofs() returns.
+   * processor that participates in this triangulation owns locally. The sum
+   * of all these numbers equals the number of degrees of freedom that exist
+   * globally, i.e. what n_dofs() returns.
    *
-   * Each element of the vector returned by this function equals the number
-   * of elements of the corresponding sets returned by
-   * global_dof_indices().
+   * Each element of the vector returned by this function equals the number of
+   * elements of the corresponding sets returned by global_dof_indices().
    *
-   * If this is a sequential job, then the vector has a single element
-   * equal to n_dofs().
+   * If this is a sequential job, then the vector has a single element equal
+   * to n_dofs().
    */
   const std::vector<types::global_dof_index> &
   n_locally_owned_dofs_per_processor () const;
@@ -804,8 +786,7 @@ public:
   const FiniteElement<dim,spacedim> &get_fe () const;
 
   /**
-   * Return a constant reference to the triangulation underlying this
-   * object.
+   * Return a constant reference to the triangulation underlying this object.
    */
   const Triangulation<dim,spacedim> &get_tria () const;
 
@@ -874,8 +855,7 @@ public:
    */
   DeclException0 (ExcFacesHaveNoLevel);
   /**
-   * The triangulation level you
-   * accessed is empty.
+   * The triangulation level you accessed is empty.
    * @ingroup Exceptions
    */
   DeclException1 (ExcEmptyLevel,
@@ -886,18 +866,18 @@ public:
 
 private:
   /**
-   * Copy constructor. I can see no reason why someone might want to use
-   * it, so I don't provide it. Since this class has pointer members,
-   * making it private prevents the compiler to provide it's own, incorrect
-   * one if anyone chose to copy such an object.
+   * Copy constructor. I can see no reason why someone might want to use it,
+   * so I don't provide it. Since this class has pointer members, making it
+   * private prevents the compiler to provide it's own, incorrect one if
+   * anyone chose to copy such an object.
    */
   DoFHandler (const DoFHandler &);
 
   /**
-   * Copy operator. I can see no reason why someone might want to use it,
-   * so I don't provide it. Since this class has pointer members, making it
-   * private prevents the compiler to provide it's own, incorrect one if
-   * anyone chose to copy such an object.
+   * Copy operator. I can see no reason why someone might want to use it, so I
+   * don't provide it. Since this class has pointer members, making it private
+   * prevents the compiler to provide it's own, incorrect one if anyone chose
+   * to copy such an object.
    */
   DoFHandler &operator = (const DoFHandler &);
 
@@ -914,19 +894,19 @@ private:
   tria;
 
   /**
-   * Store a pointer to the finite element given latest for the
-   * distribution of dofs. In order to avoid destruction of the object
-   * before the lifetime of the DoF handler, we subscribe to the finite
-   * element object. To unlock the FE before the end of the lifetime of
-   * this DoF handler, use the <tt>clear()</tt> function (this clears all
-   * data of this object as well, though).
+   * Store a pointer to the finite element given latest for the distribution
+   * of dofs. In order to avoid destruction of the object before the lifetime
+   * of the DoF handler, we subscribe to the finite element object. To unlock
+   * the FE before the end of the lifetime of this DoF handler, use the
+   * <tt>clear()</tt> function (this clears all data of this object as well,
+   * though).
    */
   SmartPointer<const FiniteElement<dim,spacedim>,DoFHandler<dim,spacedim> >
   selected_fe;
 
   /**
-   * An object that describes how degrees of freedom should be distributed
-   * and renumbered.
+   * An object that describes how degrees of freedom should be distributed and
+   * renumbered.
    */
   std_cxx11::shared_ptr<dealii::internal::DoFHandler::Policy::PolicyBase<dim,spacedim> > policy;
 
@@ -934,8 +914,8 @@ private:
    * A structure that contains all sorts of numbers that characterize the
    * degrees of freedom this object works on.
    *
-   * For most members of this structure, there is an accessor function in
-   * this class that returns its value.
+   * For most members of this structure, there is an accessor function in this
+   * class that returns its value.
    */
   dealii::internal::DoFHandler::NumberCache number_cache;
 
@@ -945,10 +925,10 @@ private:
   std::vector<dealii::internal::DoFHandler::NumberCache> mg_number_cache;
 
   /**
-   * A data structure that is used to store the DoF indices associated with
-   * a particular vertex. Unlike cells, vertices live on several levels of
-   * a multigrid hierarchy; consequently, we need to store DoF indices for
-   * each vertex for each of the levels it lives on. This class does this.
+   * A data structure that is used to store the DoF indices associated with a
+   * particular vertex. Unlike cells, vertices live on several levels of a
+   * multigrid hierarchy; consequently, we need to store DoF indices for each
+   * vertex for each of the levels it lives on. This class does this.
    */
   class MGVertexDoFs
   {
@@ -964,9 +944,9 @@ private:
     ~MGVertexDoFs ();
 
     /**
-     * A function that is called to allocate the necessary amount of memory
-     * to store the indices of the DoFs that live on this vertex for the
-     * given (inclusive) range of levels.
+     * A function that is called to allocate the necessary amount of memory to
+     * store the indices of the DoFs that live on this vertex for the given
+     * (inclusive) range of levels.
      */
     void init (const unsigned int coarsest_level,
                const unsigned int finest_level,
@@ -983,8 +963,8 @@ private:
     unsigned int get_finest_level () const;
 
     /**
-     * Return the index of the <code>dof_number</code>th degree of freedom
-     * for the given level stored for the current vertex.
+     * Return the index of the <code>dof_number</code>th degree of freedom for
+     * the given level stored for the current vertex.
      */
     types::global_dof_index
     get_index (const unsigned int level,
@@ -1015,15 +995,15 @@ private:
     unsigned int finest_level;
 
     /**
-     * A pointer to an array where we store the indices of the DoFs that
-     * live on the various levels this vertex exists on.
+     * A pointer to an array where we store the indices of the DoFs that live
+     * on the various levels this vertex exists on.
      */
     types::global_dof_index *indices;
 
     /**
      * This array stores, for each level starting with coarsest_level, the
-     * offset in the <code>indices</code> array where the DoF indices for
-     * each level are stored.
+     * offset in the <code>indices</code> array where the DoF indices for each
+     * level are stored.
      */
     types::global_dof_index *indices_offset;
   };
@@ -1062,8 +1042,8 @@ private:
   std::vector<MGVertexDoFs> mg_vertex_dofs;
 
   /**
-   * Space to store the DoF numbers for the different levels. Analogous to
-   * the <tt>levels[]</tt> tree of the Triangulation objects.
+   * Space to store the DoF numbers for the different levels. Analogous to the
+   * <tt>levels[]</tt> tree of the Triangulation objects.
    */
   std::vector<dealii::internal::DoFHandler::DoFLevel<dim>*> levels;
 
@@ -1223,8 +1203,8 @@ namespace internal
 {
   /**
    * returns a string representing the dynamic type of the given argument.
-   * This is basically the same what typeid(...).name() does, but it turns
-   * out this is broken on Intel 13+.
+   * This is basically the same what typeid(...).name() does, but it turns out
+   * this is broken on Intel 13+.
    *
    * Defined in dof_handler.cc.
    */
index 798a7d70c6cfe98bccb53126128264676b2b8c3d..d4c117afefb3ae302dd9abb60f7cb7082647ecdc 100644 (file)
@@ -39,20 +39,17 @@ namespace internal
     struct NumberCache;
 
     /**
-     * A namespace in which we define
-     * classes that describe how to
-     * distribute and renumber
-     * degrees of freedom.
+     * A namespace in which we define classes that describe how to distribute
+     * and renumber degrees of freedom.
      */
     namespace Policy
     {
       struct Implementation;
 
       /**
-       * A class that implements policies for
-       * how the DoFHandler::distribute_dofs
-       * and DoFHandler::renumber_dofs
-       * functions should work.
+       * A class that implements policies for how the
+       * DoFHandler::distribute_dofs and DoFHandler::renumber_dofs functions
+       * should work.
        */
       template <int dim, int spacedim>
       class PolicyBase
@@ -64,8 +61,7 @@ namespace internal
         virtual ~PolicyBase ();
 
         /**
-         * Distribute degrees of freedom on
-         * the object given as last argument.
+         * Distribute degrees of freedom on the object given as last argument.
          */
         virtual
         NumberCache
@@ -80,8 +76,7 @@ namespace internal
                             std::vector<NumberCache> &number_caches) const = 0;
 
         /**
-         * Renumber degrees of freedom as
-         * specified by the first argument.
+         * Renumber degrees of freedom as specified by the first argument.
          */
         virtual
         NumberCache
@@ -91,18 +86,15 @@ namespace internal
 
 
       /**
-       * This class implements the
-       * default policy for sequential
-       * operations, i.e. for the case where
-       * all cells get degrees of freedom.
+       * This class implements the default policy for sequential operations,
+       * i.e. for the case where all cells get degrees of freedom.
        */
       template <int dim, int spacedim>
       class Sequential : public PolicyBase<dim,spacedim>
       {
       public:
         /**
-         * Distribute degrees of freedom on
-         * the object given as last argument.
+         * Distribute degrees of freedom on the object given as last argument.
          */
         virtual
         NumberCache
@@ -117,8 +109,7 @@ namespace internal
                             std::vector<NumberCache> &number_caches) const;
 
         /**
-         * Renumber degrees of freedom as
-         * specified by the first argument.
+         * Renumber degrees of freedom as specified by the first argument.
          */
         virtual
         NumberCache
@@ -128,19 +119,15 @@ namespace internal
 
 
       /**
-       * This class implements the
-       * policy for operations when
-       * we use a
-       * parallel::distributed::Triangulation
-       * object.
+       * This class implements the policy for operations when we use a
+       * parallel::distributed::Triangulation object.
        */
       template <int dim, int spacedim>
       class ParallelDistributed : public PolicyBase<dim,spacedim>
       {
       public:
         /**
-         * Distribute degrees of freedom on
-         * the object given as last argument.
+         * Distribute degrees of freedom on the object given as last argument.
          */
         virtual
         NumberCache
@@ -155,8 +142,7 @@ namespace internal
                             std::vector<NumberCache> &number_caches) const;
 
         /**
-         * Renumber degrees of freedom as
-         * specified by the first argument.
+         * Renumber degrees of freedom as specified by the first argument.
          */
         virtual
         NumberCache
index 124d64daf75259afe8f895465826d9f21b0585dc..dd66957e7b0a84816a6d30da6f7218664fd136eb 100644 (file)
@@ -50,7 +50,8 @@ namespace internal
      * templates is a little more complicated. See the @ref Iterators module
      * for more information.
      *
-     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+     * 2003, 2008, 2010
      */
     template <template <int, int> class DH, int spacedim, bool lda>
     struct Iterators<DH<1, spacedim>, lda>
@@ -91,7 +92,8 @@ namespace internal
      * templates is a little more complicated. See the @ref Iterators module
      * for more information.
      *
-     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+     * 2003, 2008, 2010
      */
     template <template <int, int> class DH, int spacedim, bool lda>
     struct Iterators<DH<2, spacedim>, lda>
@@ -132,7 +134,8 @@ namespace internal
      * templates is a little more complicated. See the @ref Iterators module
      * for more information.
      *
-     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+     * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+     * 2003, 2008, 2010
      */
     template <template <int, int> class DH, int spacedim, bool lda>
     struct Iterators<DH<3, spacedim>, lda>
index eaf9ea1fc986912d56f3b768a6de882b3b446e92..32ac4b7180492913e4b36be3e6956d0cd811cdcb 100644 (file)
@@ -37,30 +37,30 @@ namespace internal
      * Structure for storing degree of freedom information for cells,
      * organized by levels.
      *
-     * We store are cached values for the DoF indices on
-     * each cell in#cell_dof_indices_cache, since this is a frequently requested operation. The
-     * values are set by DoFCellAccessor::update_cell_dof_indices_cache
-     * and are used by DoFCellAccessor::get_dof_indices.
+     * We store are cached values for the DoF indices on each cell
+     * in#cell_dof_indices_cache, since this is a frequently requested
+     * operation. The values are set by
+     * DoFCellAccessor::update_cell_dof_indices_cache and are used by
+     * DoFCellAccessor::get_dof_indices.
      *
-     * Note that vertices are separate from, and in fact have nothing to
-     * do with cells. The indices of degrees of freedom located on
-     * vertices therefore are not stored here, but rather in member
-     * variables of the dealii::DoFHandler class.
+     * Note that vertices are separate from, and in fact have nothing to do
+     * with cells. The indices of degrees of freedom located on vertices
+     * therefore are not stored here, but rather in member variables of the
+     * dealii::DoFHandler class.
      *
-     * The indices of degrees of freedom located on lower dimensional
-     * objects, i.e. on lines for 2D and on quads and lines for 3D are
-     * treated similarly than that on cells. However, these geometrical
-     * objects, which are called faces as a generalisation, are not
-     * organised in a hierarchical structure of levels. Therefore, the
-     * degrees of freedom located on these objects are stored in separate
-     * classes, namely the <tt>DoFFaces</tt> classes.
+     * The indices of degrees of freedom located on lower dimensional objects,
+     * i.e. on lines for 2D and on quads and lines for 3D are treated
+     * similarly than that on cells. However, these geometrical objects, which
+     * are called faces as a generalisation, are not organised in a
+     * hierarchical structure of levels. Therefore, the degrees of freedom
+     * located on these objects are stored in separate classes, namely the
+     * <tt>DoFFaces</tt> classes.
      *
-     * Access to this object is usually
-     * through the DoFAccessor::set_dof_index() and
-     * DoFAccessor::dof_index() functions or similar functions of derived
-     * classes that in turn access the member variables using the
-     * DoFHandler::get_dof_index() and corresponding setter functions.
-     * Knowledge of the actual data format is therefore
+     * Access to this object is usually through the
+     * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+     * similar functions of derived classes that in turn access the member
+     * variables using the DoFHandler::get_dof_index() and corresponding
+     * setter functions. Knowledge of the actual data format is therefore
      * encapsulated to the present hierarchy of classes as well as the
      * dealii::DoFHandler class.
      *
@@ -71,44 +71,38 @@ namespace internal
     {
     public:
       /**
-       * Cache for the DoF indices
-       * on cells. The size of this
-       * array equals the number of
-       * cells on a given level
-       * times
-       * selected_fe.dofs_per_cell.
+       * Cache for the DoF indices on cells. The size of this array equals the
+       * number of cells on a given level times selected_fe.dofs_per_cell.
        */
       std::vector<types::global_dof_index> cell_dof_indices_cache;
 
       /**
-       * The object containing dof-indices
-       * and related access-functions
+       * The object containing dof-indices and related access-functions
        */
       DoFObjects<dim> dof_object;
 
       /**
-       * Return a pointer to the beginning of the DoF indices cache
-       * for a given cell.
+       * Return a pointer to the beginning of the DoF indices cache for a
+       * given cell.
        *
        * @param obj_index The number of the cell we are looking at.
        * @param dofs_per_cell The number of DoFs per cell for this cell.
        * @return A pointer to the first DoF index for the current cell. The
-       *   next dofs_per_cell indices are for the current cell.
+       * next dofs_per_cell indices are for the current cell.
        */
       const types::global_dof_index *
       get_cell_cache_start (const unsigned int obj_index,
                             const unsigned int dofs_per_cell) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
index 8c62a79d801d20a9a236c472a6db5dd22bcafe48..2adab75f921b772f42eb2d2f05b48abc87b1fcb1 100644 (file)
@@ -39,22 +39,20 @@ namespace internal
      *
      * <h3>Information for all DoFObjects classes</h3>
      *
-     * The DoFObjects classes store the global indices of the
-     * degrees of freedom for each cell on a certain level. The global
-     * index or number of a degree of freedom is the zero-based index of
-     * the according value in the solution vector and the row and column
-     * index in the global matrix or the multigrid matrix for this
-     * level. These indices refer to the unconstrained vectors and
-     * matrices, where we have not taken account of the constraints
-     * introduced by hanging nodes.
+     * The DoFObjects classes store the global indices of the degrees of
+     * freedom for each cell on a certain level. The global index or number of
+     * a degree of freedom is the zero-based index of the according value in
+     * the solution vector and the row and column index in the global matrix
+     * or the multigrid matrix for this level. These indices refer to the
+     * unconstrained vectors and matrices, where we have not taken account of
+     * the constraints introduced by hanging nodes.
      *
-     * Since vertices are not associated with a particular level, the
-     * indices associated with vertices are not stored in the DoFObjects
-     * classes but rather in the DoFHandler::vertex_dofs array.
+     * Since vertices are not associated with a particular level, the indices
+     * associated with vertices are not stored in the DoFObjects classes but
+     * rather in the DoFHandler::vertex_dofs array.
      *
-     * The DoFObjects classes are not used directly, but objects
-     * of theses classes are included in the DoFLevel and
-     * DoFFaces classes.
+     * The DoFObjects classes are not used directly, but objects of theses
+     * classes are included in the DoFLevel and DoFFaces classes.
      *
      * @ingroup dofs
      * @author Tobias Leicht, 2006
@@ -64,38 +62,23 @@ namespace internal
     {
     public:
       /**
-       * Store the global indices of
-       * the degrees of freedom.
+       * Store the global indices of the degrees of freedom.
        */
       std::vector<types::global_dof_index> dofs;
 
     public:
       /**
-       * Set the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index to the value
-       * given by the last
-       * argument. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Set the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index to the value given by
+       * the last argument. The @p dof_handler argument is used to access the
+       * finite element that is to be used to compute the location where this
+       * data is stored.
        *
-       * The third argument, @p
-       * fe_index, must equal
-       * zero. It is otherwise
-       * unused, but we retain the
-       * argument so that we can
-       * use the same interface for
-       * non-hp and hp finite
-       * element methods, in effect
-       * making it possible to
-       * share the DoFAccessor
-       * class hierarchy between hp
-       * and non-hp classes.
+       * The third argument, @p fe_index, must equal zero. It is otherwise
+       * unused, but we retain the argument so that we can use the same
+       * interface for non-hp and hp finite element methods, in effect making
+       * it possible to share the DoFAccessor class hierarchy between hp and
+       * non-hp classes.
        */
       template <int dh_dim, int spacedim>
       void
@@ -106,29 +89,16 @@ namespace internal
                      const types::global_dof_index       global_index);
 
       /**
-       * Return the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Return the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index. The @p dof_handler
+       * argument is used to access the finite element that is to be used to
+       * compute the location where this data is stored.
        *
-       * The third argument, @p
-       * fe_index, must equal
-       * zero. It is otherwise
-       * unused, but we retain the
-       * argument so that we can
-       * use the same interface for
-       * non-hp and hp finite
-       * element methods, in effect
-       * making it possible to
-       * share the DoFAccessor
-       * class hierarchy between hp
-       * and non-hp classes.
+       * The third argument, @p fe_index, must equal zero. It is otherwise
+       * unused, but we retain the argument so that we can use the same
+       * interface for non-hp and hp finite element methods, in effect making
+       * it possible to share the DoFAccessor class hierarchy between hp and
+       * non-hp classes.
        */
       template <int dh_dim, int spacedim>
       types::global_dof_index
@@ -138,11 +108,8 @@ namespace internal
                      const unsigned int       local_index) const;
 
       /**
-       * Return the value 1. The
-       * meaning of this function
-       * becomes clear by looking
-       * at what the corresponding
-       * functions in the classes
+       * Return the value 1. The meaning of this function becomes clear by
+       * looking at what the corresponding functions in the classes
        * internal::hp::DoFObjects
        */
       template <int dh_dim, int spacedim>
@@ -151,10 +118,8 @@ namespace internal
                            const types::global_dof_index       index) const;
 
       /**
-       * Similar to the function
-       * above. Assert that the
-       * given index is zero, and
-       * then return true.
+       * Similar to the function above. Assert that the given index is zero,
+       * and then return true.
        */
       template <int dh_dim, int spacedim>
       bool
@@ -163,26 +128,22 @@ namespace internal
                           const unsigned int       fe_index) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
                      const unsigned int version);
 
       /**
-       * Make the DoFHandler and
-       * MGDoFHandler classes a
-       * friend, so that they can
-       * resize arrays as
-       * necessary.
+       * Make the DoFHandler and MGDoFHandler classes a friend, so that they
+       * can resize arrays as necessary.
        */
       template <int> friend class DoFLevel;
       template <int> friend class DoFFaces;
index 44283fe6a4926663ac5e892dd597f0a574532d45..aac872454bf51bf78fd751cf033c24b7f7b3f10e 100644 (file)
@@ -34,96 +34,89 @@ DEAL_II_NAMESPACE_OPEN
  *
  * <h3>Cuthill-McKee like algorithms</h3>
  *
- * Within this class, the Cuthill-McKee algorithm is implemented. It
- * starts at a degree of freedom, searches the other DoFs for those
- * which are coupled with the one we started with and numbers these in
- * a certain way. It then finds the second level of DoFs, namely those
- * that couple with those of the previous level (which were those that
- * coupled with the initial DoF) and numbers these. And so on. For the
- * details of the algorithm, especially the numbering within each
- * level, please see H. R. Schwarz:
- * "Methode der finiten Elemente". The reverse Cuthill-McKee algorithm
- * does the same job, but numbers all elements in the reverse order.
+ * Within this class, the Cuthill-McKee algorithm is implemented. It starts at
+ * a degree of freedom, searches the other DoFs for those which are coupled
+ * with the one we started with and numbers these in a certain way. It then
+ * finds the second level of DoFs, namely those that couple with those of the
+ * previous level (which were those that coupled with the initial DoF) and
+ * numbers these. And so on. For the details of the algorithm, especially the
+ * numbering within each level, please see H. R. Schwarz: "Methode der finiten
+ * Elemente". The reverse Cuthill-McKee algorithm does the same job, but
+ * numbers all elements in the reverse order.
  *
  * These algorithms have one major drawback: they require a good starting
- * point, i.e. the degree of freedom index that will get a new index of
- * zero. The renumbering functions therefore allow the caller to specify such
- * an initial DoF, e.g. by exploiting knowledge of the actual topology of the
+ * point, i.e. the degree of freedom index that will get a new index of zero.
+ * The renumbering functions therefore allow the caller to specify such an
+ * initial DoF, e.g. by exploiting knowledge of the actual topology of the
  * domain. It is also possible to give several starting indices, which may be
  * used to simulate a simple upstream numbering (by giving the inflow dofs as
  * starting values) or to make preconditioning faster (by letting the
  * Dirichlet boundary indices be starting points).
  *
- * If no starting index is given, one is chosen automatically, namely
- * one with the smallest coordination number (the coordination number
- * is the number of other dofs this dof couples with). This dof is
- * usually located on the boundary of the domain. There is, however,
- * large ambiguity in this when using the hierarchical meshes used in
- * this library, since in most cases the computational domain is not
- * approximated by tilting and deforming elements and by plugging
- * together variable numbers of elements at vertices, but rather by
- * hierarchical refinement. There is therefore a large number of dofs
- * with equal coordination numbers. The renumbering algorithms will
+ * If no starting index is given, one is chosen automatically, namely one with
+ * the smallest coordination number (the coordination number is the number of
+ * other dofs this dof couples with). This dof is usually located on the
+ * boundary of the domain. There is, however, large ambiguity in this when
+ * using the hierarchical meshes used in this library, since in most cases the
+ * computational domain is not approximated by tilting and deforming elements
+ * and by plugging together variable numbers of elements at vertices, but
+ * rather by hierarchical refinement. There is therefore a large number of
+ * dofs with equal coordination numbers. The renumbering algorithms will
  * therefore not give optimal results.
  *
- * In the book of Schwarz (H.R.Schwarz: Methode der finiten Elemente),
- * it is advised to test many starting points, if possible all with
- * the smallest coordination number and also those with slightly
- * higher numbers. However, this seems only possible for meshes with
- * at most several dozen or a few hundred elements found in small
- * engineering problems of the early 1980s (the second edition was
- * published in 1984), but certainly not with those used in this
- * library, featuring several 10,000 to a few 100,000 elements.
+ * In the book of Schwarz (H.R.Schwarz: Methode der finiten Elemente), it is
+ * advised to test many starting points, if possible all with the smallest
+ * coordination number and also those with slightly higher numbers. However,
+ * this seems only possible for meshes with at most several dozen or a few
+ * hundred elements found in small engineering problems of the early 1980s
+ * (the second edition was published in 1984), but certainly not with those
+ * used in this library, featuring several 10,000 to a few 100,000 elements.
  *
  *
  * <h4>Implementation of renumbering schemes</h4>
  *
- * The renumbering algorithms need quite a lot of memory, since they
- * have to store for each dof with which other dofs it couples. This
- * is done using a SparsityPattern object used to store the sparsity
- * pattern of matrices. It is not useful for the user to do anything
- * between distributing the dofs and renumbering, i.e. the calls to
- * DoFHandler::distribute_dofs and DoFHandler::renumber_dofs should
- * follow each other immediately. If you try to create a sparsity
- * pattern or anything else in between, these will be invalid
- * afterwards.
+ * The renumbering algorithms need quite a lot of memory, since they have to
+ * store for each dof with which other dofs it couples. This is done using a
+ * SparsityPattern object used to store the sparsity pattern of matrices. It
+ * is not useful for the user to do anything between distributing the dofs and
+ * renumbering, i.e. the calls to DoFHandler::distribute_dofs and
+ * DoFHandler::renumber_dofs should follow each other immediately. If you try
+ * to create a sparsity pattern or anything else in between, these will be
+ * invalid afterwards.
  *
- * The renumbering may take care of dof-to-dof couplings only induced
- * by eliminating constraints. In addition to the memory consumption
- * mentioned above, this also takes quite some computational time, but
- * it may be switched off upon calling the @p renumber_dofs
- * function. This will then give inferior results, since knots in the
- * graph (representing dofs) are not found to be neighbors even if
- * they would be after condensation.
+ * The renumbering may take care of dof-to-dof couplings only induced by
+ * eliminating constraints. In addition to the memory consumption mentioned
+ * above, this also takes quite some computational time, but it may be
+ * switched off upon calling the @p renumber_dofs function. This will then
+ * give inferior results, since knots in the graph (representing dofs) are not
+ * found to be neighbors even if they would be after condensation.
  *
- * The renumbering algorithms work on a purely algebraic basis, due to
- * the isomorphism between the graph theoretical groundwork underlying
- * the algorithms and binary matrices (matrices of which the entries
- * are binary values) represented by the sparsity patterns. In
- * special, the algorithms do not try to exploit topological knowledge
- * (e.g. corner detection) to find appropriate starting points. This
- * way, however, they work in arbitrary space dimension.
+ * The renumbering algorithms work on a purely algebraic basis, due to the
+ * isomorphism between the graph theoretical groundwork underlying the
+ * algorithms and binary matrices (matrices of which the entries are binary
+ * values) represented by the sparsity patterns. In special, the algorithms do
+ * not try to exploit topological knowledge (e.g. corner detection) to find
+ * appropriate starting points. This way, however, they work in arbitrary
+ * space dimension.
  *
- * If you want to give starting points, you may give a list of dof
- * indices which will form the first step of the renumbering. The dofs
- * of the list will be consecutively numbered starting with zero,
- * i.e. this list is not renumbered according to the coordination
- * number of the nodes. Indices not in the allowed range are
- * deleted. If no index is allowed, the algorithm will search for its
- * own starting point.
+ * If you want to give starting points, you may give a list of dof indices
+ * which will form the first step of the renumbering. The dofs of the list
+ * will be consecutively numbered starting with zero, i.e. this list is not
+ * renumbered according to the coordination number of the nodes. Indices not
+ * in the allowed range are deleted. If no index is allowed, the algorithm
+ * will search for its own starting point.
  *
  *
  * <h4>Results of renumbering</h4>
  *
- * The renumbering schemes mentioned above do not lead to optimal
- * results.  However, after all there is no algorithm that
- * accomplishes this within reasonable time. There are situations
- * where the lack of optimality even leads to worse results than with
- * the original, crude, levelwise numbering scheme; one of these
- * examples is a mesh of four cells of which always those cells are
- * refined which are neighbors to the center (you may call this mesh a
- * `zoom in' mesh). In one such example the bandwidth was increased by
- * about 50 per cent.
+ * The renumbering schemes mentioned above do not lead to optimal results.
+ * However, after all there is no algorithm that accomplishes this within
+ * reasonable time. There are situations where the lack of optimality even
+ * leads to worse results than with the original, crude, levelwise numbering
+ * scheme; one of these examples is a mesh of four cells of which always those
+ * cells are refined which are neighbors to the center (you may call this mesh
+ * a `zoom in' mesh). In one such example the bandwidth was increased by about
+ * 50 per cent.
  *
  * In most other cases, the bandwidth is reduced significantly. The reduction
  * is the better the less structured the grid is. With one grid where the
@@ -131,273 +124,215 @@ DEAL_II_NAMESPACE_OPEN
  * was reduced by a factor of six.
  *
  * Using the constraint information usually leads to reductions in bandwidth
- * of 10 or 20 per cent, but may for some very unstructured grids also lead
- * to an increase. You have to weigh the decrease in your case with the time
+ * of 10 or 20 per cent, but may for some very unstructured grids also lead to
+ * an increase. You have to weigh the decrease in your case with the time
  * spent to use the constraint information, which usually is several times
  * longer than the `pure' renumbering algorithm.
  *
  * In almost all cases, the renumbering scheme finds a corner to start with.
  * Since there is more than one corner in most grids and since even an
  * interior degree of freedom may be a better starting point, giving the
- * starting point by the user may be a viable way if you have a simple
- * scheme to derive a suitable point (e.g. by successively taking the
- * third child of the cell top left of the coarsest level, taking its
- * third vertex and the dof index thereof, if you want the top left corner
- * vertex). If you do not know beforehand what your grid will look like
- * (e.g. when using adaptive algorithms), searching a best starting point
- * may be difficult, however, and in many cases will not justify the effort.
+ * starting point by the user may be a viable way if you have a simple scheme
+ * to derive a suitable point (e.g. by successively taking the third child of
+ * the cell top left of the coarsest level, taking its third vertex and the
+ * dof index thereof, if you want the top left corner vertex). If you do not
+ * know beforehand what your grid will look like (e.g. when using adaptive
+ * algorithms), searching a best starting point may be difficult, however, and
+ * in many cases will not justify the effort.
  *
  *
  * <h3>Component-wise and block-wise numberings</h3>
  *
  * For finite elements composed of several base elements using the FESystem
- * class, or for elements which provide several components themselves, it
- * may be of interest to sort the DoF indices by component. This will then
- * bring out the block matrix structure, since otherwise the degrees of freedom
- * are numbered cell-wise without taking into account that they may belong to
- * different components. For example, one may want to sort degree of freedom for
- * a Stokes discretization so that we first get all velocities and then all
- * the pressures so that the resulting matrix naturally decomposes into a
+ * class, or for elements which provide several components themselves, it may
+ * be of interest to sort the DoF indices by component. This will then bring
+ * out the block matrix structure, since otherwise the degrees of freedom are
+ * numbered cell-wise without taking into account that they may belong to
+ * different components. For example, one may want to sort degree of freedom
+ * for a Stokes discretization so that we first get all velocities and then
+ * all the pressures so that the resulting matrix naturally decomposes into a
  * $2\times 2$ system.
  *
- * This kind of numbering may be obtained by calling the
- * component_wise() function of this class. Since it does not touch
- * the order of indices within each component, it may be worthwhile to first
- * renumber using the Cuthill-McKee or a similar algorithm and
- * afterwards renumbering component-wise. This will bring out the
- * matrix structure and additionally have a good numbering within each
- * block.
+ * This kind of numbering may be obtained by calling the component_wise()
+ * function of this class. Since it does not touch the order of indices within
+ * each component, it may be worthwhile to first renumber using the Cuthill-
+ * McKee or a similar algorithm and afterwards renumbering component-wise.
+ * This will bring out the matrix structure and additionally have a good
+ * numbering within each block.
  *
  * The component_wise() function allows not only to honor enumeration based on
  * vector components, but also allows to group together vector components into
- * "blocks" using a defaulted argument to the various DoFRenumber::component_wise()
- * functions (see @ref GlossComponent vs @ref GlossBlock for a description of
- * the difference). The blocks designated through this argument may, but do not
- * have to be, equal to the blocks that the finite element reports. For example,
- * a typical Stokes element would be
+ * "blocks" using a defaulted argument to the various
+ * DoFRenumber::component_wise() functions (see @ref GlossComponent vs @ref
+ * GlossBlock for a description of the difference). The blocks designated
+ * through this argument may, but do not have to be, equal to the blocks that
+ * the finite element reports. For example, a typical Stokes element would be
  * @code
  *   FESystem<dim> stokes_fe (FE_Q<dim>(2), dim,   // dim velocities
  *                            FE_Q<dim>(1), 1);    // one pressure
  * @endcode
  * This element has <code>dim+1</code> vector components and equally many
  * blocks. However, one may want to consider the velocities as one logical
- * block so that all velocity degrees of freedom are enumerated the same
- * way, independent of whether they are $x$- or $y$-velocities. This is done,
- * for example, in step-20 and step-22 as well as several other tutorial programs.
+ * block so that all velocity degrees of freedom are enumerated the same way,
+ * independent of whether they are $x$- or $y$-velocities. This is done, for
+ * example, in step-20 and step-22 as well as several other tutorial programs.
  *
- * On the other hand, if you really want to use block structure reported
- * by the finite element itself (a case that is often the case if you have
- * finite elements that have multiple vector components, e.g. the FE_RaviartThomas
- * or FE_Nedelec elements) then you can use the DoFRenumber::block_wise instead
+ * On the other hand, if you really want to use block structure reported by
+ * the finite element itself (a case that is often the case if you have finite
+ * elements that have multiple vector components, e.g. the FE_RaviartThomas or
+ * FE_Nedelec elements) then you can use the DoFRenumber::block_wise instead
  * of the DoFRenumbering::component_wise functions.
  *
  *
  * <h3>Cell-wise numbering</h3>
  *
- * Given an ordered vector of cells, the function cell_wise()
- * sorts the degrees of freedom such that degrees on earlier cells of
- * this vector will occur before degrees on later cells.
+ * Given an ordered vector of cells, the function cell_wise() sorts the
+ * degrees of freedom such that degrees on earlier cells of this vector will
+ * occur before degrees on later cells.
  *
  * This rule produces a well-defined ordering for discontinuous Galerkin
- * methods (FE_DGP, FE_DGQ). For continuous methods, we use the
- * additional rule that each degree of freedom is ordered according to
- * the first cell in the ordered vector it belongs to.
+ * methods (FE_DGP, FE_DGQ). For continuous methods, we use the additional
+ * rule that each degree of freedom is ordered according to the first cell in
+ * the ordered vector it belongs to.
  *
- * Applications of this scheme are downstream() and
- * clock_wise_dg(). The first orders the cells according to a
- * downstream direction and then applies cell_wise().
+ * Applications of this scheme are downstream() and clock_wise_dg(). The first
+ * orders the cells according to a downstream direction and then applies
+ * cell_wise().
  *
  * @note For DG elements, the internal numbering in each cell remains
- * unaffected. This cannot be guaranteed for continuous elements
- * anymore, since degrees of freedom shared with an earlier cell will
- * be accounted for by the other cell.
+ * unaffected. This cannot be guaranteed for continuous elements anymore,
+ * since degrees of freedom shared with an earlier cell will be accounted for
+ * by the other cell.
  *
  *
  * <h3>Random renumbering</h3>
  *
- * The random() function renumbers degrees of freedom randomly. This
- * function is probably seldom of use, except to check the dependence of
- * solvers (iterative or direct ones) on the numbering of the degrees
- * of freedom. It uses the @p random_shuffle function from the C++
- * standard library to do its work.
+ * The random() function renumbers degrees of freedom randomly. This function
+ * is probably seldom of use, except to check the dependence of solvers
+ * (iterative or direct ones) on the numbering of the degrees of freedom. It
+ * uses the @p random_shuffle function from the C++ standard library to do its
+ * work.
  *
  *
  * <h3>A comparison of reordering strategies</h3>
  *
- * As a benchmark of comparison, let us consider what the different
- * sparsity patterns produced by the various algorithms when using the
- * $Q_2^d\times Q_1$ element combination typically employed in the
- * discretization of Stokes equations, when used on the mesh obtained
- * in step-22 after one adaptive mesh refinement in
- * 3d. The space dimension together with the coupled finite element
- * leads to a rather dense system matrix with, on average around 180
- * nonzero entries per row. After applying each of the reordering
- * strategies shown below, the degrees of freedom are also sorted
- * using DoFRenumbering::component_wise into velocity and pressure
- * groups; this produces the $2\times 2$ block structure seen below
- * with the large velocity-velocity block at top left, small
- * pressure-pressure block at bottom right, and coupling blocks at top
- * right and bottom left.
+ * As a benchmark of comparison, let us consider what the different sparsity
+ * patterns produced by the various algorithms when using the $Q_2^d\times
+ * Q_1$ element combination typically employed in the discretization of Stokes
+ * equations, when used on the mesh obtained in step-22 after one adaptive
+ * mesh refinement in 3d. The space dimension together with the coupled finite
+ * element leads to a rather dense system matrix with, on average around 180
+ * nonzero entries per row. After applying each of the reordering strategies
+ * shown below, the degrees of freedom are also sorted using
+ * DoFRenumbering::component_wise into velocity and pressure groups; this
+ * produces the $2\times 2$ block structure seen below with the large
+ * velocity-velocity block at top left, small pressure-pressure block at
+ * bottom right, and coupling blocks at top right and bottom left.
  *
- * The goal of reordering strategies is to improve the
- * preconditioner. In step-22 we use a SparseILU to
- * preconditioner for the velocity-velocity block at the top left. The
- * quality of the preconditioner can then be measured by the number of
- * CG iterations required to solve a linear system with this
- * block. For some of the reordering strategies below we record this
- * number for adaptive refinement cycle 3, with 93176 degrees of
- * freedom; because we solve several linear systems with the same
- * matrix in the Schur complement, the average number of iterations is
- * reported. The lower the number the better the preconditioner and
- * consequently the better the renumbering of degrees of freedom is
- * suited for this task. We also state the run-time of the program, in
- * part determined by the number of iterations needed, for the first 4
- * cycles on one of our machines. Note that the reported times
- * correspond to the run time of the entire program, not just the
- * affected solver; if a program runs twice as fast with one
- * particular ordering than with another one, then this means that the
- * actual solver is actually several times faster.
+ * The goal of reordering strategies is to improve the preconditioner. In
+ * step-22 we use a SparseILU to preconditioner for the velocity-velocity
+ * block at the top left. The quality of the preconditioner can then be
+ * measured by the number of CG iterations required to solve a linear system
+ * with this block. For some of the reordering strategies below we record this
+ * number for adaptive refinement cycle 3, with 93176 degrees of freedom;
+ * because we solve several linear systems with the same matrix in the Schur
+ * complement, the average number of iterations is reported. The lower the
+ * number the better the preconditioner and consequently the better the
+ * renumbering of degrees of freedom is suited for this task. We also state
+ * the run-time of the program, in part determined by the number of iterations
+ * needed, for the first 4 cycles on one of our machines. Note that the
+ * reported times correspond to the run time of the entire program, not just
+ * the affected solver; if a program runs twice as fast with one particular
+ * ordering than with another one, then this means that the actual solver is
+ * actually several times faster.
  *
- * <table>
- * <tr>
- *   <td>
- *     @image html "reorder_sparsity_step_31_original.png"
- *   </td>
- *   <td>
- *     @image html "reorder_sparsity_step_31_random.png"
- *   </td>
- *   <td>
- *     @image html "reorder_sparsity_step_31_deal_cmk.png"
- *   </td>
- * </tr>
- * <tr>
- *   <td>
- *     Enumeration as produced by deal.II's DoFHandler::distribute_dofs function
- *     and no further reordering apart from the component-wise one.
+ * <table> <tr> <td> @image html "reorder_sparsity_step_31_original.png" </td>
+ * <td> @image html "reorder_sparsity_step_31_random.png" </td> <td> @image
+ * html "reorder_sparsity_step_31_deal_cmk.png" </td> </tr> <tr> <td>
+ * Enumeration as produced by deal.II's DoFHandler::distribute_dofs function
+ * and no further reordering apart from the component-wise one.
  *
- *     With this renumbering, we needed an average of 92.2 iterations for the
- *     testcase outlined above, and a runtime of 7min53s.
- *   </td>
- *   <td>
- *     Random enumeration as produced by applying DoFRenumbering::random
- *     after calling DoFHandler::distribute_dofs. This enumeration produces
- *     nonzero entries in matrices pretty much everywhere, appearing here as
- *     an entirely unstructured matrix.
+ * With this renumbering, we needed an average of 92.2 iterations for the
+ * testcase outlined above, and a runtime of 7min53s. </td> <td> Random
+ * enumeration as produced by applying DoFRenumbering::random after calling
+ * DoFHandler::distribute_dofs. This enumeration produces nonzero entries in
+ * matrices pretty much everywhere, appearing here as an entirely unstructured
+ * matrix.
  *
- *     With this renumbering, we needed an average of 71 iterations for the
- *     testcase outlined above, and a runtime of 10min55s. The longer runtime
- *     despite less iterations compared to the default ordering may be due to
- *     the fact that computing and applying the ILU requires us to jump back
- *     and forth all through memory due to the lack of localization of
- *     matrix entries around the diagonal; this then leads to many cache
- *     misses and consequently bad timings.
- *   </td>
- *   <td>
- *     Cuthill-McKee enumeration as produced by calling the deal.II implementation
- *     of the algorithm provided by DoFRenumbering::Cuthill_McKee
- *     after DoFHandler::distribute_dofs.
+ * With this renumbering, we needed an average of 71 iterations for the
+ * testcase outlined above, and a runtime of 10min55s. The longer runtime
+ * despite less iterations compared to the default ordering may be due to the
+ * fact that computing and applying the ILU requires us to jump back and forth
+ * all through memory due to the lack of localization of matrix entries around
+ * the diagonal; this then leads to many cache misses and consequently bad
+ * timings. </td> <td> Cuthill-McKee enumeration as produced by calling the
+ * deal.II implementation of the algorithm provided by
+ * DoFRenumbering::Cuthill_McKee after DoFHandler::distribute_dofs.
  *
- *     With this renumbering, we needed an average of 57.3 iterations for the
- *     testcase outlined above, and a runtime of 6min10s.
- *   </td>
- *   </td>
- * </tr>
+ * With this renumbering, we needed an average of 57.3 iterations for the
+ * testcase outlined above, and a runtime of 6min10s. </td> </td> </tr>
  *
- * <tr>
- *   <td>
- *     @image html "reorder_sparsity_step_31_boost_cmk.png"
- *   </td>
- *   <td>
- *     @image html "reorder_sparsity_step_31_boost_king.png"
- *   </td>
- *   <td>
- *     @image html "reorder_sparsity_step_31_boost_md.png"
- *   </td>
- * </tr>
- * <tr>
- *   <td>
- *     Cuthill-McKee enumeration as produced by calling the BOOST implementation
- *     of the algorithm provided by DoFRenumbering::boost::Cuthill_McKee
- *     after DoFHandler::distribute_dofs.
+ * <tr> <td> @image html "reorder_sparsity_step_31_boost_cmk.png" </td> <td>
+ * @image html "reorder_sparsity_step_31_boost_king.png" </td> <td> @image
+ * html "reorder_sparsity_step_31_boost_md.png" </td> </tr> <tr> <td> Cuthill-
+ * McKee enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::Cuthill_McKee after
+ * DoFHandler::distribute_dofs.
  *
- *     With this renumbering, we needed an average of 51.7 iterations for the
- *     testcase outlined above, and a runtime of 5min52s.
- *   </td>
- *   <td>
- *     King enumeration as produced by calling the BOOST implementation
- *     of the algorithm provided by DoFRenumbering::boost::king_ordering
- *     after DoFHandler::distribute_dofs. The sparsity pattern appears
- *     denser than with BOOST's Cuthill-McKee algorithm; however, this is
- *     only an illusion: the number of nonzero entries is the same, they are
- *     simply not as well clustered.
+ * With this renumbering, we needed an average of 51.7 iterations for the
+ * testcase outlined above, and a runtime of 5min52s. </td> <td> King
+ * enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::king_ordering after
+ * DoFHandler::distribute_dofs. The sparsity pattern appears denser than with
+ * BOOST's Cuthill-McKee algorithm; however, this is only an illusion: the
+ * number of nonzero entries is the same, they are simply not as well
+ * clustered.
  *
- *     With this renumbering, we needed an average of 51.0 iterations for the
- *     testcase outlined above, and a runtime of 5min03s. Although the number
- *     of iterations is only slightly less than with BOOST's Cuthill-McKee
- *     implementation, runtime is significantly less. This, again, may be due
- *     to cache effects. As a consequence, this is the algorithm best suited
- *     to the testcase, and is in fact used in step-22.
- *   </td>
- *   <td>
- *     Minimum degree enumeration as produced by calling the BOOST implementation
- *     of the algorithm provided by DoFRenumbering::boost::minimum_degree
- *     after DoFHandler::distribute_dofs. The minimum degree algorithm does not
- *     attempt to minimize the bandwidth of a matrix but to minimize the amount
- *     of fill-in a LU decomposition would produce, i.e. the number of places in
- *     the matrix that would be occupied by elements of an LU decomposition that
- *     are not already occupied by elements of the original matrix. The resulting
- *     sparsity pattern obviously has an entirely different structure than the
- *     ones produced by algorithms trying to minimize the bandwidth.
+ * With this renumbering, we needed an average of 51.0 iterations for the
+ * testcase outlined above, and a runtime of 5min03s. Although the number of
+ * iterations is only slightly less than with BOOST's Cuthill-McKee
+ * implementation, runtime is significantly less. This, again, may be due to
+ * cache effects. As a consequence, this is the algorithm best suited to the
+ * testcase, and is in fact used in step-22. </td> <td> Minimum degree
+ * enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::minimum_degree after
+ * DoFHandler::distribute_dofs. The minimum degree algorithm does not attempt
+ * to minimize the bandwidth of a matrix but to minimize the amount of fill-in
+ * a LU decomposition would produce, i.e. the number of places in the matrix
+ * that would be occupied by elements of an LU decomposition that are not
+ * already occupied by elements of the original matrix. The resulting sparsity
+ * pattern obviously has an entirely different structure than the ones
+ * produced by algorithms trying to minimize the bandwidth.
  *
- *     With this renumbering, we needed an average of 58.9 iterations for the
- *     testcase outlined above, and a runtime of 6min11s.
- *   </td>
- * </tr>
+ * With this renumbering, we needed an average of 58.9 iterations for the
+ * testcase outlined above, and a runtime of 6min11s. </td> </tr>
  *
- * <tr>
- *   <td>
- *     @image html "reorder_sparsity_step_31_downstream.png"
- *   </td>
- *   <td>
- *   </td>
- *   <td>
- *   </td>
- * </tr>
- * <tr>
- *   <td>
- *     Downstream enumeration using DoFRenumbering::downstream using a
- *     direction that points diagonally through the domain.
+ * <tr> <td> @image html "reorder_sparsity_step_31_downstream.png" </td> <td>
+ * </td> <td> </td> </tr> <tr> <td> Downstream enumeration using
+ * DoFRenumbering::downstream using a direction that points diagonally through
+ * the domain.
  *
- *     With this renumbering, we needed an average of 90.5 iterations for the
- *     testcase outlined above, and a runtime of 7min05s.
- *   </td>
- *   <td>
- *   </td>
- *   <td>
- *   </td>
- * </tr>
- * </table>
+ * With this renumbering, we needed an average of 90.5 iterations for the
+ * testcase outlined above, and a runtime of 7min05s. </td> <td> </td> <td>
+ * </td> </tr> </table>
  *
  *
  * <h3>Multigrid DoF numbering</h3>
  *
- * Most of the algorithms listed above also work on multigrid degree of freedom
- * numberings. Refer to the actual function declarations to get more
+ * Most of the algorithms listed above also work on multigrid degree of
+ * freedom numberings. Refer to the actual function declarations to get more
  * information on this.
  *
  * @ingroup dofs
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2004, 2007, 2008
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2004, 2007,
+ * 2008
  */
 namespace DoFRenumbering
 {
   /**
-   * Direction based comparator for
-   * cell iterators: it returns @p
-   * true if the center of the second
-   * cell is downstream of the center
-   * of the first one with respect to
-   * the direction given to the
-   * constructor.
+   * Direction based comparator for cell iterators: it returns @p true if the
+   * center of the second cell is downstream of the center of the first one
+   * with respect to the direction given to the constructor.
    */
   template <class Iterator, int dim>
   struct CompareDownstream
@@ -493,9 +428,9 @@ namespace DoFRenumbering
                    const bool                       use_constraints    = false);
 
     /**
-     * Computes the renumbering vector needed by the Cuthill_McKee()
-     * function. Does not perform the renumbering on the DoFHandler dofs but
-     * returns the renumbering vector.
+     * Computes the renumbering vector needed by the Cuthill_McKee() function.
+     * Does not perform the renumbering on the DoFHandler dofs but returns the
+     * renumbering vector.
      */
     template <class DH>
     void
@@ -586,9 +521,9 @@ namespace DoFRenumbering
                  const std::vector<types::global_dof_index> &starting_indices   = std::vector<types::global_dof_index>());
 
   /**
-   * Computes the renumbering vector needed by the Cuthill_McKee()
-   * function. Does not perform the renumbering on the DoFHandler dofs but
-   * returns the renumbering vector.
+   * Computes the renumbering vector needed by the Cuthill_McKee() function.
+   * Does not perform the renumbering on the DoFHandler dofs but returns the
+   * renumbering vector.
    */
   template <class DH>
   void
@@ -633,11 +568,11 @@ namespace DoFRenumbering
    * You can specify that the components are ordered in a different way than
    * suggested by the FESystem object you use. To this end, set up the vector
    * @p target_component such that the entry at index @p i denotes the number
-   * of the target component for dofs with component @p i in the
-   * FESystem. Naming the same target component more than once is possible and
-   * results in a blocking of several components into one. This is discussed
-   * in step-22. If you omit this argument, the same order as given by the
-   * finite element is used.
+   * of the target component for dofs with component @p i in the FESystem.
+   * Naming the same target component more than once is possible and results
+   * in a blocking of several components into one. This is discussed in
+   * step-22. If you omit this argument, the same order as given by the finite
+   * element is used.
    *
    * If one of the base finite elements from which the global finite element
    * under consideration here, is a non-primitive one, i.e. its shape
@@ -648,10 +583,10 @@ namespace DoFRenumbering
    *
    * For finite elements with only one component, or a single non-primitive
    * base element, this function is the identity operation.
-  *
-  * @note A similar function, which renumbered all levels existed for
-  * MGDoFHandler. This function was deleted. Thus, you have to call the level
-  * function for each level now.
+   *
+   * @note A similar function, which renumbered all levels existed for
+   * MGDoFHandler. This function was deleted. Thus, you have to call the level
+   * function for each level now.
    */
   template <int dim, int spacedim>
   void
@@ -671,9 +606,9 @@ namespace DoFRenumbering
 
   /**
    * Sort the degrees of freedom by component. It does the same thing as the
-   * above function, only that it does this for one single level of a
-   * multi-level discretization. The non-multigrid part of the MGDoFHandler is
-   * not touched.
+   * above function, only that it does this for one single level of a multi-
+   * level discretization. The non-multigrid part of the MGDoFHandler is not
+   * touched.
    */
   template <class DH>
   void
@@ -693,9 +628,9 @@ namespace DoFRenumbering
                   const std::vector<unsigned int> &target_component = std::vector<unsigned int>());
 
   /**
-   * Computes the renumbering vector needed by the component_wise()
-   * functions. Does not perform the renumbering on the DoFHandler dofs but
-   * returns the renumbering vector.
+   * Computes the renumbering vector needed by the component_wise() functions.
+   * Does not perform the renumbering on the DoFHandler dofs but returns the
+   * renumbering vector.
    */
   template <int dim, int spacedim, class ITERATOR, class ENDITERATOR>
   types::global_dof_index
@@ -767,9 +702,9 @@ namespace DoFRenumbering
   block_wise (MGDoFHandler<dim> &dof_handler);
 
   /**
-   * Computes the renumbering vector needed by the block_wise()
-   * functions. Does not perform the renumbering on the DoFHandler dofs but
-   * returns the renumbering vector.
+   * Computes the renumbering vector needed by the block_wise() functions.
+   * Does not perform the renumbering on the DoFHandler dofs but returns the
+   * renumbering vector.
    */
   template <int dim, int spacedim, class ITERATOR, class ENDITERATOR>
   types::global_dof_index
@@ -865,10 +800,10 @@ namespace DoFRenumbering
    * be guaranteed for all meshes.
    *
    * If the @p dof_wise_renumbering argument is set to @p false, this function
-   * produces a downstream ordering of the mesh cells and calls
-   * cell_wise(). Therefore, the output only makes sense for Discontinuous
-   * Galerkin Finite Elements (all degrees of freedom have to be associated
-   * with the interior of the cell in that case) in that case.
+   * produces a downstream ordering of the mesh cells and calls cell_wise().
+   * Therefore, the output only makes sense for Discontinuous Galerkin Finite
+   * Elements (all degrees of freedom have to be associated with the interior
+   * of the cell in that case) in that case.
    *
    * If @p dof_wise_renumbering is set to @p true, the degrees of freedom are
    * renumbered based on the support point location of the individual degrees
@@ -983,9 +918,9 @@ namespace DoFRenumbering
                 const bool counter = false);
 
   /**
-   * Computes the renumbering vector needed by the clockwise_dg()
-   * functions. Does not perform the renumbering on the DoFHandler dofs but
-   * returns the renumbering vector.
+   * Computes the renumbering vector needed by the clockwise_dg() functions.
+   * Does not perform the renumbering on the DoFHandler dofs but returns the
+   * renumbering vector.
    */
   template <class DH>
   void
@@ -1019,10 +954,10 @@ namespace DoFRenumbering
 
   /**
    * Sort those degrees of freedom which are tagged with @p true in the @p
-   * selected_dofs array on the level @p level to the back of the DoF
-   * numbers. The sorting is stable, i.e. the relative order within the tagged
-   * degrees of freedom is preserved, as is the relative order within the
-   * untagged ones.
+   * selected_dofs array on the level @p level to the back of the DoF numbers.
+   * The sorting is stable, i.e. the relative order within the tagged degrees
+   * of freedom is preserved, as is the relative order within the untagged
+   * ones.
    *
    * @pre The @p selected_dofs array must have as many elements as the @p
    * dof_handler has degrees of freedom on the given level.
@@ -1111,9 +1046,9 @@ namespace DoFRenumbering
   subdomain_wise (DH &dof_handler);
 
   /**
-   * Computes the renumbering vector needed by the subdomain_wise()
-   * function. Does not perform the renumbering on the @p DoFHandler dofs but
-   * returns the renumbering vector.
+   * Computes the renumbering vector needed by the subdomain_wise() function.
+   * Does not perform the renumbering on the @p DoFHandler dofs but returns
+   * the renumbering vector.
    */
   template <class DH>
   void
@@ -1137,9 +1072,8 @@ namespace DoFRenumbering
    */
   DeclException0 (ExcInvalidComponentOrder);
   /**
-   * The function is only
-   * implemented for Discontinuous
-   * Galerkin Finite elements.
+   * The function is only implemented for Discontinuous Galerkin Finite
+   * elements.
    *
    * @ingroup Exceptions
    */
index 40495100c049d7820d7bd2af47b2f73a07cdd7ed..b5ad9aa65cfaf78a1c144702ebaec45efe41b502 100644 (file)
@@ -60,31 +60,30 @@ namespace GridTools
 //TODO: map_support_points_to_dofs should generate a multimap, rather than just a map, since several dofs may be located at the same support point
 
 /**
- * This is a collection of functions operating on, and manipulating
- * the numbers of degrees of freedom. The documentation of the member
- * functions will provide more information, but for functions that
- * exist in multiple versions, there are sections in this global
- * documentation stating some commonalities.
+ * This is a collection of functions operating on, and manipulating the
+ * numbers of degrees of freedom. The documentation of the member functions
+ * will provide more information, but for functions that exist in multiple
+ * versions, there are sections in this global documentation stating some
+ * commonalities.
  *
- * All member functions are static, so there is no need to create an
- * object of class DoFTools.
+ * All member functions are static, so there is no need to create an object of
+ * class DoFTools.
  *
  *
  * <h3>Setting up sparsity patterns</h3>
  *
  * When assembling system matrices, the entries are usually of the form
  * $a_{ij} = a(\phi_i, \phi_j)$, where $a$ is a bilinear functional, often an
- * integral. When using sparse matrices, we therefore only need to reserve space
- * for those $a_{ij}$ only, which are nonzero, which is the same as to say that
- * the basis functions $\phi_i$ and $\phi_j$ have a nonempty intersection of
- * their support. Since the support of basis functions is bound only on cells
- * on which they are located or to which they are adjacent, to
- * determine the sparsity pattern it is sufficient to loop over all
- * cells and connect all basis functions on each cell with all other
- * basis functions on that cell.  There may be finite elements for
- * which not all basis functions on a cell connect with each other,
- * but no use of this case is made since no examples where this occurs
- * are known to the author.
+ * integral. When using sparse matrices, we therefore only need to reserve
+ * space for those $a_{ij}$ only, which are nonzero, which is the same as to
+ * say that the basis functions $\phi_i$ and $\phi_j$ have a nonempty
+ * intersection of their support. Since the support of basis functions is
+ * bound only on cells on which they are located or to which they are
+ * adjacent, to determine the sparsity pattern it is sufficient to loop over
+ * all cells and connect all basis functions on each cell with all other basis
+ * functions on that cell.  There may be finite elements for which not all
+ * basis functions on a cell connect with each other, but no use of this case
+ * is made since no examples where this occurs are known to the author.
  *
  *
  * <h3>DoF numberings on boundaries</h3>
@@ -125,46 +124,45 @@ namespace GridTools
  * i.e. the indices of degrees of freedom on different parts may be
  * intermixed.
  *
- * Degrees of freedom on the boundary but not on one of the specified
- * boundary parts are given the index DoFHandler::invalid_dof_index, as if
- * they were in the interior. If no boundary indicator was given or if
- * no face of a cell has a boundary indicator contained in the given
- * list, the vector of new indices consists solely of
- * DoFHandler::invalid_dof_index.
+ * Degrees of freedom on the boundary but not on one of the specified boundary
+ * parts are given the index DoFHandler::invalid_dof_index, as if they were in
+ * the interior. If no boundary indicator was given or if no face of a cell
+ * has a boundary indicator contained in the given list, the vector of new
+ * indices consists solely of DoFHandler::invalid_dof_index.
  *
  * (As a side note, for corner cases: The question what a degree of freedom on
  * the boundary is, is not so easy.  It should really be a degree of freedom
- * of which the respective basis function has nonzero values on the
- * boundary. At least for Lagrange elements this definition is equal to the
- * statement that the off-point, or what deal.II calls support_point, of the
- * shape function, i.e. the point where the function assumes its nominal value
- * (for Lagrange elements this is the point where it has the function value
- * 1), is located on the boundary. We do not check this directly, the
- * criterion is rather defined through the information the finite element
- * class gives: the FiniteElement class defines the numbers of basis functions
- * per vertex, per line, and so on and the basis functions are numbered after
- * this information; a basis function is to be considered to be on the face of
- * a cell (and thus on the boundary if the cell is at the boundary) according
- * to it belonging to a vertex, line, etc but not to the interior of the
- * cell. The finite element uses the same cell-wise numbering so that we can
- * say that if a degree of freedom was numbered as one of the dofs on lines,
- * we assume that it is located on the line. Where the off-point actually is,
- * is a secret of the finite element (well, you can ask it, but we don't do it
+ * of which the respective basis function has nonzero values on the boundary.
+ * At least for Lagrange elements this definition is equal to the statement
+ * that the off-point, or what deal.II calls support_point, of the shape
+ * function, i.e. the point where the function assumes its nominal value (for
+ * Lagrange elements this is the point where it has the function value 1), is
+ * located on the boundary. We do not check this directly, the criterion is
+ * rather defined through the information the finite element class gives: the
+ * FiniteElement class defines the numbers of basis functions per vertex, per
+ * line, and so on and the basis functions are numbered after this
+ * information; a basis function is to be considered to be on the face of a
+ * cell (and thus on the boundary if the cell is at the boundary) according to
+ * it belonging to a vertex, line, etc but not to the interior of the cell.
+ * The finite element uses the same cell-wise numbering so that we can say
+ * that if a degree of freedom was numbered as one of the dofs on lines, we
+ * assume that it is located on the line. Where the off-point actually is, is
+ * a secret of the finite element (well, you can ask it, but we don't do it
  * here) and not relevant in this context.)
  *
  *
  * <h3>Setting up sparsity patterns for boundary matrices</h3>
  *
- * In some cases, one wants to only work with DoFs that sit on the
- * boundary. One application is, for example, if rather than interpolating
- * non-homogenous boundary values, one would like to project them. For this,
- * we need two things: a way to identify nodes that are located on (parts of)
- * the boundary, and a way to build matrices out of only degrees of freedom
- * that are on the boundary (i.e. much smaller matrices, in which we do not
- * even build the large zero block that stems from the fact that most degrees
- * of freedom have no support on the boundary of the domain). The first of
- * these tasks is done by the map_dof_to_boundary_indices() function of this
- * class (described above).
+ * In some cases, one wants to only work with DoFs that sit on the boundary.
+ * One application is, for example, if rather than interpolating non-
+ * homogenous boundary values, one would like to project them. For this, we
+ * need two things: a way to identify nodes that are located on (parts of) the
+ * boundary, and a way to build matrices out of only degrees of freedom that
+ * are on the boundary (i.e. much smaller matrices, in which we do not even
+ * build the large zero block that stems from the fact that most degrees of
+ * freedom have no support on the boundary of the domain). The first of these
+ * tasks is done by the map_dof_to_boundary_indices() function of this class
+ * (described above).
  *
  * The second part requires us first to build a sparsity pattern for the
  * couplings between boundary nodes, and then to actually build the components
@@ -187,17 +185,15 @@ namespace GridTools
 namespace DoFTools
 {
   /**
-   * The flags used in tables by certain <tt>make_*_pattern</tt>
-   * functions to describe whether two components of the solution
-   * couple in the bilinear forms corresponding to cell or face
-   * terms. An example of using these flags is shown in the
-   * introduction of step-46.
+   * The flags used in tables by certain <tt>make_*_pattern</tt> functions to
+   * describe whether two components of the solution couple in the bilinear
+   * forms corresponding to cell or face terms. An example of using these
+   * flags is shown in the introduction of step-46.
    *
-   * In the descriptions of the individual elements below, remember
-   * that these flags are used as elements of tables of size
-   * FiniteElement::n_components times FiniteElement::n_components
-   * where each element indicates whether two components do or do not
-   * couple.
+   * In the descriptions of the individual elements below, remember that these
+   * flags are used as elements of tables of size FiniteElement::n_components
+   * times FiniteElement::n_components where each element indicates whether
+   * two components do or do not couple.
    */
   enum Coupling
   {
@@ -210,15 +206,16 @@ namespace DoFTools
      */
     always,
     /**
-     * Two components couple only if their shape functions are both
-     * nonzero on a given face. This flag is only used when computing
-     * integrals over faces of cells.
+     * Two components couple only if their shape functions are both nonzero on
+     * a given face. This flag is only used when computing integrals over
+     * faces of cells.
      */
     nonzero
   };
 
   /**
-   * @name Functions to support code that generically uses both DoFHandler and hp::DoFHandler
+   * @name Functions to support code that generically uses both DoFHandler and
+   * hp::DoFHandler
    * @{
    */
   /**
@@ -243,8 +240,8 @@ namespace DoFTools
   /**
    * Maximal number of degrees of freedom on a face.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -255,8 +252,8 @@ namespace DoFTools
   /**
    * Maximal number of degrees of freedom on a face.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -267,8 +264,8 @@ namespace DoFTools
   /**
    * Maximal number of degrees of freedom on a vertex.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -279,8 +276,8 @@ namespace DoFTools
   /**
    * Maximal number of degrees of freedom on a vertex.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -289,11 +286,11 @@ namespace DoFTools
   max_dofs_per_vertex (const hp::DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Number of vector components in the finite element object used by
-   * this DoFHandler.
+   * Number of vector components in the finite element object used by this
+   * DoFHandler.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -302,11 +299,11 @@ namespace DoFTools
   n_components (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Number of vector components in the finite element object used by
-   * this DoFHandler.
+   * Number of vector components in the finite element object used by this
+   * DoFHandler.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -315,11 +312,11 @@ namespace DoFTools
   n_components (const hp::DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Find out whether the FiniteElement used by this DoFHandler is
-   * primitive or not.
+   * Find out whether the FiniteElement used by this DoFHandler is primitive
+   * or not.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -328,11 +325,11 @@ namespace DoFTools
   fe_is_primitive (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Find out whether the FiniteElement used by this DoFHandler is
-   * primitive or not.
+   * Find out whether the FiniteElement used by this DoFHandler is primitive
+   * or not.
    *
-   * This function exists for both non-hp and hp DoFHandlers, to allow
-   * for a uniform interface to query this property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow for a
+   * uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -352,63 +349,55 @@ namespace DoFTools
   /**
    * Locate non-zero entries of the system matrix.
    *
-   * This function computes the possible positions of non-zero entries
-   * in the global system matrix. We assume that a certain finite
-   * element basis function is non-zero on a cell only if its degree
-   * of freedom is associated with the interior, a face, an edge or a
-   * vertex of this cell. As a result, the matrix entry between two
-   * basis functions can be non-zero only if they correspond to
-   * degrees of freedom of at least one common cell. Therefore, @p
-   * make_sparsity_pattern just loops over all cells and enters all
-   * couplings local to that cell. As the generation of the sparsity
-   * pattern is irrespective of the equation which is solved later on,
-   * the resulting sparsity pattern is symmetric.
-   *
-   * Remember using SparsityPattern::compress() after generating the
-   * pattern.
+   * This function computes the possible positions of non-zero entries in the
+   * global system matrix. We assume that a certain finite element basis
+   * function is non-zero on a cell only if its degree of freedom is
+   * associated with the interior, a face, an edge or a vertex of this cell.
+   * As a result, the matrix entry between two basis functions can be non-zero
+   * only if they correspond to degrees of freedom of at least one common
+   * cell. Therefore, @p make_sparsity_pattern just loops over all cells and
+   * enters all couplings local to that cell. As the generation of the
+   * sparsity pattern is irrespective of the equation which is solved later
+   * on, the resulting sparsity pattern is symmetric.
+   *
+   * Remember using SparsityPattern::compress() after generating the pattern.
    *
    * The actual type of the sparsity pattern may be SparsityPattern,
    * CompressedSparsityPattern, BlockSparsityPattern,
-   * BlockCompressedSparsityPattern,
-   * BlockCompressedSetSparsityPattern,
-   * BlockCompressedSimpleSparsityPattern, or any other class that
-   * satisfies similar requirements. It is assumed that the size of
-   * the sparsity pattern matches the number of degrees of freedom and
-   * that enough unused nonzero entries are left to fill the sparsity
-   * pattern. The nonzero entries generated by this function are
-   * overlaid to possible previous content of the object, that is
-   * previously added entries are not deleted.
-   *
-   * Since this process is purely local, the sparsity pattern does not
-   * provide for entries introduced by the elimination of hanging
-   * nodes. They have to be taken care of by a call to
-   * ConstraintMatrix::condense() afterwards.
-   *
-   * Alternatively, the constraints on degrees of freedom can already
-   * be taken into account at the time of creating the sparsity
-   * pattern. For this, pass the ConstraintMatrix object as the third
-   * argument to the current function. No call to
-   * ConstraintMatrix::condense() is then necessary. This process is
-   * explained in step-27.
-   *
-   * In case the constraints are already taken care of in this
-   * function, it is possible to neglect off-diagonal entries in the
-   * sparsity pattern. When using
-   * ConstraintMatrix::distribute_local_to_global during assembling,
-   * no entries will ever be written into these matrix position, so
-   * that one can save some computing time in matrix-vector products
-   * by not even creating these elements. In that case, the variable
-   * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
-   *
-   * If the @p subdomain_id parameter is given, the sparsity pattern
-   * is built only on cells that have a subdomain_id equal to the
-   * given argument. This is useful in parallel contexts where the
-   * matrix and sparsity pattern (for example a
-   * TrilinosWrappers::SparsityPattern) may be distributed and not
-   * every MPI process needs to build the entire sparsity pattern; in
-   * that case, it is sufficient if every process only builds that
-   * part of the sparsity pattern that corresponds to the subdomain_id
-   * for which it is responsible. This feature is used in step-32.
+   * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern,
+   * BlockCompressedSimpleSparsityPattern, or any other class that satisfies
+   * similar requirements. It is assumed that the size of the sparsity pattern
+   * matches the number of degrees of freedom and that enough unused nonzero
+   * entries are left to fill the sparsity pattern. The nonzero entries
+   * generated by this function are overlaid to possible previous content of
+   * the object, that is previously added entries are not deleted.
+   *
+   * Since this process is purely local, the sparsity pattern does not provide
+   * for entries introduced by the elimination of hanging nodes. They have to
+   * be taken care of by a call to ConstraintMatrix::condense() afterwards.
+   *
+   * Alternatively, the constraints on degrees of freedom can already be taken
+   * into account at the time of creating the sparsity pattern. For this, pass
+   * the ConstraintMatrix object as the third argument to the current
+   * function. No call to ConstraintMatrix::condense() is then necessary. This
+   * process is explained in step-27.
+   *
+   * In case the constraints are already taken care of in this function, it is
+   * possible to neglect off-diagonal entries in the sparsity pattern. When
+   * using ConstraintMatrix::distribute_local_to_global during assembling, no
+   * entries will ever be written into these matrix position, so that one can
+   * save some computing time in matrix-vector products by not even creating
+   * these elements. In that case, the variable <tt>keep_constrained_dofs</tt>
+   * needs to be set to <tt>false</tt>.
+   *
+   * If the @p subdomain_id parameter is given, the sparsity pattern is built
+   * only on cells that have a subdomain_id equal to the given argument. This
+   * is useful in parallel contexts where the matrix and sparsity pattern (for
+   * example a TrilinosWrappers::SparsityPattern) may be distributed and not
+   * every MPI process needs to build the entire sparsity pattern; in that
+   * case, it is sufficient if every process only builds that part of the
+   * sparsity pattern that corresponds to the subdomain_id for which it is
+   * responsible. This feature is used in step-32.
    *
    * @ingroup constraints
    */
@@ -421,21 +410,19 @@ namespace DoFTools
                          const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
   /**
-   * Locate non-zero entries for vector valued finite elements.  This
-   * function does mostly the same as the previous
-   * make_sparsity_pattern(), but it is specialized for vector finite
-   * elements and allows to specify which variables couple in which
-   * equation. For example, if wanted to solve the Stokes equations,
+   * Locate non-zero entries for vector valued finite elements.  This function
+   * does mostly the same as the previous make_sparsity_pattern(), but it is
+   * specialized for vector finite elements and allows to specify which
+   * variables couple in which equation. For example, if wanted to solve the
+   * Stokes equations,
    *
-   * @f{align*}
-   * -\Delta \mathbf u + \nabla p &= 0,\\
-   * \text{div}\ u                    &= 0
-   * @f}
+   * @f{align*} -\Delta \mathbf u + \nabla p &= 0,\\ \text{div}\ u
+   * &= 0 @f}
    *
-   * in two space dimensions, using stable Q2/Q1 mixed elements (using
-   * the FESystem class), then you don't want all degrees of freedom
-   * to couple in each equation. You rather may want to give the
-   * following pattern of couplings:
+   * in two space dimensions, using stable Q2/Q1 mixed elements (using the
+   * FESystem class), then you don't want all degrees of freedom to couple in
+   * each equation. You rather may want to give the following pattern of
+   * couplings:
    *
    * @f[
    * \left[
@@ -447,66 +434,59 @@ namespace DoFTools
    * \right]
    * @f]
    *
-   * where "1" indicates that two variables (i.e. components of the
-   * FESystem) couple in the respective equation, and a "0" means no
-   * coupling, in which case it is not necessary to allocate space in
-   * the matrix structure. Obviously, the mask refers to components of
-   * the composed FESystem, rather than to the degrees of freedom
-   * contained in there.
-   *
-   * This function is designed to accept a coupling pattern, like the
-   * one shown above, through the @p couplings parameter, which
-   * contains values of type #Coupling. It builds the matrix structure
-   * just like the previous function, but does not create matrix
-   * elements if not specified by the coupling pattern. If the
-   * couplings are symmetric, then so will be the resulting sparsity
-   * pattern.
+   * where "1" indicates that two variables (i.e. components of the FESystem)
+   * couple in the respective equation, and a "0" means no coupling, in which
+   * case it is not necessary to allocate space in the matrix structure.
+   * Obviously, the mask refers to components of the composed FESystem, rather
+   * than to the degrees of freedom contained in there.
+   *
+   * This function is designed to accept a coupling pattern, like the one
+   * shown above, through the @p couplings parameter, which contains values of
+   * type #Coupling. It builds the matrix structure just like the previous
+   * function, but does not create matrix elements if not specified by the
+   * coupling pattern. If the couplings are symmetric, then so will be the
+   * resulting sparsity pattern.
    *
    * The actual type of the sparsity pattern may be SparsityPattern,
    * CompressedSparsityPattern, BlockSparsityPattern,
-   * BlockCompressedSparsityPattern,
-   * BlockCompressedSetSparsityPattern, or any other class that
-   * satisfies similar requirements.
+   * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern, or any
+   * other class that satisfies similar requirements.
    *
-   * There is a complication if some or all of the shape functions of
-   * the finite element in use are non-zero in more than one component
-   * (in deal.II speak: they are non-primitive). In this case, the
-   * coupling element correspoding to the first non-zero component is
-   * taken and additional ones for this component are ignored.
+   * There is a complication if some or all of the shape functions of the
+   * finite element in use are non-zero in more than one component (in deal.II
+   * speak: they are non-primitive). In this case, the coupling element
+   * correspoding to the first non-zero component is taken and additional ones
+   * for this component are ignored.
    *
    * @todo Not implemented for hp::DoFHandler.
    *
-   * As mentioned before, the creation of the sparsity pattern is a
-   * purely local process and the sparsity pattern does not provide
-   * for entries introduced by the elimination of hanging nodes. They
-   * have to be taken care of by a call to
-   * ConstraintMatrix::condense() afterwards.
-   *
-   * Alternatively, the constraints on degrees of freedom can already
-   * be taken into account at the time of creating the sparsity
-   * pattern. For this, pass the ConstraintMatrix object as the third
-   * argument to the current function. No call to
-   * ConstraintMatrix::condense() is then necessary. This process is
-   * explained in @ref step_27 "step-27".
-   *
-   * In case the constraints are already taken care of in this
-   * function, it is possible to neglect off-diagonal entries in the
-   * sparsity pattern. When using
-   * ConstraintMatrix::distribute_local_to_global during assembling,
-   * no entries will ever be written into these matrix position, so
-   * that one can save some computing time in matrix-vector products
-   * by not even creating these elements. In that case, the variable
-   * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
-   *
-   * If the @p subdomain_id parameter is given, the sparsity pattern
-   * is built only on cells that have a subdomain_id equal to the
-   * given argument. This is useful in parallel contexts where the
-   * matrix and sparsity pattern (for example a
-   * TrilinosWrappers::SparsityPattern) may be distributed and not
-   * every MPI process needs to build the entire sparsity pattern; in
-   * that case, it is sufficient if every process only builds that
-   * part of the sparsity pattern that corresponds to the subdomain_id
-   * for which it is responsible. This feature is used in step-32.
+   * As mentioned before, the creation of the sparsity pattern is a purely
+   * local process and the sparsity pattern does not provide for entries
+   * introduced by the elimination of hanging nodes. They have to be taken
+   * care of by a call to ConstraintMatrix::condense() afterwards.
+   *
+   * Alternatively, the constraints on degrees of freedom can already be taken
+   * into account at the time of creating the sparsity pattern. For this, pass
+   * the ConstraintMatrix object as the third argument to the current
+   * function. No call to ConstraintMatrix::condense() is then necessary. This
+   * process is explained in @ref step_27 "step-27".
+   *
+   * In case the constraints are already taken care of in this function, it is
+   * possible to neglect off-diagonal entries in the sparsity pattern. When
+   * using ConstraintMatrix::distribute_local_to_global during assembling, no
+   * entries will ever be written into these matrix position, so that one can
+   * save some computing time in matrix-vector products by not even creating
+   * these elements. In that case, the variable <tt>keep_constrained_dofs</tt>
+   * needs to be set to <tt>false</tt>.
+   *
+   * If the @p subdomain_id parameter is given, the sparsity pattern is built
+   * only on cells that have a subdomain_id equal to the given argument. This
+   * is useful in parallel contexts where the matrix and sparsity pattern (for
+   * example a TrilinosWrappers::SparsityPattern) may be distributed and not
+   * every MPI process needs to build the entire sparsity pattern; in that
+   * case, it is sufficient if every process only builds that part of the
+   * sparsity pattern that corresponds to the subdomain_id for which it is
+   * responsible. This feature is used in step-32.
    *
    * @ingroup constraints
    */
@@ -520,11 +500,10 @@ namespace DoFTools
                          const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
   /**
-   * @deprecated This is the old form of the previous function. It
-   * generates a table of DoFTools::Coupling values (where a
-   * <code>true</code> value in the mask is translated into a
-   * Coupling::always value in the table) and calls the function
-   * above.
+   * @deprecated This is the old form of the previous function. It generates a
+   * table of DoFTools::Coupling values (where a <code>true</code> value in
+   * the mask is translated into a Coupling::always value in the table) and
+   * calls the function above.
    */
   template <class DH, class SparsityPattern>
   void
@@ -533,25 +512,24 @@ namespace DoFTools
                          SparsityPattern                       &sparsity_pattern) DEAL_II_DEPRECATED;
 
   /**
-   * Construct a sparsity pattern that allows coupling degrees of
-   * freedom on two different but related meshes.
+   * Construct a sparsity pattern that allows coupling degrees of freedom on
+   * two different but related meshes.
    *
-   * The idea is that if the two given DoFHandler objects correspond
-   * to two different meshes (and potentially to different finite
-   * elements used on these cells), but that if the two triangulations
-   * they are based on are derived from the same coarse mesh through
-   * hierarchical refinement, then one may set up a problem where one
-   * would like to test shape functions from one mesh against the
-   * shape functions from another mesh. In particular, this means that
-   * shape functions from a cell on the first mesh are tested against
-   * those on the second cell that are located on the corresponding
-   * cell; this correspondence is something that the IntergridMap
-   * class can determine.
+   * The idea is that if the two given DoFHandler objects correspond to two
+   * different meshes (and potentially to different finite elements used on
+   * these cells), but that if the two triangulations they are based on are
+   * derived from the same coarse mesh through hierarchical refinement, then
+   * one may set up a problem where one would like to test shape functions
+   * from one mesh against the shape functions from another mesh. In
+   * particular, this means that shape functions from a cell on the first mesh
+   * are tested against those on the second cell that are located on the
+   * corresponding cell; this correspondence is something that the
+   * IntergridMap class can determine.
    *
-   * This function then constructs a sparsity pattern for which the
-   * degrees of freedom that represent the rows come from the first
-   * given DoFHandler, whereas the ones that correspond to columns
-   * come from the second DoFHandler.
+   * This function then constructs a sparsity pattern for which the degrees of
+   * freedom that represent the rows come from the first given DoFHandler,
+   * whereas the ones that correspond to columns come from the second
+   * DoFHandler.
    */
   template <class DH, class SparsityPattern>
   void
@@ -560,15 +538,14 @@ namespace DoFTools
                          SparsityPattern &sparsity);
 
   /**
-   * Create the sparsity pattern for boundary matrices. See the
-   * general documentation of this class for more information.
+   * Create the sparsity pattern for boundary matrices. See the general
+   * documentation of this class for more information.
    *
    * The actual type of the sparsity pattern may be SparsityPattern,
    * CompressedSparsityPattern, BlockSparsityPattern,
-   * BlockCompressedSparsityPattern,
-   * BlockCompressedSetSparsityPattern, or any other class that
-   * satisfies similar requirements. It is assumed that the size of
-   * the sparsity pattern is already correct.
+   * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern, or any
+   * other class that satisfies similar requirements. It is assumed that the
+   * size of the sparsity pattern is already correct.
    */
   template <class DH, class SparsityPattern>
   void
@@ -578,21 +555,19 @@ namespace DoFTools
 
   /**
    * Write the sparsity structure of the matrix composed of the basis
-   * functions on the boundary into the matrix structure. In contrast
-   * to the previous function, only those parts of the boundary are
-   * considered of which the boundary indicator is listed in the set
-   * of numbers passed to this function.
-   *
-   * In fact, rather than a @p set of boundary indicators, a @p map
-   * needs to be passed, since most of the functions handling with
-   * boundary indicators take a mapping of boundary indicators and the
-   * respective boundary functions. The boundary function, however, is
-   * ignored in this function.  If you have no functions at hand, but
-   * only the boundary indicators, set the function pointers to null
-   * pointers.
-   *
-   * For the type of the sparsity pattern, the same holds as said
-   * above.
+   * functions on the boundary into the matrix structure. In contrast to the
+   * previous function, only those parts of the boundary are considered of
+   * which the boundary indicator is listed in the set of numbers passed to
+   * this function.
+   *
+   * In fact, rather than a @p set of boundary indicators, a @p map needs to
+   * be passed, since most of the functions handling with boundary indicators
+   * take a mapping of boundary indicators and the respective boundary
+   * functions. The boundary function, however, is ignored in this function.
+   * If you have no functions at hand, but only the boundary indicators, set
+   * the function pointers to null pointers.
+   *
+   * For the type of the sparsity pattern, the same holds as said above.
    */
   template <class DH, class SparsityPattern>
   void
@@ -602,12 +577,12 @@ namespace DoFTools
                                   SparsityPattern    &sparsity);
 
   /**
-   * Generate sparsity pattern for fluxes, i.e. formulations of the
-   * discrete problem with discontinuous elements which couple across
-   * faces of cells.  This is a replacement of the function @p
-   * make_sparsity_pattern for discontinuous methods. Since the fluxes
-   * include couplings between neighboring elements, the normal
-   * couplings and these extra matrix entries are considered.
+   * Generate sparsity pattern for fluxes, i.e. formulations of the discrete
+   * problem with discontinuous elements which couple across faces of cells.
+   * This is a replacement of the function @p make_sparsity_pattern for
+   * discontinuous methods. Since the fluxes include couplings between
+   * neighboring elements, the normal couplings and these extra matrix entries
+   * are considered.
    */
   template<class DH, class SparsityPattern>
   void
@@ -615,9 +590,9 @@ namespace DoFTools
                               SparsityPattern &sparsity_pattern);
 
   /**
-   * This function does the same as the other with the same name, but
-   * it gets a ConstraintMatrix additionally.  This is for the case
-   * where you have fluxes but constraints as well.
+   * This function does the same as the other with the same name, but it gets
+   * a ConstraintMatrix additionally.  This is for the case where you have
+   * fluxes but constraints as well.
    *
    * @ingroup constraints
    */
@@ -630,14 +605,13 @@ namespace DoFTools
                               const types::subdomain_id  subdomain_id = numbers::invalid_unsigned_int);
 
   /**
-   * This function does the same as the other with the same name, but
-   * it gets two additional coefficient matrices. A matrix entry will
-   * only be generated for two basis functions, if there is a non-zero
-   * entry linking their associated components in the coefficient
-   * matrix.
+   * This function does the same as the other with the same name, but it gets
+   * two additional coefficient matrices. A matrix entry will only be
+   * generated for two basis functions, if there is a non-zero entry linking
+   * their associated components in the coefficient matrix.
    *
-   * There is one matrix for couplings in a cell and one for the
-   * couplings occuring in fluxes.
+   * There is one matrix for couplings in a cell and one for the couplings
+   * occuring in fluxes.
    *
    * @todo Not implemented for hp::DoFHandler.
    */
@@ -658,43 +632,38 @@ namespace DoFTools
    */
 
   /**
-   * Compute the constraints resulting from the presence of hanging
-   * nodes. Hanging nodes are best explained using a small picture:
+   * Compute the constraints resulting from the presence of hanging nodes.
+   * Hanging nodes are best explained using a small picture:
    *
    * @image html hanging_nodes.png
    *
-   * In order to make a finite element function globally continuous,
-   * we have to make sure that the dark red nodes have values that are
-   * compatible with the adjacent yellow nodes, so that the function
-   * has no jump when coming from the small cells to the large one at
-   * the top right. We therefore have to add conditions that constrain
-   * those "hanging nodes".
-   *
-   * The object into which these are inserted is later used to
-   * condense the global system matrix and right hand side, and to
-   * extend the solution vectors from the true degrees of freedom also
-   * to the constraint nodes. This function is explained in detail in
-   * the @ref step_6 "step-6" tutorial program and is used in almost
-   * all following programs as well.
-   *
-   * This function does not clear the constraint matrix object before
-   * use, in order to allow adding constraints from different sources
-   * to the same object. You therefore need to make sure it contains
-   * only constraints you still want; otherwise call the
-   * ConstraintMatrix::clear() function.  Likewise, this function does
-   * not close the object since you may want to enter other
-   * constraints later on yourself.
-   *
-   * In the hp-case, i.e. when the argument is of type hp::DoFHandler,
-   * we consider constraints due to different finite elements used on
-   * two sides of a face between cells as hanging nodes as well. In
-   * other words, for hp finite elements, this function computes all
-   * constraints due to differing mesh sizes (h) or polynomial degrees
-   * (p) between adjacent cells.
-   *
-   * The template argument (and by consequence the type of the first
-   * argument to this function) can be either ::DoFHandler or
-   * hp::DoFHandler.
+   * In order to make a finite element function globally continuous, we have
+   * to make sure that the dark red nodes have values that are compatible with
+   * the adjacent yellow nodes, so that the function has no jump when coming
+   * from the small cells to the large one at the top right. We therefore have
+   * to add conditions that constrain those "hanging nodes".
+   *
+   * The object into which these are inserted is later used to condense the
+   * global system matrix and right hand side, and to extend the solution
+   * vectors from the true degrees of freedom also to the constraint nodes.
+   * This function is explained in detail in the @ref step_6 "step-6" tutorial
+   * program and is used in almost all following programs as well.
+   *
+   * This function does not clear the constraint matrix object before use, in
+   * order to allow adding constraints from different sources to the same
+   * object. You therefore need to make sure it contains only constraints you
+   * still want; otherwise call the ConstraintMatrix::clear() function.
+   * Likewise, this function does not close the object since you may want to
+   * enter other constraints later on yourself.
+   *
+   * In the hp-case, i.e. when the argument is of type hp::DoFHandler, we
+   * consider constraints due to different finite elements used on two sides
+   * of a face between cells as hanging nodes as well. In other words, for hp
+   * finite elements, this function computes all constraints due to differing
+   * mesh sizes (h) or polynomial degrees (p) between adjacent cells.
+   *
+   * The template argument (and by consequence the type of the first argument
+   * to this function) can be either ::DoFHandler or hp::DoFHandler.
    *
    * @ingroup constraints
    */
@@ -715,28 +684,27 @@ namespace DoFTools
    * T}_0$. Using the same finite element on both, there are function spaces
    * ${\cal V}_0$ and ${\cal V}_1$ associated with these meshes. Then every
    * function $v_0 \in {\cal V}_0$ can of course also be represented exactly
-   * in ${\cal V}_1$ since by construction ${\cal V}_0 \subset {\cal
-   * V}_1$. However, not every function in ${\cal V}_1$ can be expressed as a
-   * linear combination of the shape functions of ${\cal V}_0$. The functions
-   * that can be represented lie in a homogenous subspace of ${\cal V}_1$
-   * (namely, ${\cal V}_0$, of course) and this subspace can be represented by
-   * a linear constraint of the form $CV=0$ where $V$ is the vector of nodal
-   * values of functions $v\in {\cal V}_1$. In other words, every function
-   * $v_h=\sum_j V_j \varphi_j^{(1)} \in {\cal V}_1$ that also satisfies
-   * $v_h\in {\cal V}_0$ automatically satisfies $CV=0$. This function
-   * computes the matrix $C$ in the form of a ConstraintMatrix object.
-   *
-   * The construction of these constraints is done as follows: for
-   * each of the degrees of freedom (i.e. shape functions) on the
-   * coarse grid, we compute its representation on the fine grid,
-   * i.e. how the linear combination of shape functions on the fine
-   * grid looks like that resembles the shape function on the coarse
-   * grid. From this information, we can then compute the constraints
-   * which have to hold if a solution of a linear equation on the fine
-   * grid shall be representable on the coarse grid. The exact
-   * algorithm how these constraints can be computed is rather
-   * complicated and is best understood by reading the source code,
-   * which contains many comments.
+   * in ${\cal V}_1$ since by construction ${\cal V}_0 \subset {\cal V}_1$.
+   * However, not every function in ${\cal V}_1$ can be expressed as a linear
+   * combination of the shape functions of ${\cal V}_0$. The functions that
+   * can be represented lie in a homogenous subspace of ${\cal V}_1$ (namely,
+   * ${\cal V}_0$, of course) and this subspace can be represented by a linear
+   * constraint of the form $CV=0$ where $V$ is the vector of nodal values of
+   * functions $v\in {\cal V}_1$. In other words, every function $v_h=\sum_j
+   * V_j \varphi_j^{(1)} \in {\cal V}_1$ that also satisfies $v_h\in {\cal
+   * V}_0$ automatically satisfies $CV=0$. This function computes the matrix
+   * $C$ in the form of a ConstraintMatrix object.
+   *
+   * The construction of these constraints is done as follows: for each of the
+   * degrees of freedom (i.e. shape functions) on the coarse grid, we compute
+   * its representation on the fine grid, i.e. how the linear combination of
+   * shape functions on the fine grid looks like that resembles the shape
+   * function on the coarse grid. From this information, we can then compute
+   * the constraints which have to hold if a solution of a linear equation on
+   * the fine grid shall be representable on the coarse grid. The exact
+   * algorithm how these constraints can be computed is rather complicated and
+   * is best understood by reading the source code, which contains many
+   * comments.
    *
    * The use of this function is as follows: it accepts as parameters two DoF
    * Handlers, the first of which refers to the coarse grid and the second of
@@ -782,17 +750,15 @@ namespace DoFTools
 
 
   /**
-   * This function generates a matrix such that when a vector of data
-   * with as many elements as there are degrees of freedom of this
-   * component on the coarse grid is multiplied to this matrix, we
-   * obtain a vector with as many elements as there are global
-   * degrees of freedom on the fine grid. All the elements of the
-   * other vector components of the finite element fields on the fine grid
-   * are not touched.
+   * This function generates a matrix such that when a vector of data with as
+   * many elements as there are degrees of freedom of this component on the
+   * coarse grid is multiplied to this matrix, we obtain a vector with as many
+   * elements as there are global degrees of freedom on the fine grid. All the
+   * elements of the other vector components of the finite element fields on
+   * the fine grid are not touched.
    *
-   * The output of this function is a compressed format that can be
-   * given to the @p reinit functions of the SparsityPattern ad
-   * SparseMatrix classes.
+   * The output of this function is a compressed format that can be given to
+   * the @p reinit functions of the SparsityPattern ad SparseMatrix classes.
    */
   template <int dim, int spacedim>
   void
@@ -814,47 +780,45 @@ namespace DoFTools
    */
 
   /**
-   * Insert the (algebraic) constraints due to periodic boundary
-   * conditions into a ConstraintMatrix @p constraint_matrix.
+   * Insert the (algebraic) constraints due to periodic boundary conditions
+   * into a ConstraintMatrix @p constraint_matrix.
    *
-   * Given a pair of not necessarily active boundary faces @p face_1 and
-   * @p face_2, this functions constrains all DoFs associated with the boundary
+   * Given a pair of not necessarily active boundary faces @p face_1 and @p
+   * face_2, this functions constrains all DoFs associated with the boundary
    * described by @p face_1 to the respective DoFs of the boundary described
    * by @p face_2. More precisely:
    *
-   * If @p face_1 and @p face_2 are both active faces it adds the DoFs
-   * of @p face_1 to the list of constrained DoFs in @p constraint_matrix
-   * and adds entries to constrain them to the corresponding values of the
-   * DoFs on @p face_2. This happens on a purely algebraic level, meaning,
-   * the global DoF with (local face) index <tt>i</tt> on @p face_1 gets
-   * constraint to the DoF with (local face) index <tt>i</tt> on @p face_2
-   * (possibly corrected for orientation, see below).
-   *
-   * Otherwise, if @p face_1 and @p face_2 are not active faces, this
-   * function loops recursively over the children of @p face_1 and @p face_2.
-   * If only one of the two faces is active, then we recursively iterate
-   * over the children of the non-active ones and make sure that the
-   * solution function on the refined side equals that on the non-refined
-   * face in much the same way as we enforce hanging node constraints
-   * at places where differently refined cells come together. (However,
-   * unlike hanging nodes, we do not enforce the requirement that there
-   * be only a difference of one refinement level between the two sides
-   * of the domain you would like to be periodic).
-   *
-   * This routine only constrains DoFs that are not already constrained.
-   * If this routine encounters a DoF that already is constrained (for
-   * instance by Dirichlet boundary conditions), the old setting of the
-   * constraint (dofs the entry is constrained to, inhomogeneities) is
-   * kept and nothing happens.
-   *
-   * The flags in the @p component_mask (see @ref GlossComponentMask)
-   * denote which components of the finite element space shall be
-   * constrained with periodic boundary conditions. If it is left as
-   * specified by the default value all components are constrained. If it
-   * is different from the default value, it is assumed that the number of
-   * entries equals the number of components of the finite element. This
-   * can be used to enforce periodicity in only one variable in a system of
-   * equations.
+   * If @p face_1 and @p face_2 are both active faces it adds the DoFs of @p
+   * face_1 to the list of constrained DoFs in @p constraint_matrix and adds
+   * entries to constrain them to the corresponding values of the DoFs on @p
+   * face_2. This happens on a purely algebraic level, meaning, the global DoF
+   * with (local face) index <tt>i</tt> on @p face_1 gets constraint to the
+   * DoF with (local face) index <tt>i</tt> on @p face_2 (possibly corrected
+   * for orientation, see below).
+   *
+   * Otherwise, if @p face_1 and @p face_2 are not active faces, this function
+   * loops recursively over the children of @p face_1 and @p face_2. If only
+   * one of the two faces is active, then we recursively iterate over the
+   * children of the non-active ones and make sure that the solution function
+   * on the refined side equals that on the non-refined face in much the same
+   * way as we enforce hanging node constraints at places where differently
+   * refined cells come together. (However, unlike hanging nodes, we do not
+   * enforce the requirement that there be only a difference of one refinement
+   * level between the two sides of the domain you would like to be periodic).
+   *
+   * This routine only constrains DoFs that are not already constrained. If
+   * this routine encounters a DoF that already is constrained (for instance
+   * by Dirichlet boundary conditions), the old setting of the constraint
+   * (dofs the entry is constrained to, inhomogeneities) is kept and nothing
+   * happens.
+   *
+   * The flags in the @p component_mask (see @ref GlossComponentMask) denote
+   * which components of the finite element space shall be constrained with
+   * periodic boundary conditions. If it is left as specified by the default
+   * value all components are constrained. If it is different from the default
+   * value, it is assumed that the number of entries equals the number of
+   * components of the finite element. This can be used to enforce periodicity
+   * in only one variable in a system of equations.
    *
    * @p face_orientation, @p face_flip and @p face_rotation describe an
    * orientation that should be applied to @p face_1 prior to matching and
@@ -862,9 +826,9 @@ namespace DoFTools
    * the given faces in their respective cells (which for boundary faces is
    * always the default) but instead how you want to see periodicity to be
    * enforced. For example, by using these flags, you can enforce a condition
-   * of the kind $u(0,y)=u(1,1-y)$ (i.e., a Moebius band) or in 3d
-   * a twisted torus. More precisely, these flags match local face DoF indices
-   * in the following manner:
+   * of the kind $u(0,y)=u(1,1-y)$ (i.e., a Moebius band) or in 3d a twisted
+   * torus. More precisely, these flags match local face DoF indices in the
+   * following manner:
    *
    * In 2d: <tt>face_orientation</tt> must always be <tt>true</tt>,
    * <tt>face_rotation</tt> is always <tt>false</tt>, and face_flip has the
@@ -948,19 +912,19 @@ namespace DoFTools
    * and any combination of that...
    * @endcode
    *
-   * Optionally a matrix @p matrix along with an std::vector
-   * @p first_vector_components can be specified that describes how DoFs on
-   * @p face_1 should be modified prior to constraining to the DoFs of
-   * @p face_2. Here, two declarations are possible:
-   * If the std::vector @p first_vector_components is non empty the
-   * matrix is interpreted as a @p dim $\times$ @p dim rotation matrix that is
-   * applied to all vector valued blocks listed in @p first_vector_components
-   * of the FESystem. If @p first_vector_components is empty the matrix is
-   * interpreted as an interpolation matrix with size no_face_dofs $\times$
-   * no_face_dofs.
+   * Optionally a matrix @p matrix along with an std::vector @p
+   * first_vector_components can be specified that describes how DoFs on @p
+   * face_1 should be modified prior to constraining to the DoFs of @p face_2.
+   * Here, two declarations are possible: If the std::vector @p
+   * first_vector_components is non empty the matrix is interpreted as a @p
+   * dim $\times$ @p dim rotation matrix that is applied to all vector valued
+   * blocks listed in @p first_vector_components of the FESystem. If @p
+   * first_vector_components is empty the matrix is interpreted as an
+   * interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
    *
-   * Detailed information can be found in the
-   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions".
+   * Detailed information can be found in the @see @ref
+   * GlossPeriodicConstraints "Glossary entry on periodic boundary
+   * conditions".
    *
    * @todo: Reference to soon be written example step and glossary article.
    *
@@ -982,22 +946,22 @@ namespace DoFTools
 
 
   /**
-   * Insert the (algebraic) constraints due to periodic boundary
-   * conditions into a ConstraintMatrix @p constraint_matrix.
+   * Insert the (algebraic) constraints due to periodic boundary conditions
+   * into a ConstraintMatrix @p constraint_matrix.
    *
    * This is the main high level interface for above low level variant of
-   * make_periodicity_constraints(). It takes an std::vector @p
-   * periodic_faces as argument and applies above
-   * make_periodicity_constraints on each entry. The std::vector @p
-   * periodic_faces can be created by GridTools::collect_periodic_faces.
+   * make_periodicity_constraints(). It takes an std::vector @p periodic_faces
+   * as argument and applies above make_periodicity_constraints on each entry.
+   * The std::vector @p periodic_faces can be created by
+   * GridTools::collect_periodic_faces.
    *
    * @note For DoFHandler objects that are built on a
    * parallel::distributed::Triangulation object
    * parallel::distributed::Triangulation::add_periodicity has to be called
    * before.
    *
-   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
-   * for further information.
+   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+   * conditions" for further information.
    *
    * @author Daniel Arndt, Matthias Maier, 2013, 2014
    */
@@ -1012,48 +976,46 @@ namespace DoFTools
 
 
   /**
-   * Insert the (algebraic) constraints due to periodic boundary
-   * conditions into a ConstraintMatrix @p constraint_matrix.
+   * Insert the (algebraic) constraints due to periodic boundary conditions
+   * into a ConstraintMatrix @p constraint_matrix.
    *
    * This function serves as a high level interface for the
    * make_periodicity_constraints() function.
    *
-   * Define a 'first' boundary as all boundary faces having boundary_id
-   * @p b_id1 and a 'second' boundary consisting of all faces belonging
-   * to @p b_id2.
+   * Define a 'first' boundary as all boundary faces having boundary_id @p
+   * b_id1 and a 'second' boundary consisting of all faces belonging to @p
+   * b_id2.
    *
-   * This function tries to match all faces belonging to the first
-   * boundary with faces belonging to the second boundary with the help
-   * of orthogonal_equality().
+   * This function tries to match all faces belonging to the first boundary
+   * with faces belonging to the second boundary with the help of
+   * orthogonal_equality().
    *
-   * If this matching is successful it constrains all DoFs associated
-   * with the 'first' boundary to the respective DoFs of the 'second'
-   * boundary respecting the relative orientation of the two faces.
+   * If this matching is successful it constrains all DoFs associated with the
+   * 'first' boundary to the respective DoFs of the 'second' boundary
+   * respecting the relative orientation of the two faces.
    *
-   * This routine only constrains DoFs that are not already constrained.
-   * If this routine encounters a DoF that already is constrained (for
-   * instance by Dirichlet boundary conditions), the old setting of the
-   * constraint (dofs the entry is constrained to, inhomogeneities) is
-   * kept and nothing happens.
+   * This routine only constrains DoFs that are not already constrained. If
+   * this routine encounters a DoF that already is constrained (for instance
+   * by Dirichlet boundary conditions), the old setting of the constraint
+   * (dofs the entry is constrained to, inhomogeneities) is kept and nothing
+   * happens.
    *
    * The flags in the last parameter, @p component_mask (see @ref
-   * GlossComponentMask) denote which components of the finite element
-   * space shall be constrained with periodic boundary conditions. If it is
-   * left as specified by the default value all components are constrained.
-   * If it is different from the default value, it is assumed that the
-   * number of entries equals the number of components in the boundary
-   * functions and the finite element, and those components in the given
-   * boundary function will be used for which the respective flag was set
-   * in the component mask.
+   * GlossComponentMask) denote which components of the finite element space
+   * shall be constrained with periodic boundary conditions. If it is left as
+   * specified by the default value all components are constrained. If it is
+   * different from the default value, it is assumed that the number of
+   * entries equals the number of components in the boundary functions and the
+   * finite element, and those components in the given boundary function will
+   * be used for which the respective flag was set in the component mask.
    *
    * @note: This function is a convenience wrapper. It internally calls
    * GridTools::collect_periodic_faces() with the supplied paramaters and
-   * feeds the output to above make_periodicity_constraints() variant. If
-   * you need more functionality use GridTools::collect_periodic_faces()
-   * directly.
+   * feeds the output to above make_periodicity_constraints() variant. If you
+   * need more functionality use GridTools::collect_periodic_faces() directly.
    *
-   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
-   * for further information.
+   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+   * conditions" for further information.
    *
    * @author Matthias Maier, 2012
    */
@@ -1070,28 +1032,26 @@ namespace DoFTools
 
 
   /**
-   * This compatibility version of make_periodicity_constraints only works
-   * on grids with cells in @ref GlossFaceOrientation "standard orientation".
+   * This compatibility version of make_periodicity_constraints only works on
+   * grids with cells in @ref GlossFaceOrientation "standard orientation".
    *
-   * Instead of defining a 'first' and 'second' boundary with the help of
-   * two boundary_indicators this function defines a 'left' boundary as all
-   * faces with local face index <code>2*dimension</code> and boundary
-   * indicator @p b_id and, similarly, a 'right' boundary consisting of all
-   * face with local face index <code>2*dimension+1</code> and boundary
-   * indicator @p b_id.
+   * Instead of defining a 'first' and 'second' boundary with the help of two
+   * boundary_indicators this function defines a 'left' boundary as all faces
+   * with local face index <code>2*dimension</code> and boundary indicator @p
+   * b_id and, similarly, a 'right' boundary consisting of all face with local
+   * face index <code>2*dimension+1</code> and boundary indicator @p b_id.
    *
    * @note This version of make_periodicity_constraints  will not work on
-   * meshes with cells not in @ref GlossFaceOrientation
-   * "standard orientation".
+   * meshes with cells not in @ref GlossFaceOrientation "standard
+   * orientation".
    *
    * @note: This function is a convenience wrapper. It internally calls
    * GridTools::collect_periodic_faces() with the supplied paramaters and
-   * feeds the output to above make_periodicity_constraints() variant. If
-   * you need more functionality use GridTools::collect_periodic_faces()
-   * directly.
+   * feeds the output to above make_periodicity_constraints() variant. If you
+   * need more functionality use GridTools::collect_periodic_faces() directly.
    *
-   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
-   * for further information.
+   * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+   * conditions" for further information.
    */
   template<typename DH>
   void
@@ -1105,11 +1065,11 @@ namespace DoFTools
 
 
   /**
-   * The @p offset is a vector tangential to the faces that is added to
-   * the location of vertices of the 'first' boundary when attempting to
-   * match them to the corresponding vertices of the 'second' boundary via
-   * orthogonal_equality (). This can be used to implement conditions such
-   * as $u(0,y)=u(1,y+1)$.
+   * The @p offset is a vector tangential to the faces that is added to the
+   * location of vertices of the 'first' boundary when attempting to match
+   * them to the corresponding vertices of the 'second' boundary via
+   * orthogonal_equality (). This can be used to implement conditions such as
+   * $u(0,y)=u(1,y+1)$.
    *
    * @deprecated This function is deprecated. Use
    * GridTools::collect_periodic_faces in conjunction with
@@ -1128,15 +1088,15 @@ namespace DoFTools
 
 
   /**
-   * The @p offset is a vector tangential to the faces that is added to
-   * the location of vertices of the 'first' boundary when attempting to
-   * match them to the corresponding vertices of the 'second' boundary via
-   * orthogonal_equality(). This can be used to implement conditions such
-   * as $u(0,y)=u(1,y+1)$.
+   * The @p offset is a vector tangential to the faces that is added to the
+   * location of vertices of the 'first' boundary when attempting to match
+   * them to the corresponding vertices of the 'second' boundary via
+   * orthogonal_equality(). This can be used to implement conditions such as
+   * $u(0,y)=u(1,y+1)$.
    *
    * @note This version of make_periodicity_constraints  will not work on
-   * meshes with cells not in @ref GlossFaceOrientation
-   * "standard orientation".
+   * meshes with cells not in @ref GlossFaceOrientation "standard
+   * orientation".
    *
    * @deprecated This function is deprecated. Use
    * GridTools::collect_periodic_faces in conjunction with
@@ -1154,35 +1114,32 @@ namespace DoFTools
 
 
   /**
-   * Take a vector of values which live on cells (e.g. an error per
-   * cell) and distribute it to the dofs in such a way that a finite
-   * element field results, which can then be further processed,
-   * e.g. for output. You should note that the resulting field will
-   * not be continuous at hanging nodes. This can, however, easily be
-   * arranged by calling the appropriate @p distribute function of a
-   * ConstraintMatrix object created for this DoFHandler object, after
-   * the vector has been fully assembled.
+   * Take a vector of values which live on cells (e.g. an error per cell) and
+   * distribute it to the dofs in such a way that a finite element field
+   * results, which can then be further processed, e.g. for output. You should
+   * note that the resulting field will not be continuous at hanging nodes.
+   * This can, however, easily be arranged by calling the appropriate @p
+   * distribute function of a ConstraintMatrix object created for this
+   * DoFHandler object, after the vector has been fully assembled.
    *
-   * It is assumed that the number of elements in @p cell_data equals
-   * the number of active cells and that the number of elements in @p
-   * dof_data equals <tt>dof_handler.n_dofs()</tt>.
+   * It is assumed that the number of elements in @p cell_data equals the
+   * number of active cells and that the number of elements in @p dof_data
+   * equals <tt>dof_handler.n_dofs()</tt>.
    *
-   * Note that the input vector may be a vector of any data type as
-   * long as it is convertible to @p double.  The output vector, being
-   * a data vector on a DoF handler, always consists of elements of
-   * type @p double.
+   * Note that the input vector may be a vector of any data type as long as it
+   * is convertible to @p double.  The output vector, being a data vector on a
+   * DoF handler, always consists of elements of type @p double.
    *
-   * In case the finite element used by this DoFHandler consists of
-   * more than one component, you need to specify which component in
-   * the output vector should be used to store the finite element
-   * field in; the default is zero (no other value is allowed if the
-   * finite element consists only of one component). All other
-   * components of the vector remain untouched, i.e. their contents
-   * are not changed.
+   * In case the finite element used by this DoFHandler consists of more than
+   * one component, you need to specify which component in the output vector
+   * should be used to store the finite element field in; the default is zero
+   * (no other value is allowed if the finite element consists only of one
+   * component). All other components of the vector remain untouched, i.e.
+   * their contents are not changed.
    *
-   * This function cannot be used if the finite element in use has
-   * shape functions that are non-zero in more than one vector
-   * component (in deal.II speak: they are non-primitive).
+   * This function cannot be used if the finite element in use has shape
+   * functions that are non-zero in more than one vector component (in deal.II
+   * speak: they are non-primitive).
    */
   template <class DH, typename Number>
   void
@@ -1196,33 +1153,33 @@ namespace DoFTools
    */
 
   /**
-   * @name Identifying subsets of degrees of freedom with particular properties
+   * @name Identifying subsets of degrees of freedom with particular
+   * properties
    * @{
    */
 
   /**
-   * Extract the indices of the degrees of freedom belonging to
-   * certain vector components of a vector-valued finite element. The
-   * @p component_mask defines which components or blocks of an
-   * FESystem are to be extracted from the DoFHandler @p dof. The
-   * entries in the output array @p selected_dofs corresponding to
-   * degrees of freedom belonging to these components are then flagged
-   * @p true, while all others are set to @p false.
+   * Extract the indices of the degrees of freedom belonging to certain vector
+   * components of a vector-valued finite element. The @p component_mask
+   * defines which components or blocks of an FESystem are to be extracted
+   * from the DoFHandler @p dof. The entries in the output array @p
+   * selected_dofs corresponding to degrees of freedom belonging to these
+   * components are then flagged @p true, while all others are set to @p
+   * false.
    *
-   * The size of @p component_mask must be compatible with the number
-   * of components in the FiniteElement used by @p dof. The size of @p
-   * selected_dofs must equal DoFHandler::n_dofs(). Previous contents
-   * of this array are overwritten.
+   * The size of @p component_mask must be compatible with the number of
+   * components in the FiniteElement used by @p dof. The size of @p
+   * selected_dofs must equal DoFHandler::n_dofs(). Previous contents of this
+   * array are overwritten.
    *
-   * If the finite element under consideration is not primitive, i.e.,
-   * some or all of its shape functions are non-zero in more than one
-   * vector component (which holds, for example, for FE_Nedelec or
-   * FE_RaviartThomas elements), then shape functions cannot be
-   * associated with a single vector component. In this case, if
-   * <em>one</em> shape vector component of this element is flagged in
-   * @p component_mask (see @ref GlossComponentMask), then this is
-   * equivalent to selecting <em>all</em> vector components
-   * corresponding to this non-primitive base element.
+   * If the finite element under consideration is not primitive, i.e., some or
+   * all of its shape functions are non-zero in more than one vector component
+   * (which holds, for example, for FE_Nedelec or FE_RaviartThomas elements),
+   * then shape functions cannot be associated with a single vector component.
+   * In this case, if <em>one</em> shape vector component of this element is
+   * flagged in @p component_mask (see @ref GlossComponentMask), then this is
+   * equivalent to selecting <em>all</em> vector components corresponding to
+   * this non-primitive base element.
    *
    * @note If the @p blocks argument is true,
    */
@@ -1242,17 +1199,19 @@ namespace DoFTools
                 std::vector<bool>       &selected_dofs);
 
   /**
-   * This function is the equivalent to the DoFTools::extract_dofs() functions above
-   * except that the selection of which degrees of freedom to extract is not done
-   * based on components (see @ref GlossComponent) but instead based on whether they
-   * are part of a particular block (see @ref GlossBlock). Consequently, the second
-   * argument is not a ComponentMask but a BlockMask object.
+   * This function is the equivalent to the DoFTools::extract_dofs() functions
+   * above except that the selection of which degrees of freedom to extract is
+   * not done based on components (see @ref GlossComponent) but instead based
+   * on whether they are part of a particular block (see @ref GlossBlock).
+   * Consequently, the second argument is not a ComponentMask but a BlockMask
+   * object.
    *
-   * @param dof_handler The DoFHandler object from which to extract degrees of freedom
-   * @param block_mask The block mask that describes which blocks to consider (see
-   *       @ref GlossBlockMask)
-   * @param selected_dofs A vector of length DoFHandler::n_dofs() in which those
-   *       entries are true that correspond to the selected blocks.
+   * @param dof_handler The DoFHandler object from which to extract degrees of
+   * freedom
+   * @param block_mask The block mask that describes which blocks to consider
+   * (see @ref GlossBlockMask)
+   * @param selected_dofs A vector of length DoFHandler::n_dofs() in which
+   * those entries are true that correspond to the selected blocks.
    */
   template <int dim, int spacedim>
   void
@@ -1270,8 +1229,8 @@ namespace DoFTools
                 std::vector<bool>       &selected_dofs);
 
   /**
-   * Do the same thing as the corresponding extract_dofs() function
-   * for one level of a multi-grid DoF numbering.
+   * Do the same thing as the corresponding extract_dofs() function for one
+   * level of a multi-grid DoF numbering.
    */
   template <class DH>
   void
@@ -1281,8 +1240,8 @@ namespace DoFTools
                       std::vector<bool>       &selected_dofs);
 
   /**
-   * Do the same thing as the corresponding extract_dofs() function
-   * for one level of a multi-grid DoF numbering.
+   * Do the same thing as the corresponding extract_dofs() function for one
+   * level of a multi-grid DoF numbering.
    */
   template <class DH>
   void
@@ -1292,55 +1251,48 @@ namespace DoFTools
                       std::vector<bool>       &selected_dofs);
 
   /**
-   * Extract all degrees of freedom which are at the boundary and
-   * belong to specified components of the solution. The function
-   * returns its results in the last non-default-valued parameter
-   * which contains @p true if a degree of freedom is at the boundary
-   * and belongs to one of the selected components, and @p false
-   * otherwise. The function is used in step-15.
-   *
-   * By specifying the @p boundary_indicator variable, you can select
-   * which boundary indicators the faces have to have on which the
-   * degrees of freedom are located that shall be extracted. If it is
-   * an empty list, then all boundary indicators are accepted.
-   *
-   * The size of @p component_mask (see @ref GlossComponentMask) shall
-   * equal the number of components in the finite element used by @p
-   * dof. The size of @p selected_dofs shall equal
-   * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
-   * overwritten.
-   *
-   * Using the usual convention, if a shape function is non-zero in
-   * more than one component (i.e. it is non-primitive), then the
-   * element in the component mask is used that corresponds to the
-   * first non-zero components. Elements in the mask corresponding to
-   * later components are ignored.
-   *
-   * @note This function will not work for DoFHandler objects that are
-   * built on a parallel::distributed::Triangulation object. The
-   * reasons is that the output argument @p selected_dofs has to have
-   * a length equal to <i>all</i> global degrees of freedom.
-   * Consequently, this does not scale to very large problems. If you
-   * need the functionality of this function for parallel
-   * triangulations, then you need to use the other
+   * Extract all degrees of freedom which are at the boundary and belong to
+   * specified components of the solution. The function returns its results in
+   * the last non-default-valued parameter which contains @p true if a degree
+   * of freedom is at the boundary and belongs to one of the selected
+   * components, and @p false otherwise. The function is used in step-15.
+   *
+   * By specifying the @p boundary_indicator variable, you can select which
+   * boundary indicators the faces have to have on which the degrees of
+   * freedom are located that shall be extracted. If it is an empty list, then
+   * all boundary indicators are accepted.
+   *
+   * The size of @p component_mask (see @ref GlossComponentMask) shall equal
+   * the number of components in the finite element used by @p dof. The size
+   * of @p selected_dofs shall equal <tt>dof_handler.n_dofs()</tt>. Previous
+   * contents of this array or overwritten.
+   *
+   * Using the usual convention, if a shape function is non-zero in more than
+   * one component (i.e. it is non-primitive), then the element in the
+   * component mask is used that corresponds to the first non-zero components.
+   * Elements in the mask corresponding to later components are ignored.
+   *
+   * @note This function will not work for DoFHandler objects that are built
+   * on a parallel::distributed::Triangulation object. The reasons is that the
+   * output argument @p selected_dofs has to have a length equal to <i>all</i>
+   * global degrees of freedom. Consequently, this does not scale to very
+   * large problems. If you need the functionality of this function for
+   * parallel triangulations, then you need to use the other
    * DoFTools::extract_boundary_dofs function.
    *
    * @param dof_handler The object that describes which degrees of freedom
-   *          live on which cell
-   * @param component_mask A mask denoting the vector components of the
-   *          finite element that should be considered (see also
-   *          @ref GlossComponentMask).
-   * @param selected_dofs The IndexSet object that is returned and that
-   *          will contain the indices of degrees of freedom that are
-   *          located on the boundary (and correspond to the selected
-   *          vector components and boundary indicators, depending on
-   *          the values of the @p component_mask and @p boundary_indicators
-   *          arguments).
-   * @param boundary_indicators If empty, this function extracts the
-   *          indices of the degrees of freedom for all parts of the boundary.
-   *          If it is a non-empty list, then the function only considers
-   *          boundary faces with the boundary indicators listed in this
-   *          argument.
+   * live on which cell
+   * @param component_mask A mask denoting the vector components of the finite
+   * element that should be considered (see also @ref GlossComponentMask).
+   * @param selected_dofs The IndexSet object that is returned and that will
+   * contain the indices of degrees of freedom that are located on the
+   * boundary (and correspond to the selected vector components and boundary
+   * indicators, depending on the values of the @p component_mask and @p
+   * boundary_indicators arguments).
+   * @param boundary_indicators If empty, this function extracts the indices
+   * of the degrees of freedom for all parts of the boundary. If it is a non-
+   * empty list, then the function only considers boundary faces with the
+   * boundary indicators listed in this argument.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
@@ -1352,33 +1304,30 @@ namespace DoFTools
                          const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
 
   /**
-   * This function does the same as the previous one but it
-   * returns its result as an IndexSet rather than a std::vector@<bool@>.
-   * Thus, it can also be called for DoFHandler objects that are
-   * defined on parallel::distributed::Triangulation objects.
+   * This function does the same as the previous one but it returns its result
+   * as an IndexSet rather than a std::vector@<bool@>. Thus, it can also be
+   * called for DoFHandler objects that are defined on
+   * parallel::distributed::Triangulation objects.
    *
    * @note If the DoFHandler object is indeed defined on a
-   * parallel::distributed::Triangulation, then the @p selected_dofs
-   * index set will contain only those degrees of freedom on the
-   * boundary that belong to the locally relevant set (see
-   * @ref GlossLocallyRelevantDof "locally relevant DoFs").
+   * parallel::distributed::Triangulation, then the @p selected_dofs index set
+   * will contain only those degrees of freedom on the boundary that belong to
+   * the locally relevant set (see @ref GlossLocallyRelevantDof "locally
+   * relevant DoFs").
    *
    * @param dof_handler The object that describes which degrees of freedom
-   *          live on which cell
-   * @param component_mask A mask denoting the vector components of the
-   *          finite element that should be considered (see also
-   *          @ref GlossComponentMask).
-   * @param selected_dofs The IndexSet object that is returned and that
-   *          will contain the indices of degrees of freedom that are
-   *          located on the boundary (and correspond to the selected
-   *          vector components and boundary indicators, depending on
-   *          the values of the @p component_mask and @p boundary_indicators
-   *          arguments).
-   * @param boundary_indicators If empty, this function extracts the
-   *          indices of the degrees of freedom for all parts of the boundary.
-   *          If it is a non-empty list, then the function only considers
-   *          boundary faces with the boundary indicators listed in this
-   *          argument.
+   * live on which cell
+   * @param component_mask A mask denoting the vector components of the finite
+   * element that should be considered (see also @ref GlossComponentMask).
+   * @param selected_dofs The IndexSet object that is returned and that will
+   * contain the indices of degrees of freedom that are located on the
+   * boundary (and correspond to the selected vector components and boundary
+   * indicators, depending on the values of the @p component_mask and @p
+   * boundary_indicators arguments).
+   * @param boundary_indicators If empty, this function extracts the indices
+   * of the degrees of freedom for all parts of the boundary. If it is a non-
+   * empty list, then the function only considers boundary faces with the
+   * boundary indicators listed in this argument.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
@@ -1390,19 +1339,17 @@ namespace DoFTools
                          const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
 
   /**
-   * This function is similar to the extract_boundary_dofs() function
-   * but it extracts those degrees of freedom whose shape functions
-   * are nonzero on at least part of the selected boundary. For
-   * continuous elements, this is exactly the set of shape functions
-   * whose degrees of freedom are defined on boundary faces. On the
-   * other hand, if the finite element in used is a discontinuous
-   * element, all degrees of freedom are defined in the inside of
-   * cells and consequently none would be boundary degrees of
-   * freedom. Several of those would have shape functions that are
-   * nonzero on the boundary, however. This function therefore
-   * extracts all those for which the
-   * FiniteElement::has_support_on_face function says that it is
-   * nonzero on any face on one of the selected boundary parts.
+   * This function is similar to the extract_boundary_dofs() function but it
+   * extracts those degrees of freedom whose shape functions are nonzero on at
+   * least part of the selected boundary. For continuous elements, this is
+   * exactly the set of shape functions whose degrees of freedom are defined
+   * on boundary faces. On the other hand, if the finite element in used is a
+   * discontinuous element, all degrees of freedom are defined in the inside
+   * of cells and consequently none would be boundary degrees of freedom.
+   * Several of those would have shape functions that are nonzero on the
+   * boundary, however. This function therefore extracts all those for which
+   * the FiniteElement::has_support_on_face function says that it is nonzero
+   * on any face on one of the selected boundary parts.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
@@ -1414,37 +1361,35 @@ namespace DoFTools
                                          const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
 
   /**
-   * Extract a vector that represents the constant modes of the
-   * DoFHandler for the components chosen by <tt>component_mask</tt>
-   * (see @ref GlossComponentMask).  The constant modes on a
-   * discretization are the null space of a Laplace operator on the
-   * selected components with Neumann boundary conditions applied. The
-   * null space is a necessary ingredient for obtaining a good AMG
-   * preconditioner when using the class
-   * TrilinosWrappers::PreconditionAMG.  Since the ML AMG package only
-   * works on algebraic properties of the respective matrix, it has no
-   * chance to detect whether the matrix comes from a scalar or a
-   * vector valued problem. However, a near null space supplies
-   * exactly the needed information about the components placement of vector
-   * components within the matrix. The null space (or rather, the constant
-   * modes) is provided by the finite element underlying the given DoFHandler
-   * and for most elements, the null space will consist of as many vectors as
-   * there are true arguments in <tt>component_mask</tt> (see @ref
-   * GlossComponentMask), each of which will be one in one vector component
-   * and zero in all others. However, the representation of the constant
-   * function for e.g. FE_DGP is different (the first component on each
-   * element one, all other components zero), and some scalar elements may
-   * even have two constant modes (FE_Q_DG0). Therefore, we store this object
-   * in a vector of vectors, where the outer vector contains the collection of
-   * the actual constant modes on the DoFHandler. Each inner vector has as
-   * many components as there are (locally owned) degrees of freedom in the
-   * selected components. Note that any matrix associated with this null space
-   * must have been constructed using the same <tt>component_mask</tt>
-   * argument, since the numbering of DoFs is done relative to the selected
-   * dofs, not to all dofs.
-   *
-   * The main reason for this program is the use of the null space
-   * with the AMG preconditioner.
+   * Extract a vector that represents the constant modes of the DoFHandler for
+   * the components chosen by <tt>component_mask</tt> (see @ref
+   * GlossComponentMask).  The constant modes on a discretization are the null
+   * space of a Laplace operator on the selected components with Neumann
+   * boundary conditions applied. The null space is a necessary ingredient for
+   * obtaining a good AMG preconditioner when using the class
+   * TrilinosWrappers::PreconditionAMG.  Since the ML AMG package only works
+   * on algebraic properties of the respective matrix, it has no chance to
+   * detect whether the matrix comes from a scalar or a vector valued problem.
+   * However, a near null space supplies exactly the needed information about
+   * the components placement of vector components within the matrix. The null
+   * space (or rather, the constant modes) is provided by the finite element
+   * underlying the given DoFHandler and for most elements, the null space
+   * will consist of as many vectors as there are true arguments in
+   * <tt>component_mask</tt> (see @ref GlossComponentMask), each of which will
+   * be one in one vector component and zero in all others. However, the
+   * representation of the constant function for e.g. FE_DGP is different (the
+   * first component on each element one, all other components zero), and some
+   * scalar elements may even have two constant modes (FE_Q_DG0). Therefore,
+   * we store this object in a vector of vectors, where the outer vector
+   * contains the collection of the actual constant modes on the DoFHandler.
+   * Each inner vector has as many components as there are (locally owned)
+   * degrees of freedom in the selected components. Note that any matrix
+   * associated with this null space must have been constructed using the same
+   * <tt>component_mask</tt> argument, since the numbering of DoFs is done
+   * relative to the selected dofs, not to all dofs.
+   *
+   * The main reason for this program is the use of the null space with the
+   * AMG preconditioner.
    */
   template <class DH>
   void
@@ -1461,12 +1406,11 @@ namespace DoFTools
    */
 
   /**
-   * Select all dofs that will be constrained by interface
-   * constraints, i.e. all hanging nodes.
+   * Select all dofs that will be constrained by interface constraints, i.e.
+   * all hanging nodes.
    *
-   * The size of @p selected_dofs shall equal
-   * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
-   * overwritten.
+   * The size of @p selected_dofs shall equal <tt>dof_handler.n_dofs()</tt>.
+   * Previous contents of this array or overwritten.
    */
   template <int dim, int spacedim>
   void
@@ -1479,10 +1423,10 @@ namespace DoFTools
    * @{
    */
   /**
-   * Flag all those degrees of freedom which are on cells with the
-   * given subdomain id. Note that DoFs on faces can belong to cells
-   * with differing subdomain ids, so the sets of flagged degrees of
-   * freedom are not mutually exclusive for different subdomain ids.
+   * Flag all those degrees of freedom which are on cells with the given
+   * subdomain id. Note that DoFs on faces can belong to cells with differing
+   * subdomain ids, so the sets of flagged degrees of freedom are not mutually
+   * exclusive for different subdomain ids.
    *
    * If you want to get a unique association of degree of freedom with
    * subdomains, use the @p get_subdomain_association function.
@@ -1495,10 +1439,10 @@ namespace DoFTools
 
 
   /**
-   * Extract the set of global DoF indices that are owned by the
-   * current processor. For regular DoFHandler objects, this set is
-   * the complete set with all DoF indices. In either case, it equals
-   * what DoFHandler::locally_owned_dofs() returns.
+   * Extract the set of global DoF indices that are owned by the current
+   * processor. For regular DoFHandler objects, this set is the complete set
+   * with all DoF indices. In either case, it equals what
+   * DoFHandler::locally_owned_dofs() returns.
    */
   template <class DH>
   void
@@ -1507,19 +1451,18 @@ namespace DoFTools
 
 
   /**
-   * Extract the set of global DoF indices that are active on the
-   * current DoFHandler. For regular DoFHandlers, these are all DoF
-   * indices, but for DoFHandler objects built on
-   * parallel::distributed::Triangulation this set is a superset of
-   * DoFHandler::locally_owned_dofs() and contains all DoF indices
-   * that live on all locally owned cells (including on the interface
-   * to ghost cells). However, it does not contain the DoF indices
-   * that are exclusively defined on ghost or artificial cells (see
-   * @ref GlossArtificialCell "the glossary").
+   * Extract the set of global DoF indices that are active on the current
+   * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
+   * DoFHandler objects built on parallel::distributed::Triangulation this set
+   * is a superset of DoFHandler::locally_owned_dofs() and contains all DoF
+   * indices that live on all locally owned cells (including on the interface
+   * to ghost cells). However, it does not contain the DoF indices that are
+   * exclusively defined on ghost or artificial cells (see @ref
+   * GlossArtificialCell "the glossary").
    *
-   * The degrees of freedom identified by this function equal those
-   * obtained from the dof_indices_with_subdomain_association()
-   * function when called with the locally owned subdomain id.
+   * The degrees of freedom identified by this function equal those obtained
+   * from the dof_indices_with_subdomain_association() function when called
+   * with the locally owned subdomain id.
    */
   template <class DH>
   void
@@ -1527,12 +1470,11 @@ namespace DoFTools
                                IndexSet &dof_set);
 
   /**
-   * Extract the set of global DoF indices that are active on the
-   * current DoFHandler. For regular DoFHandlers, these are all DoF
-   * indices, but for DoFHandler objects built on
-   * parallel::distributed::Triangulation this set is the union of
-   * DoFHandler::locally_owned_dofs() and the DoF indices on all ghost
-   * cells. In essence, it is the DoF indices on all cells that are
+   * Extract the set of global DoF indices that are active on the current
+   * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
+   * DoFHandler objects built on parallel::distributed::Triangulation this set
+   * is the union of DoFHandler::locally_owned_dofs() and the DoF indices on
+   * all ghost cells. In essence, it is the DoF indices on all cells that are
    * not artificial (see @ref GlossArtificialCell "the glossary").
    */
   template <class DH>
@@ -1541,36 +1483,33 @@ namespace DoFTools
                                  IndexSet &dof_set);
 
   /**
-   * For each DoF, return in the output array to which subdomain (as
-   * given by the <tt>cell->subdomain_id()</tt> function) it
-   * belongs. The output array is supposed to have the right size
-   * already when calling this function.
-   *
-   * Note that degrees of freedom associated with faces, edges, and
-   * vertices may be associated with multiple subdomains if they are
-   * sitting on partition boundaries. In these cases, we put them into
-   * one of the associated partitions in an undefined way. This may
-   * sometimes lead to different numbers of degrees of freedom in
-   * partitions, even if the number of cells is perfectly
-   * equidistributed. While this is regrettable, it is not a problem
-   * in practice since the number of degrees of freedom on partition
-   * boundaries is asymptotically vanishing as we refine the mesh as
+   * For each DoF, return in the output array to which subdomain (as given by
+   * the <tt>cell->subdomain_id()</tt> function) it belongs. The output array
+   * is supposed to have the right size already when calling this function.
+   *
+   * Note that degrees of freedom associated with faces, edges, and vertices
+   * may be associated with multiple subdomains if they are sitting on
+   * partition boundaries. In these cases, we put them into one of the
+   * associated partitions in an undefined way. This may sometimes lead to
+   * different numbers of degrees of freedom in partitions, even if the number
+   * of cells is perfectly equidistributed. While this is regrettable, it is
+   * not a problem in practice since the number of degrees of freedom on
+   * partition boundaries is asymptotically vanishing as we refine the mesh as
    * long as the number of partitions is kept constant.
    *
-   * This function returns the association of each DoF with one
-   * subdomain. If you are looking for the association of each @em
-   * cell with a subdomain, either query the
-   * <tt>cell->subdomain_id()</tt> function, or use the
+   * This function returns the association of each DoF with one subdomain. If
+   * you are looking for the association of each @em cell with a subdomain,
+   * either query the <tt>cell->subdomain_id()</tt> function, or use the
    * <tt>GridTools::get_subdomain_association</tt> function.
    *
-   * Note that this function is of questionable use for DoFHandler
-   * objects built on parallel::distributed::Triangulation since in
-   * that case ownership of individual degrees of freedom by MPI
-   * processes is controlled by the DoF handler object, not based on
-   * some geometric algorithm in conjunction with subdomain id. In
-   * particular, the degrees of freedom identified by the functions in
-   * this namespace as associated with a subdomain are not the same
-   * the DoFHandler class identifies as those it owns.
+   * Note that this function is of questionable use for DoFHandler objects
+   * built on parallel::distributed::Triangulation since in that case
+   * ownership of individual degrees of freedom by MPI processes is controlled
+   * by the DoF handler object, not based on some geometric algorithm in
+   * conjunction with subdomain id. In particular, the degrees of freedom
+   * identified by the functions in this namespace as associated with a
+   * subdomain are not the same the DoFHandler class identifies as those it
+   * owns.
    */
   template <class DH>
   void
@@ -1578,31 +1517,29 @@ namespace DoFTools
                              std::vector<types::subdomain_id> &subdomain);
 
   /**
-   * Count how many degrees of freedom are uniquely associated with
-   * the given @p subdomain index.
+   * Count how many degrees of freedom are uniquely associated with the given
+   * @p subdomain index.
    *
-   * Note that there may be rare cases where cells with the given @p
-   * subdomain index exist, but none of its degrees of freedom are
-   * actually associated with it. In that case, the returned value
-   * will be zero.
+   * Note that there may be rare cases where cells with the given @p subdomain
+   * index exist, but none of its degrees of freedom are actually associated
+   * with it. In that case, the returned value will be zero.
    *
-   * This function will generate an exception if there are no cells
-   * with the given @p subdomain index.
+   * This function will generate an exception if there are no cells with the
+   * given @p subdomain index.
    *
-   * This function returns the number of DoFs associated with one
-   * subdomain. If you are looking for the association of @em cells
-   * with this subdomain, use the
-   * <tt>GridTools::count_cells_with_subdomain_association</tt>
+   * This function returns the number of DoFs associated with one subdomain.
+   * If you are looking for the association of @em cells with this subdomain,
+   * use the <tt>GridTools::count_cells_with_subdomain_association</tt>
    * function.
    *
-   * Note that this function is of questionable use for DoFHandler
-   * objects built on parallel::distributed::Triangulation since in
-   * that case ownership of individual degrees of freedom by MPI
-   * processes is controlled by the DoF handler object, not based on
-   * some geometric algorithm in conjunction with subdomain id. In
-   * particular, the degrees of freedom identified by the functions in
-   * this namespace as associated with a subdomain are not the same
-   * the DoFHandler class identifies as those it owns.
+   * Note that this function is of questionable use for DoFHandler objects
+   * built on parallel::distributed::Triangulation since in that case
+   * ownership of individual degrees of freedom by MPI processes is controlled
+   * by the DoF handler object, not based on some geometric algorithm in
+   * conjunction with subdomain id. In particular, the degrees of freedom
+   * identified by the functions in this namespace as associated with a
+   * subdomain are not the same the DoFHandler class identifies as those it
+   * owns.
    */
   template <class DH>
   unsigned int
@@ -1610,24 +1547,23 @@ namespace DoFTools
                                          const types::subdomain_id subdomain);
 
   /**
-   * Count how many degrees of freedom are uniquely associated with
-   * the given @p subdomain index.
+   * Count how many degrees of freedom are uniquely associated with the given
+   * @p subdomain index.
    *
-   * This function does what the previous one does except that it
-   * splits the result among the vector components of the finite
-   * element in use by the DoFHandler object. The last argument (which
-   * must have a length equal to the number of vector components) will
-   * therefore store how many degrees of freedom of each vector
-   * component are associated with the given subdomain.
+   * This function does what the previous one does except that it splits the
+   * result among the vector components of the finite element in use by the
+   * DoFHandler object. The last argument (which must have a length equal to
+   * the number of vector components) will therefore store how many degrees of
+   * freedom of each vector component are associated with the given subdomain.
    *
-   * Note that this function is of questionable use for DoFHandler
-   * objects built on parallel::distributed::Triangulation since in
-   * that case ownership of individual degrees of freedom by MPI
-   * processes is controlled by the DoF handler object, not based on
-   * some geometric algorithm in conjunction with subdomain id. In
-   * particular, the degrees of freedom identified by the functions in
-   * this namespace as associated with a subdomain are not the same
-   * the DoFHandler class identifies as those it owns.
+   * Note that this function is of questionable use for DoFHandler objects
+   * built on parallel::distributed::Triangulation since in that case
+   * ownership of individual degrees of freedom by MPI processes is controlled
+   * by the DoF handler object, not based on some geometric algorithm in
+   * conjunction with subdomain id. In particular, the degrees of freedom
+   * identified by the functions in this namespace as associated with a
+   * subdomain are not the same the DoFHandler class identifies as those it
+   * owns.
    */
   template <class DH>
   void
@@ -1636,26 +1572,24 @@ namespace DoFTools
                                          std::vector<unsigned int> &n_dofs_on_subdomain);
 
   /**
-   * Return a set of indices that denotes the degrees of freedom that
-   * live on the given subdomain, i.e. that are on cells owned by the
-   * current processor. Note that this includes the ones that this
-   * subdomain "owns" (i.e. the ones for which
-   * get_subdomain_association() returns a value equal to the
-   * subdomain given here and that are selected by the
-   * extract_locally_owned() function) but also all of those that sit
-   * on the boundary between the given subdomain and other
-   * subdomain. In essence, degrees of freedom that sit on boundaries
-   * between subdomain will be in the index sets returned by this
-   * function for more than one subdomain.
-   *
-   * Note that this function is of questionable use for DoFHandler
-   * objects built on parallel::distributed::Triangulation since in
-   * that case ownership of individual degrees of freedom by MPI
-   * processes is controlled by the DoF handler object, not based on
-   * some geometric algorithm in conjunction with subdomain id. In
-   * particular, the degrees of freedom identified by the functions in
-   * this namespace as associated with a subdomain are not the same
-   * the DoFHandler class identifies as those it owns.
+   * Return a set of indices that denotes the degrees of freedom that live on
+   * the given subdomain, i.e. that are on cells owned by the current
+   * processor. Note that this includes the ones that this subdomain "owns"
+   * (i.e. the ones for which get_subdomain_association() returns a value
+   * equal to the subdomain given here and that are selected by the
+   * extract_locally_owned() function) but also all of those that sit on the
+   * boundary between the given subdomain and other subdomain. In essence,
+   * degrees of freedom that sit on boundaries between subdomain will be in
+   * the index sets returned by this function for more than one subdomain.
+   *
+   * Note that this function is of questionable use for DoFHandler objects
+   * built on parallel::distributed::Triangulation since in that case
+   * ownership of individual degrees of freedom by MPI processes is controlled
+   * by the DoF handler object, not based on some geometric algorithm in
+   * conjunction with subdomain id. In particular, the degrees of freedom
+   * identified by the functions in this namespace as associated with a
+   * subdomain are not the same the DoFHandler class identifies as those it
+   * owns.
    */
   template <class DH>
   IndexSet
@@ -1665,24 +1599,22 @@ namespace DoFTools
   /**
    * @name DoF indices on patches of cells
    *
-   * Create structures containing a large set of degrees of freedom
-   * for small patches of cells. The resulting objects can be used in
-   * RelaxationBlockSOR and related classes to implement Schwarz
-   * preconditioners and smoothers, where the subdomains consist of
-   * small numbers of cells only.
+   * Create structures containing a large set of degrees of freedom for small
+   * patches of cells. The resulting objects can be used in RelaxationBlockSOR
+   * and related classes to implement Schwarz preconditioners and smoothers,
+   * where the subdomains consist of small numbers of cells only.
    */
   //@{
   /**
-   * Create an incidence matrix that for every cell on a given level
-   * of a multilevel DoFHandler flags which degrees of freedom are
-   * associated with the corresponding cell. This data structure is a
-   * matrix with as many rows as there are cells on a given level, as
-   * many columns as there are degrees of freedom on this level, and
-   * entries that are either true or false. This data structure is
-   * conveniently represented by a SparsityPattern object.
+   * Create an incidence matrix that for every cell on a given level of a
+   * multilevel DoFHandler flags which degrees of freedom are associated with
+   * the corresponding cell. This data structure is a matrix with as many rows
+   * as there are cells on a given level, as many columns as there are degrees
+   * of freedom on this level, and entries that are either true or false. This
+   * data structure is conveniently represented by a SparsityPattern object.
    *
-   * @note The ordering of rows (cells) follows the ordering of the
-   * standard cell iterators.
+   * @note The ordering of rows (cells) follows the ordering of the standard
+   * cell iterators.
    */
   template <class DH, class Sparsity>
   void make_cell_patches(Sparsity &block_list,
@@ -1692,45 +1624,42 @@ namespace DoFTools
                          types::global_dof_index offset = 0);
 
   /**
-   * Create an incidence matrix that for every vertex on a given level
-   * of a multilevel DoFHandler flags which degrees of freedom are
-   * associated with the adjacent cells. This data structure is a matrix
-   * with as many rows as there are vertices on a given level, as many
-   * columns as there are degrees of freedom on this level, and entries
-   * that are either true or false. This data structure is
-   * conveniently represented by a SparsityPattern object.  The
-   * sparsity pattern may be empty when entering this function and
-   * will be reinitialized to the correct size.
+   * Create an incidence matrix that for every vertex on a given level of a
+   * multilevel DoFHandler flags which degrees of freedom are associated with
+   * the adjacent cells. This data structure is a matrix with as many rows as
+   * there are vertices on a given level, as many columns as there are degrees
+   * of freedom on this level, and entries that are either true or false. This
+   * data structure is conveniently represented by a SparsityPattern object.
+   * The sparsity pattern may be empty when entering this function and will be
+   * reinitialized to the correct size.
    *
-   * The function has some boolean arguments (listed below)
-   * controlling details of the generated patches. The default
-   * settings are those for Arnold-Falk-Winther type smoothers for
-   * divergence and curl conforming finite elements with essential
-   * boundary conditions. Other applications are possible, in
-   * particular changing <tt>boundary_patches</tt> for non-essential
-   * boundary conditions.
+   * The function has some boolean arguments (listed below) controlling
+   * details of the generated patches. The default settings are those for
+   * Arnold-Falk-Winther type smoothers for divergence and curl conforming
+   * finite elements with essential boundary conditions. Other applications
+   * are possible, in particular changing <tt>boundary_patches</tt> for non-
+   * essential boundary conditions.
    *
-   * @arg <tt>block_list</tt>: the SparsityPattern into which the
-   * patches will be stored.
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+   * be stored.
    *
-   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
-   * the topology operated on.
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+   * topology operated on.
    *
-   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
-   * a vertex, collect only the interior degrees of freedom of the
-   * patch and disregard those on the boundary of the patch. This is
-   * for instance the setting for smoothers of Arnold-Falk-Winther
-   * type.
+   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
+   * vertex, collect only the interior degrees of freedom of the patch and
+   * disregard those on the boundary of the patch. This is for instance the
+   * setting for smoothers of Arnold-Falk-Winther type.
    *
-   * @arg <tt>boundary_patches</tt>: include patches around vertices
-   * at the boundary of the domain. If not, only patches around
-   * interior vertices will be generated.
+   * @arg <tt>boundary_patches</tt>: include patches around vertices at the
+   * boundary of the domain. If not, only patches around interior vertices
+   * will be generated.
    *
-   * @arg <tt>level_boundary_patches</tt>: same for refinement edges
-   * towards coarser cells.
+   * @arg <tt>level_boundary_patches</tt>: same for refinement edges towards
+   * coarser cells.
    *
-   * @arg <tt>single_cell_patches</tt>: if not true, patches
-   * containing a single cell are eliminated.
+   * @arg <tt>single_cell_patches</tt>: if not true, patches containing a
+   * single cell are eliminated.
    */
   template <class DH>
   void make_vertex_patches(SparsityPattern &block_list,
@@ -1742,45 +1671,43 @@ namespace DoFTools
                            const bool single_cell_patches = false);
 
   /**
-   * Create an incidence matrix that for every cell on a given level
-   * of a multilevel DoFHandler flags which degrees of freedom are
-   * associated with children of this cell. This data structure is
-   * conveniently represented by a SparsityPattern object.
+   * Create an incidence matrix that for every cell on a given level of a
+   * multilevel DoFHandler flags which degrees of freedom are associated with
+   * children of this cell. This data structure is conveniently represented by
+   * a SparsityPattern object.
    *
-   * The function thus creates a sparsity pattern which in each row
-   * (with rows corresponding to the cells on this level) lists the degrees of
-   * freedom associated to the cells that are the children of this
-   * cell. The DoF indices used here are level dof indices of a multilevel
-   * hierarchy, i.e., they may be associated with children that are
-   * not themselves active. The sparsity pattern may be empty when entering this
-   * function and will be reinitialized to the correct size.
+   * The function thus creates a sparsity pattern which in each row (with rows
+   * corresponding to the cells on this level) lists the degrees of freedom
+   * associated to the cells that are the children of this cell. The DoF
+   * indices used here are level dof indices of a multilevel hierarchy, i.e.,
+   * they may be associated with children that are not themselves active. The
+   * sparsity pattern may be empty when entering this function and will be
+   * reinitialized to the correct size.
    *
-   * The function has some boolean arguments (listed below)
-   * controlling details of the generated patches. The default
-   * settings are those for Arnold-Falk-Winther type smoothers for
-   * divergence and curl conforming finite elements with essential
-   * boundary conditions. Other applications are possible, in
-   * particular changing <tt>boundary_dofs</tt> for non-essential
-   * boundary conditions.
+   * The function has some boolean arguments (listed below) controlling
+   * details of the generated patches. The default settings are those for
+   * Arnold-Falk-Winther type smoothers for divergence and curl conforming
+   * finite elements with essential boundary conditions. Other applications
+   * are possible, in particular changing <tt>boundary_dofs</tt> for non-
+   * essential boundary conditions.
    *
    * Since the patches are defined through refinement, th
    *
-   * @arg <tt>block_list</tt>: the SparsityPattern into which the
-   * patches will be stored.
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+   * be stored.
    *
-   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
-   * the topology operated on.
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+   * topology operated on.
    *
-   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
-   * a vertex, collect only the interior degrees of freedom of the
-   * patch and disregard those on the boundary of the patch. This is
-   * for instance the setting for smoothers of Arnold-Falk-Winther
-   * type.
+   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
+   * vertex, collect only the interior degrees of freedom of the patch and
+   * disregard those on the boundary of the patch. This is for instance the
+   * setting for smoothers of Arnold-Falk-Winther type.
    *
-   * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which
-   * would have excluded by <tt>interior_dofs_only</tt>, but are lying
-   * on the boundary of the domain, and thus need smoothing. This
-   * parameter has no effect if <tt>interior_dofs_only</tt> is false.
+   * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which would have
+   * excluded by <tt>interior_dofs_only</tt>, but are lying on the boundary of
+   * the domain, and thus need smoothing. This parameter has no effect if
+   * <tt>interior_dofs_only</tt> is false.
    */
   template <class DH>
   void make_child_patches(SparsityPattern &block_list,
@@ -1790,23 +1717,23 @@ namespace DoFTools
                           const bool boundary_dofs = false);
 
   /**
-   * Create a block list with only a single patch, which in turn
-   * contains all degrees of freedom on the given level.
+   * Create a block list with only a single patch, which in turn contains all
+   * degrees of freedom on the given level.
    *
    * This function is mostly a closure on level 0 for functions like
-   * make_child_patches() and make_vertex_patches(), which may produce
-   * an empty patch list.
+   * make_child_patches() and make_vertex_patches(), which may produce an
+   * empty patch list.
    *
-   * @arg <tt>block_list</tt>: the SparsityPattern into which the
-   * patches will be stored.
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+   * be stored.
    *
-   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
-   * the topology operated on.
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+   * topology operated on.
    *
    * @arg <tt>level</tt> The grid level used for building the list.
    *
-   * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of
-   * freedom on the boundary of the domain.
+   * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of freedom on
+   * the boundary of the domain.
    */
   template <class DH>
   void make_single_patch(SparsityPattern &block_list,
@@ -1823,42 +1750,38 @@ namespace DoFTools
    */
 
   /**
-   * Count how many degrees of freedom out of the total number belong
-   * to each component. If the number of components the finite element
-   * has is one (i.e. you only have one scalar variable), then the
-   * number in this component obviously equals the total number of
-   * degrees of freedom. Otherwise, the sum of the DoFs in all the
-   * components needs to equal the total number.
+   * Count how many degrees of freedom out of the total number belong to each
+   * component. If the number of components the finite element has is one
+   * (i.e. you only have one scalar variable), then the number in this
+   * component obviously equals the total number of degrees of freedom.
+   * Otherwise, the sum of the DoFs in all the components needs to equal the
+   * total number.
    *
-   * However, the last statement does not hold true if the finite
-   * element is not primitive, i.e. some or all of its shape functions
-   * are non-zero in more than one vector component. This applies, for
-   * example, to the Nedelec or Raviart-Thomas elements. In this case,
-   * a degree of freedom is counted in each component in which it is
-   * non-zero, so that the sum mentioned above is greater than the
-   * total number of degrees of freedom.
+   * However, the last statement does not hold true if the finite element is
+   * not primitive, i.e. some or all of its shape functions are non-zero in
+   * more than one vector component. This applies, for example, to the Nedelec
+   * or Raviart-Thomas elements. In this case, a degree of freedom is counted
+   * in each component in which it is non-zero, so that the sum mentioned
+   * above is greater than the total number of degrees of freedom.
    *
    * This behavior can be switched off by the optional parameter
-   * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number
-   * of components of a nonprimitive vector valued element is
-   * collected only in the first component. All other components will
-   * have a count of zero.
-   *
-   * The additional optional argument @p target_component allows for a
-   * re-sorting and grouping of components. To this end, it contains
-   * for each component the component number it shall be counted
-   * as. Having the same number entered several times sums up several
-   * components as the same. One of the applications of this argument
-   * is when you want to form block matrices and vectors, but want to
-   * pack several components into the same block (for example, when
-   * you have @p dim velocities and one pressure, to put all
-   * velocities into one block, and the pressure into another).
-   *
-   * The result is returned in @p dofs_per_component. Note that the
-   * size of @p dofs_per_component needs to be enough to hold all the
-   * indices specified in @p target_component. If this is not the
-   * case, an assertion is thrown. The indices not targeted by
-   * target_components are left untouched.
+   * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number of
+   * components of a nonprimitive vector valued element is collected only in
+   * the first component. All other components will have a count of zero.
+   *
+   * The additional optional argument @p target_component allows for a re-
+   * sorting and grouping of components. To this end, it contains for each
+   * component the component number it shall be counted as. Having the same
+   * number entered several times sums up several components as the same. One
+   * of the applications of this argument is when you want to form block
+   * matrices and vectors, but want to pack several components into the same
+   * block (for example, when you have @p dim velocities and one pressure, to
+   * put all velocities into one block, and the pressure into another).
+   *
+   * The result is returned in @p dofs_per_component. Note that the size of @p
+   * dofs_per_component needs to be enough to hold all the indices specified
+   * in @p target_component. If this is not the case, an assertion is thrown.
+   * The indices not targeted by target_components are left untouched.
    */
   template <class DH>
   void
@@ -1869,20 +1792,18 @@ namespace DoFTools
                             = std::vector<unsigned int>());
 
   /**
-   * Count the degrees of freedom in each block. This function is
-   * similar to count_dofs_per_component(), with the difference that
-   * the counting is done by blocks. See @ref GlossBlock "blocks" in
-   * the glossary for details. Again the vectors are assumed to have
-   * the correct size before calling this function. If this is not the
-   * case, an assertion is thrown.
+   * Count the degrees of freedom in each block. This function is similar to
+   * count_dofs_per_component(), with the difference that the counting is done
+   * by blocks. See @ref GlossBlock "blocks" in the glossary for details.
+   * Again the vectors are assumed to have the correct size before calling
+   * this function. If this is not the case, an assertion is thrown.
    *
-   * This function is used in the step-22, step-31, and step-32
-   * tutorial programs.
+   * This function is used in the step-22, step-31, and step-32 tutorial
+   * programs.
    *
-   * @pre The dofs_per_block variable has as many components as the
-   * finite element used by the dof_handler argument has blocks, or
-   * alternatively as many blocks as are enumerated in the
-   * target_blocks argument if given.
+   * @pre The dofs_per_block variable has as many components as the finite
+   * element used by the dof_handler argument has blocks, or alternatively as
+   * many blocks as are enumerated in the target_blocks argument if given.
    */
   template <class DH>
   void
@@ -1893,8 +1814,8 @@ namespace DoFTools
 
   /**
    * @deprecated See the previous function with the same name for a
-   * description. This function exists for compatibility with older
-   * versions only.
+   * description. This function exists for compatibility with older versions
+   * only.
    */
   template <int dim, int spacedim>
   void
@@ -1904,15 +1825,14 @@ namespace DoFTools
 
 
   /**
-   * For each active cell of a DoFHandler or hp::DoFHandler, extract
-   * the active finite element index and fill the vector given as
-   * second argument. This vector is assumed to have as many entries
-   * as there are active cells.
+   * For each active cell of a DoFHandler or hp::DoFHandler, extract the
+   * active finite element index and fill the vector given as second argument.
+   * This vector is assumed to have as many entries as there are active cells.
    *
-   * For non-hp DoFHandler objects given as first argument, the
-   * returned vector will consist of only zeros, indicating that all
-   * cells use the same finite element. For a hp::DoFHandler, the
-   * values may be different, though.
+   * For non-hp DoFHandler objects given as first argument, the returned
+   * vector will consist of only zeros, indicating that all cells use the same
+   * finite element. For a hp::DoFHandler, the values may be different,
+   * though.
    */
   template <class DH>
   void
@@ -1927,25 +1847,26 @@ namespace DoFTools
    * solution of a local problem on the patch surrounding each of the cells of
    * the mesh. You can get a list of cells that form the patch around a given
    * cell using GridTools::get_patch_around_cell(). This function is then
-   * useful in setting up the size of the linear system used to solve the local
-   * problem on the patch around a cell. The function
-   * DoFTools::get_dofs_on_patch() will then help to make the
-   * connection between global degrees of freedom and the local ones.
-   *
-   * @tparam Container A type that is either DoFHandler or hp::DoFHandler.
-   *   In C++, the compiler can not determine the type of <code>DH</code>
-   *   from the function call. You need to specify it as an explicit template
-   *   argument following the function name.
+   * useful in setting up the size of the linear system used to solve the
+   * local problem on the patch around a cell. The function
+   * DoFTools::get_dofs_on_patch() will then help to make the connection
+   * between global degrees of freedom and the local ones.
+   *
+   * @tparam Container A type that is either DoFHandler or hp::DoFHandler. In
+   * C++, the compiler can not determine the type of <code>DH</code> from the
+   * function call. You need to specify it as an explicit template argument
+   * following the function name.
    * @param patch[in] A collection of cells within an object of type DH
-   * @return The number of degrees of freedom associated with the cells of this patch.
+   * @return The number of degrees of freedom associated with the cells of
+   * this patch.
    *
    * @note In the context of a parallel distributed computation, it only makes
-   * sense to call this function on patches around locally owned cells. This is because the
-   * neighbors of locally owned cells are either locally owned themselves, or
-   * ghost cells. For both, we know that these are in fact the real cells of
-   * the complete, parallel triangulation. We can also query the degrees of
-   * freedom on these. In other words, this function can only work if all
-   * cells in the patch are either locally owned or ghost cells.
+   * sense to call this function on patches around locally owned cells. This
+   * is because the neighbors of locally owned cells are either locally owned
+   * themselves, or ghost cells. For both, we know that these are in fact the
+   * real cells of the complete, parallel triangulation. We can also query the
+   * degrees of freedom on these. In other words, this function can only work
+   * if all cells in the patch are either locally owned or ghost cells.
    *
    * @author Arezou Ghesmati, Wolfgang Bangerth, 2014
    */
@@ -1954,26 +1875,27 @@ namespace DoFTools
   count_dofs_on_patch (const std::vector<typename DH::active_cell_iterator> &patch);
 
   /**
-   * Return the set of degrees of freedom that live on a set of
-   * cells (i.e., a patch) described by the argument.
+   * Return the set of degrees of freedom that live on a set of cells (i.e., a
+   * patch) described by the argument.
    *
    * Patches are often used in defining error estimators that require the
    * solution of a local problem on the patch surrounding each of the cells of
    * the mesh. You can get a list of cells that form the patch around a given
-   * cell using GridTools::get_patch_around_cell(). While DoFTools::count_dofs_on_patch()
-   * can be used to determine the size of these local problems, so that one can assemble
-   * the local system and then solve it, it is still necessary to provide a mapping
-   * between the global indices of the degrees of freedom that live on the patch
-   * and a local enumeration. This function provides such a local enumeration
-   * by returning the set of degrees of freedom that live on the patch.
-   *
-   * Since this set is returned in the form of a std::vector, one can also think
-   * of it as a mapping
+   * cell using GridTools::get_patch_around_cell(). While
+   * DoFTools::count_dofs_on_patch() can be used to determine the size of
+   * these local problems, so that one can assemble the local system and then
+   * solve it, it is still necessary to provide a mapping between the global
+   * indices of the degrees of freedom that live on the patch and a local
+   * enumeration. This function provides such a local enumeration by returning
+   * the set of degrees of freedom that live on the patch.
+   *
+   * Since this set is returned in the form of a std::vector, one can also
+   * think of it as a mapping
    * @code
    *   i -> global_dof_index
    * @endcode
-   * where <code>i</code> is an index into the returned vector (i.e., a
-   * the <i>local</i> index of a degree of freedom on the patch) and
+   * where <code>i</code> is an index into the returned vector (i.e., a the
+   * <i>local</i> index of a degree of freedom on the patch) and
    * <code>global_dof_index</code> is the global index of a degree of freedom
    * located on the patch. The array returned has size equal to
    * DoFTools::count_dofs_on_patch().
@@ -1982,21 +1904,21 @@ namespace DoFTools
    * one considers the index into this array a local DoF index, then the local
    * system that results retains the block structure of the global system.
    *
-   * @tparam Container A type that is either DoFHandler or hp::DoFHandler.
-   *   In C++, the compiler can not determine the type of <code>DH</code>
-   *   from the function call. You need to specify it as an explicit template
-   *   argument following the function name.
+   * @tparam Container A type that is either DoFHandler or hp::DoFHandler. In
+   * C++, the compiler can not determine the type of <code>DH</code> from the
+   * function call. You need to specify it as an explicit template argument
+   * following the function name.
    * @param patch[in] A collection of cells within an object of type DH
-   * @return A list of those global degrees of freedom located on the
-   *   patch, as defined above.
+   * @return A list of those global degrees of freedom located on the patch,
+   * as defined above.
    *
    * @note In the context of a parallel distributed computation, it only makes
-   * sense to call this function on patches around locally owned cells. This is because the
-   * neighbors of locally owned cells are either locally owned themselves, or
-   * ghost cells. For both, we know that these are in fact the real cells of
-   * the complete, parallel triangulation. We can also query the degrees of
-   * freedom on these. In other words, this function can only work if all
-   * cells in the patch are either locally owned or ghost cells.
+   * sense to call this function on patches around locally owned cells. This
+   * is because the neighbors of locally owned cells are either locally owned
+   * themselves, or ghost cells. For both, we know that these are in fact the
+   * real cells of the complete, parallel triangulation. We can also query the
+   * degrees of freedom on these. In other words, this function can only work
+   * if all cells in the patch are either locally owned or ghost cells.
    *
    * @author Arezou Ghesmati, Wolfgang Bangerth, 2014
    */
@@ -2009,15 +1931,14 @@ namespace DoFTools
    */
 
   /**
-   * Create a mapping from degree of freedom indices to the index of
-   * that degree of freedom on the boundary. After this operation,
-   * <tt>mapping[dof]</tt> gives the index of the degree of freedom
-   * with global number @p dof in the list of degrees of freedom on
-   * the boundary.  If the degree of freedom requested is not on the
-   * boundary, the value of <tt>mapping[dof]</tt> is @p
-   * invalid_dof_index. This function is mainly used when setting up
-   * matrices and vectors on the boundary from the trial functions,
-   * which have global numbers, while the matrices and vectors use
+   * Create a mapping from degree of freedom indices to the index of that
+   * degree of freedom on the boundary. After this operation,
+   * <tt>mapping[dof]</tt> gives the index of the degree of freedom with
+   * global number @p dof in the list of degrees of freedom on the boundary.
+   * If the degree of freedom requested is not on the boundary, the value of
+   * <tt>mapping[dof]</tt> is @p invalid_dof_index. This function is mainly
+   * used when setting up matrices and vectors on the boundary from the trial
+   * functions, which have global numbers, while the matrices and vectors use
    * numbers of the trial functions local to the boundary.
    *
    * Prior content of @p mapping is deleted.
@@ -2028,9 +1949,9 @@ namespace DoFTools
                                std::vector<types::global_dof_index>  &mapping);
 
   /**
-   * Same as the previous function, except that only those parts of
-   * the boundary are considered for which the boundary indicator is
-   * listed in the second argument.
+   * Same as the previous function, except that only those parts of the
+   * boundary are considered for which the boundary indicator is listed in the
+   * second argument.
    *
    * See the general doc of this class for more information.
    *
@@ -2043,21 +1964,19 @@ namespace DoFTools
                                std::vector<types::global_dof_index>     &mapping);
 
   /**
-   * Return a list of support points (see this @ref GlossSupport
-   * "glossary entry") for all the degrees of freedom handled by this
-   * DoF handler object. This function, of course, only works if the
-   * finite element object used by the DoF handler object actually
-   * provides support points, i.e. no edge elements or the
-   * like. Otherwise, an exception is thrown.
+   * Return a list of support points (see this @ref GlossSupport "glossary
+   * entry") for all the degrees of freedom handled by this DoF handler
+   * object. This function, of course, only works if the finite element object
+   * used by the DoF handler object actually provides support points, i.e. no
+   * edge elements or the like. Otherwise, an exception is thrown.
    *
-   * @pre The given array must have a length of as many elements as
-   * there are degrees of freedom.
+   * @pre The given array must have a length of as many elements as there are
+   * degrees of freedom.
    *
-   * @note The precondition to this function that the output argument
-   * needs to have size equal to the total number of degrees of
-   * freedom makes this function unsuitable for the case that the
-   * given DoFHandler object derives from a
-   * parallel::distributed::Triangulation object.  Consequently, this
+   * @note The precondition to this function that the output argument needs to
+   * have size equal to the total number of degrees of freedom makes this
+   * function unsuitable for the case that the given DoFHandler object derives
+   * from a parallel::distributed::Triangulation object.  Consequently, this
    * function will produce an error if called with such a DoFHandler.
    */
   template <int dim, int spacedim>
@@ -2078,30 +1997,29 @@ namespace DoFTools
 
   /**
    * This function is a version of the above map_dofs_to_support_points
-   * function that doesn't simply return a vector of support points (see
-   * this @ref GlossSupport "glossary entry") with one
-   * entry for each global degree of freedom, but instead a map that
-   * maps from the DoFs index to its location. The point of this
-   * function is that it is also usable in cases where the DoFHandler
-   * is based on a parallel::distributed::Triangulation object. In such cases,
-   * each processor will not be able to determine the support point location
-   * of all DoFs, and worse no processor may be able to hold a vector that
-   * would contain the locations of all DoFs even if they were known. As
-   * a consequence, this function constructs a map from those DoFs for which
-   * we can know the locations (namely, those DoFs that are
-   * locally relevant (see @ref GlossLocallyRelevantDof "locally relevant DoFs")
-   * to their locations.
+   * function that doesn't simply return a vector of support points (see this
+   * @ref GlossSupport "glossary entry") with one entry for each global degree
+   * of freedom, but instead a map that maps from the DoFs index to its
+   * location. The point of this function is that it is also usable in cases
+   * where the DoFHandler is based on a parallel::distributed::Triangulation
+   * object. In such cases, each processor will not be able to determine the
+   * support point location of all DoFs, and worse no processor may be able to
+   * hold a vector that would contain the locations of all DoFs even if they
+   * were known. As a consequence, this function constructs a map from those
+   * DoFs for which we can know the locations (namely, those DoFs that are
+   * locally relevant (see @ref GlossLocallyRelevantDof "locally relevant
+   * DoFs") to their locations.
    *
    * For non-distributed triangulations, the map returned as @p support_points
    * is of course dense, i.e., every DoF is to be found in it.
    *
    * @param mapping The mapping from the reference cell to the real cell on
-   *        which DoFs are defined.
+   * which DoFs are defined.
    * @param dof_handler The object that describes which DoF indices live on
-   *        which cell of the triangulation.
+   * which cell of the triangulation.
    * @param support_points A map that for every locally relevant DoF index
-   *        contains the corresponding location in real space coordinates.
-   *        Previous content of this object is deleted in this function.
+   * contains the corresponding location in real space coordinates. Previous
+   * content of this object is deleted in this function.
    */
   template <int dim, int spacedim>
   void
@@ -2120,20 +2038,19 @@ namespace DoFTools
 
 
   /**
-   * This is the opposite function to the one above. It generates a
-   * map where the keys are the support points of the degrees of
-   * freedom, while the values are the DoF indices. For a definition
-   * of support points, see this @ref GlossSupport "glossary entry".
+   * This is the opposite function to the one above. It generates a map where
+   * the keys are the support points of the degrees of freedom, while the
+   * values are the DoF indices. For a definition of support points, see this
+   * @ref GlossSupport "glossary entry".
    *
-   * Since there is no natural order in the space of points (except
-   * for the 1d case), you have to provide a map with an explicitly
-   * specified comparator object. This function is therefore
-   * templatized on the comparator object. Previous content of the map
-   * object is deleted in this function.
+   * Since there is no natural order in the space of points (except for the 1d
+   * case), you have to provide a map with an explicitly specified comparator
+   * object. This function is therefore templatized on the comparator object.
+   * Previous content of the map object is deleted in this function.
    *
-   * Just as with the function above, it is assumed that the finite
-   * element in use here actually supports the notion of support
-   * points of all its components.
+   * Just as with the function above, it is assumed that the finite element in
+   * use here actually supports the notion of support points of all its
+   * components.
    */
   template <class DH, class Comp>
   void
@@ -2142,13 +2059,13 @@ namespace DoFTools
                               std::map<Point<DH::space_dimension>, types::global_dof_index, Comp> &point_to_index_map);
 
   /**
-   * Map a coupling table from the user friendly organization by
-   * components to the organization by blocks. Specializations of this
-   * function for DoFHandler and hp::DoFHandler are required due to
-   * the different results of their finite element access.
+   * Map a coupling table from the user friendly organization by components to
+   * the organization by blocks. Specializations of this function for
+   * DoFHandler and hp::DoFHandler are required due to the different results
+   * of their finite element access.
    *
-   * The return vector will be initialized to the correct length
-   * inside this function.
+   * The return vector will be initialized to the correct length inside this
+   * function.
    */
   template <int dim, int spacedim>
   void
@@ -2157,40 +2074,37 @@ namespace DoFTools
                                std::vector<Table<2,Coupling> > &tables_by_block);
 
   /**
-   * Make a constraint matrix for the constraints that result from
-   * zero boundary values on the given boundary indicator.
+   * Make a constraint matrix for the constraints that result from zero
+   * boundary values on the given boundary indicator.
    *
-   * This function constrains all degrees of freedom on the given part
-   * of the boundary.
+   * This function constrains all degrees of freedom on the given part of the
+   * boundary.
    *
-   * A variant of this function with different arguments is used in
-   * step-36.
+   * A variant of this function with different arguments is used in step-36.
    *
    * @param dof The DoFHandler to work on.
-   * @param boundary_indicator The indicator of that part of the boundary
-   *   for which constraints should be computed. If this number equals
-   *   numbers::invalid_boundary_id then all boundaries of the domain
-   *   will be treated.
+   * @param boundary_indicator The indicator of that part of the boundary for
+   * which constraints should be computed. If this number equals
+   * numbers::invalid_boundary_id then all boundaries of the domain will be
+   * treated.
    * @param zero_boundary_constraints The constraint object into which the
-   *   constraints will be written. The new constraints due to zero boundary
-   *   values will simply be added, preserving any other constraints
-   *   previously present. However, this will only work if the previous
-   *   content of that object consists of constraints on degrees of freedom
-   *   that are not located on the boundary treated here. If there are
-   *   previously existing constraints for degrees of freedom located on the
-   *   boundary, then this would constitute a conflict. See the @ref constraints
-   *   module for handling the case where there are conflicting constraints
-   *   on individual degrees of freedom.
-   * @param component_mask An optional component mask that
-   *   restricts the functionality of this function to a subset of an FESystem.
-   *   For non-@ref GlossPrimitive "primitive"
-   *   shape functions, any degree of freedom
-   *   is affected that belongs to a
-   *   shape function where at least
-   *   one of its nonzero components
-   *   is affected by the component mask (see @ref GlossComponentMask). If
-   *   this argument is omitted, all components of the finite element with
-   *   degrees of freedom at the boundary will be considered.
+   * constraints will be written. The new constraints due to zero boundary
+   * values will simply be added, preserving any other constraints previously
+   * present. However, this will only work if the previous content of that
+   * object consists of constraints on degrees of freedom that are not located
+   * on the boundary treated here. If there are previously existing
+   * constraints for degrees of freedom located on the boundary, then this
+   * would constitute a conflict. See the @ref constraints module for handling
+   * the case where there are conflicting constraints on individual degrees of
+   * freedom.
+   * @param component_mask An optional component mask that restricts the
+   * functionality of this function to a subset of an FESystem. For non-@ref
+   * GlossPrimitive "primitive" shape functions, any degree of freedom is
+   * affected that belongs to a shape function where at least one of its
+   * nonzero components is affected by the component mask (see @ref
+   * GlossComponentMask). If this argument is omitted, all components of the
+   * finite element with degrees of freedom at the boundary will be
+   * considered.
    *
    * @ingroup constraints
    *
@@ -2204,10 +2118,10 @@ namespace DoFTools
                                   const ComponentMask    &component_mask = ComponentMask());
 
   /**
-   * Do the same as the previous function, except do it for all
-   * parts of the boundary, not just those with a particular boundary
-   * indicator. This function is then equivalent to calling the previous
-   * one with numbers::invalid_boundary_id as second argument.
+   * Do the same as the previous function, except do it for all parts of the
+   * boundary, not just those with a particular boundary indicator. This
+   * function is then equivalent to calling the previous one with
+   * numbers::invalid_boundary_id as second argument.
    *
    * This function is used in step-36, for example.
    *
@@ -2221,13 +2135,13 @@ namespace DoFTools
 
 
   /**
-   * Map a coupling table from the user friendly organization by
-   * components to the organization by blocks. Specializations of this
-   * function for DoFHandler and hp::DoFHandler are required due to
-   * the different results of their finite element access.
+   * Map a coupling table from the user friendly organization by components to
+   * the organization by blocks. Specializations of this function for
+   * DoFHandler and hp::DoFHandler are required due to the different results
+   * of their finite element access.
    *
-   * The return vector will be initialized to the correct length
-   * inside this function.
+   * The return vector will be initialized to the correct length inside this
+   * function.
    */
   template <int dim, int spacedim>
   void
@@ -2236,10 +2150,9 @@ namespace DoFTools
                                std::vector<Table<2,Coupling> > &tables_by_block);
 
   /**
-   * Given a finite element and a table how the vector components of
-   * it couple with each other, compute and return a table that
-   * describes how the individual shape functions couple with each
-   * other.
+   * Given a finite element and a table how the vector components of it couple
+   * with each other, compute and return a table that describes how the
+   * individual shape functions couple with each other.
    */
   template <int dim, int spacedim>
   Table<2,Coupling>
@@ -2247,11 +2160,11 @@ namespace DoFTools
                                           const Table<2,Coupling> &component_couplings);
 
   /**
-   * Same function as above for a collection of finite elements,
-   * returning a collection of tables.
+   * Same function as above for a collection of finite elements, returning a
+   * collection of tables.
    *
-   * The function currently treats DoFTools::Couplings::nonzero the
-   * same as DoFTools::Couplings::always .
+   * The function currently treats DoFTools::Couplings::nonzero the same as
+   * DoFTools::Couplings::always .
    */
   template <int dim, int spacedim>
   std::vector<Table<2,Coupling> >
@@ -2277,8 +2190,8 @@ namespace DoFTools
    */
   DeclException0 (ExcGridsDontMatch);
   /**
-   * The ::DoFHandler or hp::DoFHandler was not initialized with a
-   * finite element. Please call DoFHandler::distribute_dofs() etc. first.
+   * The ::DoFHandler or hp::DoFHandler was not initialized with a finite
+   * element. Please call DoFHandler::distribute_dofs() etc. first.
    *
    * @ingroup Exceptions
    */
index e69f6a2df383e6542b3335e5ac28866266c9abec..a682cf8cf184d448e126f442824ba37124bc5e47 100644 (file)
@@ -26,40 +26,38 @@ template <int spacedim, typename Number> class Function;
 
 
 /**
- * This class declares a local typedef that denotes a mapping between a boundary indicator
- * (see @ref GlossBoundaryIndicator) that is used to describe what kind of boundary
- * condition holds on a particular piece of the boundary,
- * and the function describing the actual function that provides the boundary
- * values on this part of the boundary. This type is required in many functions
- * in the library where, for example, we need to know about the functions $h_i(\mathbf x)$
- * used in boundary conditions
- * @f{align*}
- *   \mathbf n \cdot \nabla u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega.
- * @f}
- * An example is the function KellyErrorEstimator::estimate() that allows us
- * to provide a set of functions $h_i$ for all those boundary indicators $i$ for
- * which the boundary condition is supposed to be of Neumann type. Of course,
- * the same kind of principle can be applied to cases where we care about
- * Dirichlet values, where one needs to provide a map from boundary indicator $i$
- * to Dirichlet function $h_i$ if the boundary conditions are given as
- * @f{align*}
- *   u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega.
- * @f}
- * This is, for example, the case for the VectorTools::interpolate() functions.
+ * This class declares a local typedef that denotes a mapping between a
+ * boundary indicator (see @ref GlossBoundaryIndicator) that is used to
+ * describe what kind of boundary condition holds on a particular piece of the
+ * boundary, and the function describing the actual function that provides the
+ * boundary values on this part of the boundary. This type is required in many
+ * functions in the library where, for example, we need to know about the
+ * functions $h_i(\mathbf x)$ used in boundary conditions @f{align*} \mathbf n
+ * \cdot \nabla u = h_i \qquad \qquad \text{on}\
+ * \Gamma_i\subset\partial\Omega. @f} An example is the function
+ * KellyErrorEstimator::estimate() that allows us to provide a set of
+ * functions $h_i$ for all those boundary indicators $i$ for which the
+ * boundary condition is supposed to be of Neumann type. Of course, the same
+ * kind of principle can be applied to cases where we care about Dirichlet
+ * values, where one needs to provide a map from boundary indicator $i$ to
+ * Dirichlet function $h_i$ if the boundary conditions are given as @f{align*}
+ * u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega. @f} This
+ * is, for example, the case for the VectorTools::interpolate() functions.
  *
  * Tutorial programs step-6, step-7 and step-8 show examples of how to use
- * function arguments of this type in situations where we actually have an empty
- * map (i.e., we want to describe that <i>no</i> part of the boundary is a
- * Neumann boundary). step-16 actually uses it in a case where one of the
- * parts of the boundary uses a boundary indicator for which we want to use
- * function object.
+ * function arguments of this type in situations where we actually have an
+ * empty map (i.e., we want to describe that <i>no</i> part of the boundary is
+ * Neumann boundary). step-16 actually uses it in a case where one of the
+ * parts of the boundary uses a boundary indicator for which we want to use a
+ * function object.
  *
  * It seems odd at first to declare this typedef inside a class, rather than
  * declaring a typedef at global scope. The reason is that C++ does not allow
  * to define templated typedefs, where here in fact we want a typdef that
- * depends on the space dimension. (Defining templated typedefs is something that
- * is possible starting with the C++11 standard, but that wasn't possible within
- * the C++98 standard in place when this programming pattern was conceived.)
+ * depends on the space dimension. (Defining templated typedefs is something
+ * that is possible starting with the C++11 standard, but that wasn't possible
+ * within the C++98 standard in place when this programming pattern was
+ * conceived.)
  *
  * @ingroup functions
  * @author Wolfgang Bangerth, Ralf Hartmann, 2001
@@ -68,13 +66,9 @@ template<int dim,typename Number=double>
 struct FunctionMap
 {
   /**
-   * Declare the type as discussed
-   * above. Since we can't name it
-   * FunctionMap (as that would
-   * ambiguate a possible
-   * constructor of this class),
-   * name it in the fashion of the
-   * STL local typedefs.
+   * Declare the type as discussed above. Since we can't name it FunctionMap
+   * (as that would ambiguate a possible constructor of this class), name it
+   * in the fashion of the STL local typedefs.
    */
   typedef std::map<types::boundary_id, const Function<dim,Number>*> type;
 };
index 3dfe70dbc3cfe1d517e7daece45d22d383d55e95..f6254719a64090105f9949a473c0b679d27562ee 100644 (file)
@@ -29,10 +29,8 @@ namespace internal
   namespace DoFHandler
   {
     /**
-     * A structure used by the
-     * DoFHandler classes to store
-     * information about the degrees
-     * of freedom they deal with.
+     * A structure used by the DoFHandler classes to store information about
+     * the degrees of freedom they deal with.
      */
     struct NumberCache
     {
@@ -42,9 +40,8 @@ namespace internal
       NumberCache ();
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes) of
-       * this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
@@ -54,58 +51,41 @@ namespace internal
       void clear ();
 
       /**
-       * Total number of dofs,
-       * accumulated over all
-       * processors that may
+       * Total number of dofs, accumulated over all processors that may
        * participate on this mesh.
        */
       types::global_dof_index n_global_dofs;
 
       /**
-       * Number of dofs owned by
-       * this MPI process. If this
-       * is a sequential
-       * computation, then this
-       * equals n_global_dofs.
+       * Number of dofs owned by this MPI process. If this is a sequential
+       * computation, then this equals n_global_dofs.
        */
       types::global_dof_index n_locally_owned_dofs;
 
       /**
-       * An index set denoting the
-       * set of locally owned
-       * dofs. If this is a
-       * sequential computation,
-       * then it contains the
-       * entire range
+       * An index set denoting the set of locally owned dofs. If this is a
+       * sequential computation, then it contains the entire range
        * [0,n_global_dofs).
        */
       IndexSet locally_owned_dofs;
 
       /**
-       * The number of dofs owned
-       * by each of the various MPI
-       * processes. If this is a
-       * sequential job, then the
-       * vector contains a single
-       * element equal to
-       * n_global_dofs.
+       * The number of dofs owned by each of the various MPI processes. If
+       * this is a sequential job, then the vector contains a single element
+       * equal to n_global_dofs.
        */
       std::vector<types::global_dof_index> n_locally_owned_dofs_per_processor;
 
       /**
-       * The dofs owned by each of
-       * the various MPI
-       * processes. If this is a
-       * sequential job, then the
-       * vector has a single
-       * element equal to
+       * The dofs owned by each of the various MPI processes. If this is a
+       * sequential job, then the vector has a single element equal to
        * locally_owned_dofs.
        */
       std::vector<IndexSet> locally_owned_dofs_per_processor;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize (Archive &ar,
index 20f3fb42d780d4e1efad4ea360d9aafb579bae5a..a7a21a3ac797a3759dd3ead06ee31c748f3d72de 100644 (file)
@@ -28,36 +28,33 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class represents a mask that can be used to select individual
- * vector blocks of a finite element (see also
- * @ref GlossBlockMask "this glossary entry"). It will typically have as many
- * elements as the finite element has blocks, and one can
- * use <code>operator[]</code> to query whether a particular block
- * has been selected.
+ * This class represents a mask that can be used to select individual vector
+ * blocks of a finite element (see also @ref GlossBlockMask "this glossary
+ * entry"). It will typically have as many elements as the finite element has
+ * blocks, and one can use <code>operator[]</code> to query whether a
+ * particular block has been selected.
  *
  * The semantics of this class are the same as the related ComponentMask
- * class, i.e., a default constructed mask represents all possible
- * blocks. See there for more information about these semantics.
+ * class, i.e., a default constructed mask represents all possible blocks. See
+ * there for more information about these semantics.
  *
  * Objects of this kind are used in many places where one wants to restrict
  * operations to a certain subset of blocks, e.g. in DoFTools::extract_dofs.
- * These objects can
- * either be created by hand, or, simpler, by asking the finite element
- * to generate a block mask from certain selected blocks using
- * code such as this where we create a mask that only denotes the
- * velocity block of a Stokes element (see @ref vector_valued):
+ * These objects can either be created by hand, or, simpler, by asking the
+ * finite element to generate a block mask from certain selected blocks using
+ * code such as this where we create a mask that only denotes the velocity
+ * block of a Stokes element (see @ref vector_valued):
  * @code
  *   FESystem<dim> stokes_fe (FESystem<dim>(FE_Q<dim>(2), dim), 1,    // Q2 element for the velocities
  *                            FE_Q<dim>(1),                     1);     // Q1 element for the pressure
  *   FEValuesExtractors::Scalar pressure(dim);
  *   BlockMask pressure_mask = stokes_fe.block_mask (pressure);
  * @endcode
- * Note that by wrapping the velocity elements into a single FESystem
- * object we make sure that the overall element has only 2 blocks.
- * The result is a block mask that, in both 2d and 3d, would have values
- * <code>[false, true]</code>. (Compare this to the corresponding
- * component mask discussed in the ComponentMask documentation.)
- * Similarly, using
+ * Note that by wrapping the velocity elements into a single FESystem object
+ * we make sure that the overall element has only 2 blocks. The result is a
+ * block mask that, in both 2d and 3d, would have values <code>[false,
+ * true]</code>. (Compare this to the corresponding component mask discussed
+ * in the ComponentMask documentation.) Similarly, using
  * @code
  *   FEValuesExtractors::Vector velocities(0);
  *   BlockMask velocity_mask = stokes_fe.block_mask (velocities);
@@ -73,75 +70,68 @@ class BlockMask
 {
 public:
   /**
-   * Initialize a block mask. The default is that a block
-   * mask represents a set of blocks that are <i>all</i>
-   * selected, i.e., calling this constructor results in
-   * a block mask that always returns <code>true</code>
+   * Initialize a block mask. The default is that a block mask represents a
+   * set of blocks that are <i>all</i> selected, i.e., calling this
+   * constructor results in a block mask that always returns <code>true</code>
    * whenever asked whether a block is selected.
    */
   BlockMask ();
 
   /**
-   * Initialize an object of this type with a set of selected
-   * blocks specified by the argument.
+   * Initialize an object of this type with a set of selected blocks specified
+   * by the argument.
    *
-   * @param block_mask A vector of <code>true/false</code>
-   * entries that determine which blocks of a finite element
-   * are selected. If the length of the given vector is zero,
-   * then this interpreted as the case where <i>every</i> block
-   * is selected.
+   * @param block_mask A vector of <code>true/false</code> entries that
+   * determine which blocks of a finite element are selected. If the length of
+   * the given vector is zero, then this interpreted as the case where
+   * <i>every</i> block is selected.
    */
   BlockMask (const std::vector<bool> &block_mask);
 
   /**
-   * Initialize the block mask with a number of elements that
-   * are either all true or false.
+   * Initialize the block mask with a number of elements that are either all
+   * true or false.
    *
    * @param n_blocks The number of elements of this mask
    * @param initializer The value each of these elements is supposed to have:
-   *                    either true or false.
+   * either true or false.
    */
   BlockMask (const unsigned int n_blocks,
              const bool         initializer);
 
   /**
-   * If this block mask has been initialized with a mask of
-   * size greater than zero, then return the size of the mask
-   * represented by this object. On the other hand, if this
-   * mask has been initialized as an empty object that represents
-   * a mask that is true for every element (i.e., if this object
-   * would return true when calling represents_the_all_selected_mask())
-   * then return zero since no definite size is known.
+   * If this block mask has been initialized with a mask of size greater than
+   * zero, then return the size of the mask represented by this object. On the
+   * other hand, if this mask has been initialized as an empty object that
+   * represents a mask that is true for every element (i.e., if this object
+   * would return true when calling represents_the_all_selected_mask()) then
+   * return zero since no definite size is known.
    */
   unsigned int size () const;
 
   /**
-   * Return whether a particular block is selected by this
-   * mask. If this mask represents the case of an object that
-   * selects <i>all blocks</i> (e.g. if it is created
-   * using the default constructor or is converted from an
-   * empty vector of type bool) then this function returns
-   * true regardless of the given argument.
+   * Return whether a particular block is selected by this mask. If this mask
+   * represents the case of an object that selects <i>all blocks</i> (e.g. if
+   * it is created using the default constructor or is converted from an empty
+   * vector of type bool) then this function returns true regardless of the
+   * given argument.
    *
-   * @param block_index The index for which the function
-   * should return whether the block is selected. If this
-   * object represents a mask in which all blocks are always
-   * selected then any index is allowed here. Otherwise, the
-   * given index needs to be between zero and the number of
-   * blocks that this mask represents.
+   * @param block_index The index for which the function should return whether
+   * the block is selected. If this object represents a mask in which all
+   * blocks are always selected then any index is allowed here. Otherwise, the
+   * given index needs to be between zero and the number of blocks that this
+   * mask represents.
    */
   bool operator[] (const unsigned int block_index) const;
 
   /**
-   * Return whether this block mask represents a mask with
-   * exactly <code>n</code> blocks. This is true if either
-   * it was initilized with a vector with exactly <code>n</code>
-   * entries of type <code>bool</code> (in this case, @p n must
-   * equal the result of size()) or if it was initialized
-   * with an empty vector (or using the default constructor) in
-   * which case it can represent a mask with an arbitrary number
-   * of blocks and will always say that a block is
-   * selected.
+   * Return whether this block mask represents a mask with exactly
+   * <code>n</code> blocks. This is true if either it was initilized with a
+   * vector with exactly <code>n</code> entries of type <code>bool</code> (in
+   * this case, @p n must equal the result of size()) or if it was initialized
+   * with an empty vector (or using the default constructor) in which case it
+   * can represent a mask with an arbitrary number of blocks and will always
+   * say that a block is selected.
    */
   bool
   represents_n_blocks (const unsigned int n) const;
@@ -149,25 +139,22 @@ public:
   /**
    * Return the number of blocks that are selected by this mask.
    *
-   * Since empty block masks represent a block mask that
-   * would return <code>true</code> for every block, this
-   * function may not know the true size of the block
-   * mask and it therefore requires an argument that denotes the
-   * overall number of blocks.
+   * Since empty block masks represent a block mask that would return
+   * <code>true</code> for every block, this function may not know the true
+   * size of the block mask and it therefore requires an argument that denotes
+   * the overall number of blocks.
    *
-   * If the object has been initialized with a non-empty mask (i.e.,
-   * if the size() function returns something greater than zero,
-   * or equivalently if represents_the_all_selected_mask() returns
-   * false) then the argument can be omitted and the result of size()
-   * is taken.
+   * If the object has been initialized with a non-empty mask (i.e., if the
+   * size() function returns something greater than zero, or equivalently if
+   * represents_the_all_selected_mask() returns false) then the argument can
+   * be omitted and the result of size() is taken.
    */
   unsigned int
   n_selected_blocks (const unsigned int overall_number_of_blocks = numbers::invalid_unsigned_int) const;
 
   /**
-   * Return the index of the first selected block. The argument
-   * is there for the same reason it exists with the
-   * n_selected_blocks() function.
+   * Return the index of the first selected block. The argument is there for
+   * the same reason it exists with the n_selected_blocks() function.
    *
    * The function throws an exception if no block is selected at all.
    */
@@ -175,25 +162,22 @@ public:
   first_selected_block (const unsigned int overall_number_of_blocks = numbers::invalid_unsigned_int) const;
 
   /**
-   * Return true if this mask represents a default
-   * constructed mask that corresponds to one in which
-   * all blocks are selected. If true, then the size()
-   * function will return zero.
+   * Return true if this mask represents a default constructed mask that
+   * corresponds to one in which all blocks are selected. If true, then the
+   * size() function will return zero.
    */
   bool
   represents_the_all_selected_mask () const;
 
   /**
-   * Return a block mask that contains the union of the
-   * blocks selected by the current object and the one
-   * passed as an argument.
+   * Return a block mask that contains the union of the blocks selected by the
+   * current object and the one passed as an argument.
    */
   BlockMask operator | (const BlockMask &mask) const;
 
   /**
-   * Return a block mask that has only those elements set that
-   * are set both in the current object as well as the one
-   * passed as an argument.
+   * Return a block mask that has only those elements set that are set both in
+   * the current object as well as the one passed as an argument.
    */
   BlockMask operator & (const BlockMask &mask) const;
 
@@ -208,9 +192,8 @@ public:
   bool operator!= (const BlockMask &mask) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t
   memory_consumption () const;
@@ -230,16 +213,14 @@ private:
 
 
 /**
- * Write a block mask to an output stream. If the block
- * mask represents one where all blocks are selected without
- * specifying a particular size of the mask, then it
- * writes the string <code>[all blocks selected]</code> to the
+ * Write a block mask to an output stream. If the block mask represents one
+ * where all blocks are selected without specifying a particular size of the
+ * mask, then it writes the string <code>[all blocks selected]</code> to the
  * stream. Otherwise, it prints the block mask in a form like
  * <code>[true,true,true,false]</code>.
  *
  * @param out The stream to write to.
- * @param mask The mask to write.
- * @return A reference to the first argument.
+ * @param mask The mask to write. @return A reference to the first argument.
  */
 std::ostream &operator << (std::ostream &out,
                            const BlockMask &mask);
index f1f3c931e03fb4f2c71b7ea43c9379ce20a26c3f..495dd24f55cb3d686080684d71b5a10dad578876 100644 (file)
@@ -28,34 +28,34 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class represents a mask that can be used to select individual
- * vector components of a finite element (see also
- * @ref GlossComponentMask "this glossary entry"). It will typically have as many
- * elements as the finite element has vector components, and one can
- * use <code>operator[]</code> to query whether a particular component
- * has been selected.
+ * This class represents a mask that can be used to select individual vector
+ * components of a finite element (see also @ref GlossComponentMask "this
+ * glossary entry"). It will typically have as many elements as the finite
+ * element has vector components, and one can use <code>operator[]</code> to
+ * query whether a particular component has been selected.
  *
  * Objects of this kind are used in many places where one wants to restrict
- * operations to a certain subset of components, e.g. in DoFTools::make_zero_boundary_values
- * or VectorTools::interpolate_boundary_values. These objects can
- * either be created by hand, or, simpler, by asking the finite element
- * to generate a component mask from certain selected components using
- * code such as this where we create a mask that only denotes the
- * velocity components of a Stokes element (see @ref vector_valued):
+ * operations to a certain subset of components, e.g. in
+ * DoFTools::make_zero_boundary_values or
+ * VectorTools::interpolate_boundary_values. These objects can either be
+ * created by hand, or, simpler, by asking the finite element to generate a
+ * component mask from certain selected components using code such as this
+ * where we create a mask that only denotes the velocity components of a
+ * Stokes element (see @ref vector_valued):
  * @code
  *   FESystem<dim> stokes_fe (FE_Q<dim>(2), dim,    // Q2 element for the velocities
  *                            FE_Q<dim>(1), 1);     // Q1 element for the pressure
  *   FEValuesExtractors::Scalar pressure(dim);
  *   ComponentMask pressure_mask = stokes_fe.component_mask (pressure);
  * @endcode
- * The result is a component mask that, in 2d, would have values
- * <code>[false, false, true]</code>. Similarly, using
+ * The result is a component mask that, in 2d, would have values <code>[false,
+ * false, true]</code>. Similarly, using
  * @code
  *   FEValuesExtractors::Vector velocities(0);
  *   ComponentMask velocity_mask = stokes_fe.component_mask (velocities);
  * @endcode
- * would result in a mask <code>[true, true, false]</code> in 2d. Of
- * course, in 3d, the result would be <code>[true, true, true, false]</code>.
+ * would result in a mask <code>[true, true, false]</code> in 2d. Of course,
+ * in 3d, the result would be <code>[true, true, true, false]</code>.
  *
  * @ingroup fe
  * @author Wolfgang Bangerth
@@ -66,33 +66,31 @@ class ComponentMask
 {
 public:
   /**
-   * Initialize a component mask. The default is that a component
-   * mask represents a set of components that are <i>all</i>
-   * selected, i.e., calling this constructor results in
-   * a component mask that always returns <code>true</code>
-   * whenever asked whether a component is selected.
+   * Initialize a component mask. The default is that a component mask
+   * represents a set of components that are <i>all</i> selected, i.e.,
+   * calling this constructor results in a component mask that always returns
+   * <code>true</code> whenever asked whether a component is selected.
    */
   ComponentMask ();
 
   /**
-   * Initialize an object of this type with a set of selected
-   * components specified by the argument.
+   * Initialize an object of this type with a set of selected components
+   * specified by the argument.
    *
-   * @param component_mask A vector of <code>true/false</code>
-   * entries that determine which components of a finite element
-   * are selected. If the length of the given vector is zero,
-   * then this interpreted as the case where <i>every</i> component
-   * is selected.
+   * @param component_mask A vector of <code>true/false</code> entries that
+   * determine which components of a finite element are selected. If the
+   * length of the given vector is zero, then this interpreted as the case
+   * where <i>every</i> component is selected.
    */
   ComponentMask (const std::vector<bool> &component_mask);
 
   /**
-   * Initialize the component mask with a number of elements that
-   * are either all true or false.
+   * Initialize the component mask with a number of elements that are either
+   * all true or false.
    *
    * @param n_components The number of elements of this mask
    * @param initializer The value each of these elements is supposed to have:
-   *                    either true or false.
+   * either true or false.
    */
   ComponentMask (const unsigned int n_components,
                  const bool         initializer);
@@ -103,43 +101,38 @@ public:
   void set (const unsigned int index, const bool value);
 
   /**
-   * If this component mask has been initialized with a mask of
-   * size greater than zero, then return the size of the mask
-   * represented by this object. On the other hand, if this
-   * mask has been initialized as an empty object that represents
-   * a mask that is true for every element (i.e., if this object
-   * would return true when calling represents_the_all_selected_mask())
+   * If this component mask has been initialized with a mask of size greater
+   * than zero, then return the size of the mask represented by this object.
+   * On the other hand, if this mask has been initialized as an empty object
+   * that represents a mask that is true for every element (i.e., if this
+   * object would return true when calling represents_the_all_selected_mask())
    * then return zero since no definite size is known.
    */
   unsigned int size () const;
 
   /**
-   * Return whether a particular component is selected by this
-   * mask. If this mask represents the case of an object that
-   * selects <i>all components</i> (e.g. if it is created
-   * using the default constructor or is converted from an
-   * empty vector of type bool) then this function returns
-   * true regardless of the given argument.
+   * Return whether a particular component is selected by this mask. If this
+   * mask represents the case of an object that selects <i>all components</i>
+   * (e.g. if it is created using the default constructor or is converted from
+   * an empty vector of type bool) then this function returns true regardless
+   * of the given argument.
    *
-   * @param component_index The index for which the function
-   * should return whether the component is selected. If this
-   * object represents a mask in which all components are always
-   * selected then any index is allowed here. Otherwise, the
-   * given index needs to be between zero and the number of
+   * @param component_index The index for which the function should return
+   * whether the component is selected. If this object represents a mask in
+   * which all components are always selected then any index is allowed here.
+   * Otherwise, the given index needs to be between zero and the number of
    * components that this mask represents.
    */
   bool operator[] (const unsigned int component_index) const;
 
   /**
-   * Return whether this component mask represents a mask with
-   * exactly <code>n</code> components. This is true if either
-   * it was initilized with a vector with exactly <code>n</code>
-   * entries of type <code>bool</code> (in this case, @p n must
-   * equal the result of size()) or if it was initialized
-   * with an empty vector (or using the default constructor) in
-   * which case it can represent a mask with an arbitrary number
-   * of components and will always say that a component is
-   * selected.
+   * Return whether this component mask represents a mask with exactly
+   * <code>n</code> components. This is true if either it was initilized with
+   * a vector with exactly <code>n</code> entries of type <code>bool</code>
+   * (in this case, @p n must equal the result of size()) or if it was
+   * initialized with an empty vector (or using the default constructor) in
+   * which case it can represent a mask with an arbitrary number of components
+   * and will always say that a component is selected.
    */
   bool
   represents_n_components (const unsigned int n) const;
@@ -147,25 +140,22 @@ public:
   /**
    * Return the number of components that are selected by this mask.
    *
-   * Since empty component masks represent a component mask that
-   * would return <code>true</code> for every component, this
-   * function may not know the true size of the component
-   * mask and it therefore requires an argument that denotes the
-   * overall number of components.
+   * Since empty component masks represent a component mask that would return
+   * <code>true</code> for every component, this function may not know the
+   * true size of the component mask and it therefore requires an argument
+   * that denotes the overall number of components.
    *
-   * If the object has been initialized with a non-empty mask (i.e.,
-   * if the size() function returns something greater than zero,
-   * or equivalently if represents_the_all_selected_mask() returns
-   * false) then the argument can be omitted and the result of size()
-   * is taken.
+   * If the object has been initialized with a non-empty mask (i.e., if the
+   * size() function returns something greater than zero, or equivalently if
+   * represents_the_all_selected_mask() returns false) then the argument can
+   * be omitted and the result of size() is taken.
    */
   unsigned int
   n_selected_components (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;
 
   /**
-   * Return the index of the first selected component. The argument
-   * is there for the same reason it exists with the
-   * n_selected_components() function.
+   * Return the index of the first selected component. The argument is there
+   * for the same reason it exists with the n_selected_components() function.
    *
    * The function throws an exception if no component is selected at all.
    */
@@ -173,25 +163,22 @@ public:
   first_selected_component (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;
 
   /**
-   * Return true if this mask represents a default
-   * constructed mask that corresponds to one in which
-   * all components are selected. If true, then the size()
-   * function will return zero.
+   * Return true if this mask represents a default constructed mask that
+   * corresponds to one in which all components are selected. If true, then
+   * the size() function will return zero.
    */
   bool
   represents_the_all_selected_mask () const;
 
   /**
-   * Return a component mask that contains the union of the
-   * components selected by the current object and the one
-   * passed as an argument.
+   * Return a component mask that contains the union of the components
+   * selected by the current object and the one passed as an argument.
    */
   ComponentMask operator | (const ComponentMask &mask) const;
 
   /**
-   * Return a component mask that has only those elements set that
-   * are set both in the current object as well as the one
-   * passed as an argument.
+   * Return a component mask that has only those elements set that are set
+   * both in the current object as well as the one passed as an argument.
    */
   ComponentMask operator & (const ComponentMask &mask) const;
 
@@ -206,9 +193,8 @@ public:
   bool operator!= (const ComponentMask &mask) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t
   memory_consumption () const;
@@ -233,16 +219,14 @@ private:
 
 
 /**
- * Write a component mask to an output stream. If the component
- * mask represents one where all components are selected without
- * specifying a particular size of the mask, then it
- * writes the string <code>[all components selected]</code> to the
- * stream. Otherwise, it prints the component mask in a form like
- * <code>[true,true,true,false]</code>.
+ * Write a component mask to an output stream. If the component mask
+ * represents one where all components are selected without specifying a
+ * particular size of the mask, then it writes the string <code>[all
+ * components selected]</code> to the stream. Otherwise, it prints the
+ * component mask in a form like <code>[true,true,true,false]</code>.
  *
  * @param out The stream to write to.
- * @param mask The mask to write.
- * @return A reference to the first argument.
+ * @param mask The mask to write. @return A reference to the first argument.
  */
 std::ostream &operator << (std::ostream &out,
                            const ComponentMask &mask);
index 6ba42c504d12acb0d45c12c783b2b1c8fbb1f58f..e57cef0e962b933e30d3d9db3e27fc21a21119f7 100644 (file)
@@ -39,73 +39,67 @@ namespace hp
 
 
 /**
- * Base class for finite elements in arbitrary dimensions. This class
- * provides several fields which describe a specific finite element
- * and which are filled by derived classes. It more or less only
- * offers the fields and access functions which makes it possible to
- * copy finite elements without knowledge of the actual type (linear,
- * quadratic, etc). In particular, the functions to fill the data
- * fields of FEValues and its derived classes are declared.
+ * Base class for finite elements in arbitrary dimensions. This class provides
+ * several fields which describe a specific finite element and which are
+ * filled by derived classes. It more or less only offers the fields and
+ * access functions which makes it possible to copy finite elements without
+ * knowledge of the actual type (linear, quadratic, etc). In particular, the
+ * functions to fill the data fields of FEValues and its derived classes are
+ * declared.
  *
- * The interface of this class is very restrictive. The reason is that
- * finite element values should be accessed only by use of FEValues
- * objects. These, together with FiniteElement are responsible to
- * provide an optimized implementation.
+ * The interface of this class is very restrictive. The reason is that finite
+ * element values should be accessed only by use of FEValues objects. These,
+ * together with FiniteElement are responsible to provide an optimized
+ * implementation.
  *
- * This class declares the shape functions and their derivatives on
- * the unit cell $[0,1]^d$. The means to transform them onto a given
- * cell in physical space is provided by the FEValues class with a
- * Mapping object.
+ * This class declares the shape functions and their derivatives on the unit
+ * cell $[0,1]^d$. The means to transform them onto a given cell in physical
+ * space is provided by the FEValues class with a Mapping object.
  *
- * The different matrices are initialized with the correct size, such
- * that in the derived (concrete) finite element classes, their
- * entries only have to be filled in; no resizing is needed. If the
- * matrices are not defined by a concrete finite element, they should
- * be resized to zero. This way functions using them can find out,
- * that they are missing. On the other hand, it is possible to use
- * finite element classes without implementation of the full
- * functionality, if only part of it is needed. The functionality
- * under consideration here is hanging nodes constraints and grid
- * transfer, respectively.
+ * The different matrices are initialized with the correct size, such that in
+ * the derived (concrete) finite element classes, their entries only have to
+ * be filled in; no resizing is needed. If the matrices are not defined by a
+ * concrete finite element, they should be resized to zero. This way functions
+ * using them can find out, that they are missing. On the other hand, it is
+ * possible to use finite element classes without implementation of the full
+ * functionality, if only part of it is needed. The functionality under
+ * consideration here is hanging nodes constraints and grid transfer,
+ * respectively.
  *
- * The <tt>spacedim</tt> parameter has to be used if one wants to
- * solve problems in the boundary element method formulation or in an
- * equivalent one, as it is explained in the Triangulation class. If
- * not specified, this parameter takes the default value <tt>=dim</tt>
- * so that this class can be used to solve problems in the finite
- * element method formulation.
+ * The <tt>spacedim</tt> parameter has to be used if one wants to solve
+ * problems in the boundary element method formulation or in an equivalent
+ * one, as it is explained in the Triangulation class. If not specified, this
+ * parameter takes the default value <tt>=dim</tt> so that this class can be
+ * used to solve problems in the finite element method formulation.
  *
  * <h3>Components and blocks</h3>
  *
- * For vector valued elements shape functions may have nonzero entries
- * in one or several @ref GlossComponent "components" of the vector
- * valued function. If the element is @ref GlossPrimitive "primitive",
- * there is indeed a single component with a nonzero entry for each
- * shape function. This component can be determined by
- * system_to_component_index(), the number of components is
+ * For vector valued elements shape functions may have nonzero entries in one
+ * or several @ref GlossComponent "components" of the vector valued function.
+ * If the element is @ref GlossPrimitive "primitive", there is indeed a single
+ * component with a nonzero entry for each shape function. This component can
+ * be determined by system_to_component_index(), the number of components is
  * FiniteElementData::n_components().
  *
- * Furthermore, you may want to split your linear system into @ref
- * GlossBlock "blocks" for the use in BlockVector, BlockSparseMatrix,
- * BlockMatrixArray and so on. If you use non-primitive elements, you
- * cannot determine the block number by
- * system_to_component_index(). Instead, you can use
+ * Furthermore, you may want to split your linear system into @ref GlossBlock
+ * "blocks" for the use in BlockVector, BlockSparseMatrix, BlockMatrixArray
+ * and so on. If you use non-primitive elements, you cannot determine the
+ * block number by system_to_component_index(). Instead, you can use
  * system_to_block_index(), which will automatically take care of the
- * additional components occupied by vector valued elements. The
- * number of generated blocks can be determined by
- * FiniteElementData::n_blocks().
+ * additional components occupied by vector valued elements. The number of
+ * generated blocks can be determined by FiniteElementData::n_blocks().
  *
- * If you decide to operate by base element and multiplicity, the
- * function first_block_of_base() will be helpful.
+ * If you decide to operate by base element and multiplicity, the function
+ * first_block_of_base() will be helpful.
  *
  * <h3>Support points</h3>
  *
- * Since a FiniteElement does not have information on the actual grid
- * cell, it can only provide @ref GlossSupport "support points" on the
- * unit cell. Support points on the actual grid cell must be computed
- * by mapping these points. The class used for this kind of operation
- * is FEValues. In most cases, code of the following type will serve
- * to provide the mapped support points.
+ * Since a FiniteElement does not have information on the actual grid cell, it
+ * can only provide @ref GlossSupport "support points" on the unit cell.
+ * Support points on the actual grid cell must be computed by mapping these
+ * points. The class used for this kind of operation is FEValues. In most
+ * cases, code of the following type will serve to provide the mapped support
+ * points.
  *
  * @code
  * Quadrature<dim> dummy_quadrature (fe.get_unit_support_points());
@@ -123,63 +117,62 @@ namespace hp
  * Point<dim> mapped_point =
  *    mapping.transform_unit_to_real_cell (cell, unit_points[i]);
  * @endcode
- * This is a shortcut, and as all shortcuts should be used cautiously.
- * If the mapping of all support points is needed, the first variant should
- * be preferred for efficiency.
+ * This is a shortcut, and as all shortcuts should be used cautiously. If the
+ * mapping of all support points is needed, the first variant should be
+ * preferred for efficiency.
  *
  * @note Finite elements' implementation of the get_unit_support_points()
- * returns these points in the same order as shape functions. As a consequence,
- * the quadrature points accessed above are also ordered in this way. The
- * order of shape functions is typically documented in the class documentation
- * of the various finite element classes.
+ * returns these points in the same order as shape functions. As a
+ * consequence, the quadrature points accessed above are also ordered in this
+ * way. The order of shape functions is typically documented in the class
+ * documentation of the various finite element classes.
  *
  *
  * <h3>Notes on the implementation of derived classes</h3>
  *
- * The following sections list the information to be provided by
- * derived classes, depending on the dimension. They are
- * followed by a list of functions helping to generate these values.
+ * The following sections list the information to be provided by derived
+ * classes, depending on the dimension. They are followed by a list of
+ * functions helping to generate these values.
  *
  * <h4>Finite elements in one dimension</h4>
  *
- * Finite elements in one dimension need only set the #restriction
- * and #prolongation matrices. The constructor of this class in one
- * dimension presets the #interface_constraints matrix to have
- * dimension zero. Changing this behaviour in derived classes is
- * generally not a reasonable idea and you risk getting into trouble.
+ * Finite elements in one dimension need only set the #restriction and
+ * #prolongation matrices. The constructor of this class in one dimension
+ * presets the #interface_constraints matrix to have dimension zero. Changing
+ * this behaviour in derived classes is generally not a reasonable idea and
+ * you risk getting into trouble.
  *
  * <h4>Finite elements in two dimensions</h4>
  *
- * In addition to the fields already present in 1D, a constraint
- * matrix is needed, if the finite element has node values located on
- * edges or vertices. These constraints are represented by an $m\times
- * n$-matrix #interface_constraints, where <i>m</i> is the number of
- * degrees of freedom on the refined side without the corner vertices
- * (those dofs on the middle vertex plus those on the two lines), and
- * <i>n</i> is that of the unrefined side (those dofs on the two
- * vertices plus those on the line). The matrix is thus a rectangular
- * one. The $m\times n$ size of the #interface_constraints matrix can
- * also be accessed through the interface_constraints_size() function.
+ * In addition to the fields already present in 1D, a constraint matrix is
+ * needed, if the finite element has node values located on edges or vertices.
+ * These constraints are represented by an $m\times n$-matrix
+ * #interface_constraints, where <i>m</i> is the number of degrees of freedom
+ * on the refined side without the corner vertices (those dofs on the middle
+ * vertex plus those on the two lines), and <i>n</i> is that of the unrefined
+ * side (those dofs on the two vertices plus those on the line). The matrix is
+ * thus a rectangular one. The $m\times n$ size of the #interface_constraints
+ * matrix can also be accessed through the interface_constraints_size()
+ * function.
  *
- * The mapping of the dofs onto the indices of the matrix on the
- * unrefined side is as follows: let $d_v$ be the number of dofs on a
- * vertex, $d_l$ that on a line, then $n=0...d_v-1$ refers to the dofs
- * on vertex zero of the unrefined line, $n=d_v...2d_v-1$ to those on
- * vertex one, $n=2d_v...2d_v+d_l-1$ to those on the line.
+ * The mapping of the dofs onto the indices of the matrix on the unrefined
+ * side is as follows: let $d_v$ be the number of dofs on a vertex, $d_l$ that
+ * on a line, then $n=0...d_v-1$ refers to the dofs on vertex zero of the
+ * unrefined line, $n=d_v...2d_v-1$ to those on vertex one,
+ * $n=2d_v...2d_v+d_l-1$ to those on the line.
  *
- * Similarly, $m=0...d_v-1$ refers to the dofs on the middle vertex of
- * the refined side (vertex one of child line zero, vertex zero of
- * child line one), $m=d_v...d_v+d_l-1$ refers to the dofs on child
- * line zero, $m=d_v+d_l...d_v+2d_l-1$ refers to the dofs on child
- * line one.  Please note that we do not need to reserve space for the
- * dofs on the end vertices of the refined lines, since these must be
- * mapped one-to-one to the appropriate dofs of the vertices of the
- * unrefined line.
+ * Similarly, $m=0...d_v-1$ refers to the dofs on the middle vertex of the
+ * refined side (vertex one of child line zero, vertex zero of child line
+ * one), $m=d_v...d_v+d_l-1$ refers to the dofs on child line zero,
+ * $m=d_v+d_l...d_v+2d_l-1$ refers to the dofs on child line one.  Please note
+ * that we do not need to reserve space for the dofs on the end vertices of
+ * the refined lines, since these must be mapped one-to-one to the appropriate
+ * dofs of the vertices of the unrefined line.
  *
  * It should be noted that it is not possible to distribute a constrained
  * degree of freedom to other degrees of freedom which are themselves
- * constrained. Only one level of indirection is allowed. It is not known
- * at the time of this writing whether this is a constraint itself.
+ * constrained. Only one level of indirection is allowed. It is not known at
+ * the time of this writing whether this is a constraint itself.
  *
  *
  * <h4>Finite elements in three dimensions</h4>
@@ -189,22 +182,21 @@ namespace hp
  * to the usual numbering of degrees of freedom on quadrilaterals.
  *
  * The numbering of the degrees of freedom on the interior of the refined
- * faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above,
- * and $d_q$ be the number of degrees of freedom per quadrilateral (and
- * therefore per face), then $m=0...d_v-1$ denote the dofs on the vertex at
- * the center, $m=d_v...5d_v-1$ for the dofs on the vertices at the center
- * of the bounding lines of the quadrilateral,
- * $m=5d_v..5d_v+4*d_l-1$ are for the degrees of freedom on
- * the four lines connecting the center vertex to the outer boundary of the
- * mother face, $m=5d_v+4*d_l...5d_v+4*d_l+8*d_l-1$ for the degrees of freedom
- * on the small lines surrounding the quad,
- * and $m=5d_v+12*d_l...5d_v+12*d_l+4*d_q-1$ for the dofs on the
- * four child faces. Note the direction of the lines at the boundary of the
- * quads, as shown below.
+ * faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above, and
+ * $d_q$ be the number of degrees of freedom per quadrilateral (and therefore
+ * per face), then $m=0...d_v-1$ denote the dofs on the vertex at the center,
+ * $m=d_v...5d_v-1$ for the dofs on the vertices at the center of the bounding
+ * lines of the quadrilateral, $m=5d_v..5d_v+4*d_l-1$ are for the degrees of
+ * freedom on the four lines connecting the center vertex to the outer
+ * boundary of the mother face, $m=5d_v+4*d_l...5d_v+4*d_l+8*d_l-1$ for the
+ * degrees of freedom on the small lines surrounding the quad, and
+ * $m=5d_v+12*d_l...5d_v+12*d_l+4*d_q-1$ for the dofs on the four child faces.
+ * Note the direction of the lines at the boundary of the quads, as shown
+ * below.
  *
  * The order of the twelve lines and the four child faces can be extracted
- * from the following sketch, where the overall order of the different
- * dof groups is depicted:
+ * from the following sketch, where the overall order of the different dof
+ * groups is depicted:
  * @verbatim
  *    *--15--4--16--*
  *    |      |      |
@@ -216,10 +208,10 @@ namespace hp
  *    |      |      |
  *    *--13--3--14--*
  * @endverbatim
- * The numbering of vertices and lines, as well as the numbering of
- * children within a line is consistent with the one described in
- * Triangulation. Therefore, this numbering is seen from the
- * outside and inside, respectively, depending on the face.
+ * The numbering of vertices and lines, as well as the numbering of children
+ * within a line is consistent with the one described in Triangulation.
+ * Therefore, this numbering is seen from the outside and inside,
+ * respectively, depending on the face.
  *
  * The three-dimensional case has a few pitfalls available for derived classes
  * that want to implement constraint matrices. Consider the following case:
@@ -243,15 +235,15 @@ namespace hp
  * Now assume that we want to refine cell 2. We will end up with two faces
  * with hanging nodes, namely the faces between cells 1 and 2, as well as
  * between cells 2 and 3. Constraints have to be applied to the degrees of
- * freedom on both these faces. The problem is that there is now an edge
- * (the top right one of cell 2) which is part of both faces. The hanging
- * node(s) on this edge are therefore constrained twice, once from both
- * faces. To be meaningful, these constraints of course have to be
- * consistent: both faces have to constrain the hanging nodes on the edge to
- * the same nodes on the coarse edge (and only on the edge, as there can
- * then be no constraints to nodes on the rest of the face), and they have
- * to do so with the same weights. This is sometimes tricky since the nodes
- * on the edge may have different local numbers.
+ * freedom on both these faces. The problem is that there is now an edge (the
+ * top right one of cell 2) which is part of both faces. The hanging node(s)
+ * on this edge are therefore constrained twice, once from both faces. To be
+ * meaningful, these constraints of course have to be consistent: both faces
+ * have to constrain the hanging nodes on the edge to the same nodes on the
+ * coarse edge (and only on the edge, as there can then be no constraints to
+ * nodes on the rest of the face), and they have to do so with the same
+ * weights. This is sometimes tricky since the nodes on the edge may have
+ * different local numbers.
  *
  * For the constraint matrix this means the following: if a degree of freedom
  * on one edge of a face is constrained by some other nodes on the same edge
@@ -265,52 +257,49 @@ namespace hp
  *
  * <h4>Helper functions</h4>
  *
- * Construction of a finite element and computation of the matrices
- * described above may be a tedious task, in particular if it has to
- * be performed for several dimensions. Therefore, some
- * functions in FETools have been provided to help with these tasks.
+ * Construction of a finite element and computation of the matrices described
+ * above may be a tedious task, in particular if it has to be performed for
+ * several dimensions. Therefore, some functions in FETools have been provided
+ * to help with these tasks.
  *
  * <h5>Computing the correct basis from "raw" basis functions</h5>
  *
- * First, already the basis of the shape function space may be
- * difficult to implement for arbitrary order and dimension. On the
- * other hand, if the @ref GlossNodes "node values" are given, then
- * the duality relation between node functionals and basis functions
- * defines the basis. As a result, the shape function space may be
- * defined with arbitrary "raw" basis functions, such that the actual
- * finite element basis is computed from linear combinations of
- * them. The coefficients of these combinations are determined by the
+ * First, already the basis of the shape function space may be difficult to
+ * implement for arbitrary order and dimension. On the other hand, if the @ref
+ * GlossNodes "node values" are given, then the duality relation between node
+ * functionals and basis functions defines the basis. As a result, the shape
+ * function space may be defined with arbitrary "raw" basis functions, such
+ * that the actual finite element basis is computed from linear combinations
+ * of them. The coefficients of these combinations are determined by the
  * duality of node values.
  *
- * Using this matrix allows the construction of the basis of shape
- * functions in two steps.
+ * Using this matrix allows the construction of the basis of shape functions
+ * in two steps.
  * <ol>
  *
  * <li>Define the space of shape functions using an arbitrary basis
- * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node
- * functionals <i>N<sub>i</sub></i> applied to these basis functions,
- * such that its entries are <i>m<sub>ij</sub> =
- * N<sub>i</sub>(w<sub>j</sub>)</i>.
+ * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node functionals
+ * <i>N<sub>i</sub></i> applied to these basis functions, such that its
+ * entries are <i>m<sub>ij</sub> = N<sub>i</sub>(w<sub>j</sub>)</i>.
  *
- * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element
- * shape function space by applying <i>M<sup>-1</sup></i> to the basis
+ * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element shape
+ * function space by applying <i>M<sup>-1</sup></i> to the basis
  * <i>w<sub>j</sub></i>.
  * </ol>
  *
  * The function computing the matrix <i>M</i> for you is
  * FETools::compute_node_matrix(). It relies on the existence of
- * #generalized_support_points and implementation of interpolate()
- * with VectorSlice argument.
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * #generalized_support_points and implementation of interpolate() with
+ * VectorSlice argument. See the @ref GlossGeneralizedSupport "glossary entry
+ * on generalized support points" for more information.
  *
- * The piece of code in the constructor of a finite element
- * responsible for this looks like
+ * The piece of code in the constructor of a finite element responsible for
+ * this looks like
  * @code
- FullMatrix<double> M(this->dofs_per_cell, this->dofs_per_cell);
- FETools::compute_node_matrix(M, *this);
- this->inverse_node_matrix.reinit(this->dofs_per_cell, this->dofs_per_cell);
- this->inverse_node_matrix.invert(M);
FullMatrix<double> M(this->dofs_per_cell, this->dofs_per_cell);
FETools::compute_node_matrix(M, *this);
this->inverse_node_matrix.reinit(this->dofs_per_cell, this->dofs_per_cell);
this->inverse_node_matrix.invert(M);
  * @endcode
  * Don't forget to make sure that #unit_support_points or
  * #generalized_support_points are initialized before this!
@@ -323,10 +312,10 @@ namespace hp
  *
  * This can be achieved by
  * @code
- for (unsigned int i=0; i<GeometryInfo<dim>::children_per_cell; ++i)
- this->prolongation[i].reinit (this->dofs_per_cell,
- this->dofs_per_cell);
- FETools::compute_embedding_matrices (*this, this->prolongation);
for (unsigned int i=0; i<GeometryInfo<dim>::children_per_cell; ++i)
this->prolongation[i].reinit (this->dofs_per_cell,
this->dofs_per_cell);
FETools::compute_embedding_matrices (*this, this->prolongation);
  * @endcode
  *
  * <h5>Computing the #restriction matrices for error estimators</h5>
@@ -336,16 +325,17 @@ namespace hp
  * <h5>Computing #interface_constraints</h5>
  *
  * Constraint matrices can be computed semi-automatically using
- * FETools::compute_face_embedding_matrices(). This function computes
- * the representation of the coarse mesh functions by fine mesh
- * functions for each child of a face separately. These matrices must
- * be convoluted into a single rectangular constraint matrix,
- * eliminating degrees of freedom on common vertices and edges as well
- * as on the coarse grid vertices. See the discussion above for details.
+ * FETools::compute_face_embedding_matrices(). This function computes the
+ * representation of the coarse mesh functions by fine mesh functions for each
+ * child of a face separately. These matrices must be convoluted into a single
+ * rectangular constraint matrix, eliminating degrees of freedom on common
+ * vertices and edges as well as on the coarse grid vertices. See the
+ * discussion above for details.
  *
  * @ingroup febase fe
  *
- * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1998, 2000, 2001, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1998, 2000, 2001,
+ * 2005
  */
 template <int dim, int spacedim=dim>
 class FiniteElement : public Subscriptor,
@@ -485,13 +475,12 @@ public:
    * Return the gradient of the @p ith shape function at the point @p p. @p p
    * is a point on the reference element, and likewise the gradient is the
    * gradient on the unit cell with respect to unit cell coordinates. If the
-   * finite element is vector-valued, then return the value of the only
-   * non-zero component of the vector value of this shape function. If the
-   * shape function has more than one non-zero component (which we refer to
-   * with the term non-primitive), then derived classes implementing this
-   * function should throw an exception of type
-   * ExcShapeFunctionNotPrimitive. In that case, use the
-   * shape_grad_component() function.
+   * finite element is vector-valued, then return the value of the only non-
+   * zero component of the vector value of this shape function. If the shape
+   * function has more than one non-zero component (which we refer to with the
+   * term non-primitive), then derived classes implementing this function
+   * should throw an exception of type ExcShapeFunctionNotPrimitive. In that
+   * case, use the shape_grad_component() function.
    *
    * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
    * FiniteElement under consideration depends on the shape of the cell in
@@ -516,10 +505,10 @@ public:
    * cell with respect to unit cell coordinates. If the finite element is
    * vector-valued, then return the value of the only non-zero component of
    * the vector value of this shape function. If the shape function has more
-   * than one non-zero component (which we refer to with the term
-   * non-primitive), then derived classes implementing this function should
-   * throw an exception of type ExcShapeFunctionNotPrimitive. In that case,
-   * use the shape_grad_grad_component() function.
+   * than one non-zero component (which we refer to with the term non-
+   * primitive), then derived classes implementing this function should throw
+   * an exception of type ExcShapeFunctionNotPrimitive. In that case, use the
+   * shape_grad_grad_component() function.
    *
    * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
    * FiniteElement under consideration depends on the shape of the cell in
@@ -529,16 +518,10 @@ public:
                                          const Point<dim>   &p) const;
 
   /**
-   * Just like for shape_grad_grad(),
-   * but this function will be
-   * called when the shape function
-   * has more than one non-zero
-   * vector component. In that
-   * case, this function should
-   * return the gradient of the
-   * @p component-th vector
-   * component of the @p ith shape
-   * function at point @p p.
+   * Just like for shape_grad_grad(), but this function will be called when
+   * the shape function has more than one non-zero vector component. In that
+   * case, this function should return the gradient of the @p component-th
+   * vector component of the @p ith shape function at point @p p.
    */
   virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
                                                    const Point<dim>   &p,
@@ -824,37 +807,35 @@ public:
    */
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
@@ -961,10 +942,10 @@ public:
    *
    * To explain the concept, consider the case where we would like to know
    * whether a degree of freedom on a face, for example as part of an FESystem
-   * element, is primitive. Unfortunately, the
-   * is_primitive() function in the FiniteElement class takes a cell index, so
-   * we would need to find the cell index of the shape function that
-   * corresponds to the present face index. This function does that.
+   * element, is primitive. Unfortunately, the is_primitive() function in the
+   * FiniteElement class takes a cell index, so we would need to find the cell
+   * index of the shape function that corresponds to the present face index.
+   * This function does that.
    *
    * Code implementing this would then look like this:
    * @code
@@ -976,36 +957,34 @@ public:
    * actual faces can be in their standard ordering with respect to the cell
    * under consideration, or can be flipped, oriented, etc.
    *
-   * @param face_dof_index The index of the degree of freedom on a face.
-   *   This index must be between zero and dofs_per_face.
-   * @param face The number of the face this degree of freedom lives on.
-   *   This number must be between zero and GeometryInfo::faces_per_cell.
-   * @param face_orientation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_flip One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_rotation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @return The index of this degree of freedom within the set
-   *   of degrees of freedom on the entire cell. The returned value
-   *   will be between zero and dofs_per_cell.
-   *
-   * @note This function exists in this class because that is where it
-   * was first implemented. However, it can't really work in the most
-   * general case without knowing what element we have. The reason is that
-   * when a face is flipped or rotated, we also need to know whether we
-   * need to swap the degrees of freedom on this face, or whether they
-   * are immune from this. For this, consider the situation of a $Q_3$
-   * element in 2d. If face_flip is true, then we need to consider
-   * the two degrees of freedom on the edge in reverse order. On the other
-   * hand, if the element were a $Q_1^2$, then because the two degrees of
-   * freedom on this edge belong to different vector components, they
-   * should not be considered in reverse order. What all of this shows is
-   * that the function can't work if there are more than one degree of
-   * freedom per line or quad, and that in these cases the function will
-   * throw an exception pointing out that this functionality will need
-   * to be provided by a derived class that knows what degrees of freedom
-   * actually represent.
+   * @param face_dof_index The index of the degree of freedom on a face. This
+   * index must be between zero and dofs_per_face.
+   * @param face The number of the face this degree of freedom lives on. This
+   * number must be between zero and GeometryInfo::faces_per_cell.
+   * @param face_orientation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation .
+   * @param face_flip One part of the description of the orientation of the
+   * face. See @ref GlossFaceOrientation .
+   * @param face_rotation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation . @return The index of this
+   * degree of freedom within the set of degrees of freedom on the entire
+   * cell. The returned value will be between zero and dofs_per_cell.
+   *
+   * @note This function exists in this class because that is where it was
+   * first implemented. However, it can't really work in the most general case
+   * without knowing what element we have. The reason is that when a face is
+   * flipped or rotated, we also need to know whether we need to swap the
+   * degrees of freedom on this face, or whether they are immune from this.
+   * For this, consider the situation of a $Q_3$ element in 2d. If face_flip
+   * is true, then we need to consider the two degrees of freedom on the edge
+   * in reverse order. On the other hand, if the element were a $Q_1^2$, then
+   * because the two degrees of freedom on this edge belong to different
+   * vector components, they should not be considered in reverse order. What
+   * all of this shows is that the function can't work if there are more than
+   * one degree of freedom per line or quad, and that in these cases the
+   * function will throw an exception pointing out that this functionality
+   * will need to be provided by a derived class that knows what degrees of
+   * freedom actually represent.
    */
   virtual
   unsigned int face_to_cell_index (const unsigned int face_dof_index,
@@ -1044,8 +1023,8 @@ public:
   get_nonzero_components (const unsigned int i) const;
 
   /**
-   * Return in how many vector components the @p ith shape function is
-   * non-zero. This value equals the number of entries equal to @p true in the
+   * Return in how many vector components the @p ith shape function is non-
+   * zero. This value equals the number of entries equal to @p true in the
    * result of the get_nonzero_components() function.
    *
    * For most finite element spaces, the result will be equal to one. It is
@@ -1058,10 +1037,10 @@ public:
 
   /**
    * Return whether the @p ith shape function is primitive in the sense that
-   * the shape function is non-zero in only one vector
-   * component. Non-primitive shape functions would then, for example, be
-   * those of divergence free ansatz spaces, in which the individual vector
-   * components are coupled.
+   * the shape function is non-zero in only one vector component. Non-
+   * primitive shape functions would then, for example, be those of divergence
+   * free ansatz spaces, in which the individual vector components are
+   * coupled.
    *
    * The result of the function is @p true if and only if the result of
    * <tt>n_nonzero_components(i)</tt> is equal to one.
@@ -1112,10 +1091,10 @@ public:
    * within this base element.
    *
    * If the element is not composed of others, then base and instance are
-   * always zero, and the index is equal to the number of the shape
-   * function. If the element is composed of single instances of other
-   * elements (i.e. all with multiplicity one) all of which are scalar, then
-   * base values and dof indices within this element are equal to the
+   * always zero, and the index is equal to the number of the shape function.
+   * If the element is composed of single instances of other elements (i.e.
+   * all with multiplicity one) all of which are scalar, then base values and
+   * dof indices within this element are equal to the
    * #system_to_component_table. It differs only in case the element is
    * composed of other elements and at least one of them is vector-valued
    * itself.
@@ -1193,9 +1172,8 @@ public:
    * glossary" for more information.
    *
    * @param scalar An object that represents a single scalar vector component
-   * of this finite element.
-   * @return A component mask that is false in all components except for the
-   * one that corresponds to the argument.
+   * of this finite element. @return A component mask that is false in all
+   * components except for the one that corresponds to the argument.
    */
   ComponentMask
   component_mask (const FEValuesExtractors::Scalar &scalar) const;
@@ -1207,9 +1185,8 @@ public:
    * glossary" for more information.
    *
    * @param vector An object that represents dim vector components of this
-   * finite element.
-   * @return A component mask that is false in all components except for the
-   * ones that corresponds to the argument.
+   * finite element. @return A component mask that is false in all components
+   * except for the ones that corresponds to the argument.
    */
   ComponentMask
   component_mask (const FEValuesExtractors::Vector &vector) const;
@@ -1236,9 +1213,8 @@ public:
    * from BlockMask to ComponentMask.
    *
    * @param block_mask The mask that selects individual blocks of the finite
-   * element
-   * @return A mask that selects those components corresponding to the selected
-   * blocks of the input argument.
+   * element @return A mask that selects those components corresponding to the
+   * selected blocks of the input argument.
    */
   ComponentMask
   component_mask (const BlockMask &block_mask) const;
@@ -1257,9 +1233,8 @@ public:
    * exception.
    *
    * @param scalar An object that represents a single scalar vector component
-   * of this finite element.
-   * @return A component mask that is false in all components except for the
-   * one that corresponds to the argument.
+   * of this finite element. @return A component mask that is false in all
+   * components except for the one that corresponds to the argument.
    */
   BlockMask
   block_mask (const FEValuesExtractors::Scalar &scalar) const;
@@ -1275,9 +1250,8 @@ public:
    * full blocks and does not split blocks of this element.
    *
    * @param vector An object that represents dim vector components of this
-   * finite element.
-   * @return A component mask that is false in all components except for the
-   * ones that corresponds to the argument.
+   * finite element. @return A component mask that is false in all components
+   * except for the ones that corresponds to the argument.
    */
   BlockMask
   block_mask (const FEValuesExtractors::Vector &vector) const;
@@ -1294,9 +1268,8 @@ public:
    *
    * @param sym_tensor An object that represents dim*(dim+1)/2 components of
    * this finite element that are jointly to be interpreted as forming a
-   * symmetric tensor.
-   * @return A component mask that is false in all components except for the
-   * ones that corresponds to the argument.
+   * symmetric tensor. @return A component mask that is false in all
+   * components except for the ones that corresponds to the argument.
    */
   BlockMask
   block_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
@@ -1317,9 +1290,8 @@ public:
    * exception.
    *
    * @param component_mask The mask that selects individual components of the
-   * finite element
-   * @return A mask that selects those blocks corresponding to the selected
-   * blocks of the input argument.
+   * finite element @return A mask that selects those blocks corresponding to
+   * the selected blocks of the input argument.
    */
   BlockMask
   block_mask (const ComponentMask &component_mask) const;
@@ -1364,19 +1336,20 @@ public:
    *
    * See the class documentation for details on support points.
    *
-   * @note Finite elements' implementation of this function
-   * returns these points in the same order as shape functions. The
-   * order of shape functions is typically documented in the class documentation
-   * of the various finite element classes. In particular, shape functions (and
-   * consequently the mapped quadrature points discussed in the class documentation
-   * of this class) will then traverse first those shape functions
-   * located on vertices, then on lines, then on quads, etc.
+   * @note Finite elements' implementation of this function returns these
+   * points in the same order as shape functions. The order of shape functions
+   * is typically documented in the class documentation of the various finite
+   * element classes. In particular, shape functions (and consequently the
+   * mapped quadrature points discussed in the class documentation of this
+   * class) will then traverse first those shape functions located on
+   * vertices, then on lines, then on quads, etc.
    *
    * @note If this element implements support points, then it will return one
-   * such point per shape function. Since multiple shape functions may be defined
-   * at the same location, the support points returned here may be duplicated. An
-   * example would be an element of the kind <code>FESystem(FE_Q(1),3)</code>
-   * for which each support point would appear three times in the returned array.
+   * such point per shape function. Since multiple shape functions may be
+   * defined at the same location, the support points returned here may be
+   * duplicated. An example would be an element of the kind
+   * <code>FESystem(FE_Q(1),3)</code> for which each support point would
+   * appear three times in the returned array.
    */
   const std::vector<Point<dim> > &
   get_unit_support_points () const;
@@ -1432,9 +1405,8 @@ public:
    * degrees of freedom from both sides of a face (or from all adjacent
    * elements to a vertex) would be identified with each other, which is not
    * what we would like to have). Logically, these degrees of freedom are
-   * therefore defined to belong to the cell, rather than the face or
-   * vertex. In that case, the returned element would therefore have length
-   * zero.
+   * therefore defined to belong to the cell, rather than the face or vertex.
+   * In that case, the returned element would therefore have length zero.
    *
    * If the finite element defines support points, then their number equals
    * the number of degrees of freedom on the face (#dofs_per_face). The order
@@ -1500,51 +1472,47 @@ public:
   has_generalized_face_support_points () const;
 
   /**
-   * For a given degree of freedom, return whether it is logically
-   * associated with a vertex, line, quad or hex.
-   *
-   * For instance, for continuous finite elements this coincides with
-   * the lowest dimensional object the support point of the degree of
-   * freedom lies on. To give an example, for $Q_1$ elements in 3d,
-   * every degree of freedom is defined by a shape function that we
-   * get by interpolating using support points that lie on the
-   * vertices of the cell. The support of these points of course
-   * extends to all edges connected to this vertex, as well
-   * as the adjacent faces and the cell interior, but we say that
-   * logically the degree of freedom is associated with the vertex as
-   * this is the lowest-dimensional object it is associated with.
-   * Likewise, for $Q_2$ elements in 3d, the degrees of freedom
-   * with support points at edge midpoints would yield a value of
-   * GeometryPrimitive::line from this function, whereas those on
-   * the centers of faces in 3d would return GeometryPrimitive::quad.
-   *
-   * To make this more formal, the kind of object returned by
-   * this function represents the object so that the support of the
-   * shape function corresponding to the degree of freedom, (i.e., that
-   * part of the domain where the function "lives") is the union
-   * of all of the cells sharing this object. To return to the example
-   * above, for $Q_2$ in 3d, the shape function with support point at
-   * an edge midpoint has support on all cells that share the edge and
-   * not only the cells that share the adjacent faces, and consequently
-   * the function will return GeometryPrimitive::line.
-   *
-   * On the other hand, for discontinuous elements of type $DGQ_2$,
-   * a degree of freedom associated with an interpolation polynomial
-   * that has its support point physically located at a line bounding
-   * a cell, but is nonzero only on one cell. Consequently, it is
-   * logically associated with the interior of that cell (i.e., with a
-   * GeometryPrimitive::quad in 2d and a GeometryPrimitive::hex in 3d).
-   *
-   * @param[in] cell_dof_index The index of a shape function or
-   *   degree of freedom. This index must be in the range
-   *   <code>[0,dofs_per_cell)</code>.
-   *
-   * @note The integer value of the object returned by this function
-   *   equals the dimensionality of the object it describes, and can
-   *   consequently be used in generic programming paradigms. For
-   *   example, if a degree of freedom is associated with a vertex,
-   *   then this function returns GeometryPrimitive::vertex, which has
-   *   a numeric value of zero (the dimensionality of a vertex).
+   * For a given degree of freedom, return whether it is logically associated
+   * with a vertex, line, quad or hex.
+   *
+   * For instance, for continuous finite elements this coincides with the
+   * lowest dimensional object the support point of the degree of freedom lies
+   * on. To give an example, for $Q_1$ elements in 3d, every degree of freedom
+   * is defined by a shape function that we get by interpolating using support
+   * points that lie on the vertices of the cell. The support of these points
+   * of course extends to all edges connected to this vertex, as well as the
+   * adjacent faces and the cell interior, but we say that logically the
+   * degree of freedom is associated with the vertex as this is the lowest-
+   * dimensional object it is associated with. Likewise, for $Q_2$ elements in
+   * 3d, the degrees of freedom with support points at edge midpoints would
+   * yield a value of GeometryPrimitive::line from this function, whereas
+   * those on the centers of faces in 3d would return GeometryPrimitive::quad.
+   *
+   * To make this more formal, the kind of object returned by this function
+   * represents the object so that the support of the shape function
+   * corresponding to the degree of freedom, (i.e., that part of the domain
+   * where the function "lives") is the union of all of the cells sharing this
+   * object. To return to the example above, for $Q_2$ in 3d, the shape
+   * function with support point at an edge midpoint has support on all cells
+   * that share the edge and not only the cells that share the adjacent faces,
+   * and consequently the function will return GeometryPrimitive::line.
+   *
+   * On the other hand, for discontinuous elements of type $DGQ_2$, a degree
+   * of freedom associated with an interpolation polynomial that has its
+   * support point physically located at a line bounding a cell, but is
+   * nonzero only on one cell. Consequently, it is logically associated with
+   * the interior of that cell (i.e., with a GeometryPrimitive::quad in 2d and
+   * a GeometryPrimitive::hex in 3d).
+   *
+   * @param[in] cell_dof_index The index of a shape function or degree of
+   * freedom. This index must be in the range <code>[0,dofs_per_cell)</code>.
+   *
+   * @note The integer value of the object returned by this function equals
+   * the dimensionality of the object it describes, and can consequently be
+   * used in generic programming paradigms. For example, if a degree of
+   * freedom is associated with a vertex, then this function returns
+   * GeometryPrimitive::vertex, which has a numeric value of zero (the
+   * dimensionality of a vertex).
    */
   GeometryPrimitive
   get_associated_geometry_primitive (const unsigned int cell_dof_index) const;
@@ -1788,12 +1756,12 @@ protected:
    * For faces with non-standard face_orientation in 3D, the dofs on faces
    * (quads) have to be permuted in order to be combined with the correct
    * shape functions. Given a local dof @p index on a quad, return the shift
-   * in the local index, if the face has non-standard face_orientation,
-   * i.e. <code>old_index + shift = new_index</code>. In 2D and 1D there is no
-   * need for permutation so the vector is empty. In 3D it has the size of
-   * <code> #dofs_per_quad * 8 </code>, where 8 is the number of orientations,
-   * a face can be in (all combinations of the three bool flags
-   * face_orientation, face_flip and face_rotation).
+   * in the local index, if the face has non-standard face_orientation, i.e.
+   * <code>old_index + shift = new_index</code>. In 2D and 1D there is no need
+   * for permutation so the vector is empty. In 3D it has the size of <code>
+   * #dofs_per_quad * 8 </code>, where 8 is the number of orientations, a face
+   * can be in (all combinations of the three bool flags face_orientation,
+   * face_flip and face_rotation).
    *
    * The standard implementation fills this with zeros, i.e. no permuatation
    * at all. Derived finite element classes have to fill this Table with the
@@ -1805,9 +1773,9 @@ protected:
    * For lines with non-standard line_orientation in 3D, the dofs on lines
    * have to be permuted in order to be combined with the correct shape
    * functions. Given a local dof @p index on a line, return the shift in the
-   * local index, if the line has non-standard line_orientation,
-   * i.e. <code>old_index + shift = new_index</code>. In 2D and 1D there is no
-   * need for permutation so the vector is empty. In 3D it has the size of
+   * local index, if the line has non-standard line_orientation, i.e.
+   * <code>old_index + shift = new_index</code>. In 2D and 1D there is no need
+   * for permutation so the vector is empty. In 3D it has the size of
    * #dofs_per_line.
    *
    * The standard implementation fills this with zeros, i.e. no permutation at
@@ -1844,8 +1812,8 @@ protected:
    * case the element is composed of other elements and at least one of them
    * is vector-valued itself.
    *
-   * This array has valid values also in the case of vector-valued
-   * (i.e. non-primitive) shape functions, in contrast to the
+   * This array has valid values also in the case of vector-valued (i.e. non-
+   * primitive) shape functions, in contrast to the
    * #system_to_component_table.
    */
   std::vector<std::pair<std::pair<unsigned int,unsigned int>,unsigned int> >
@@ -1867,21 +1835,16 @@ protected:
    * The base element establishing a component.
    *
    * For each component number <tt>c</tt>, the entries have the following
-   * meaning:
-   * <dl>
-   * <dt><tt>table[c].first.first</tt></dt>
-   * <dd>Number of the base element for <tt>c</tt>.</dd>
-   * <dt><tt>table[c].first.second</tt></dt>
+   * meaning: <dl> <dt><tt>table[c].first.first</tt></dt> <dd>Number of the
+   * base element for <tt>c</tt>.</dd> <dt><tt>table[c].first.second</tt></dt>
    * <dd>Component in the base element for <tt>c</tt>.</dd>
-   * <dt><tt>table[c].second</tt></dt>
-   * <dd>Multiple of the base element for <tt>c</tt>.</dd>
-   * </dl>
+   * <dt><tt>table[c].second</tt></dt> <dd>Multiple of the base element for
+   * <tt>c</tt>.</dd> </dl>
    *
    * This variable is set to the correct size by the constructor of this
    * class, but needs to be initialized by derived classes, unless its size is
-   * one and the only entry is a zero, which is the case for scalar
-   * elements. In that case, the initialization by the base class is
-   * sufficient.
+   * one and the only entry is a zero, which is the case for scalar elements.
+   * In that case, the initialization by the base class is sufficient.
    */
   std::vector<std::pair<std::pair<unsigned int, unsigned int>, unsigned int> >
   component_to_base_table;
@@ -1911,15 +1874,14 @@ protected:
    * vector component of the element. This is based on the fact that all the
    * shape functions that belong to the same vector component must necessarily
    * behave in the same way, to make things reasonable. However, the problem
-   * is that it is sometimes impossible to query this flag in the
-   * vector-valued case: this used to be done with the
-   * #system_to_component_index function that returns which vector component a
-   * shape function is associated with. The point is that since we now support
-   * shape functions that are associated with more than one vector component
-   * (for example the shape functions of Raviart-Thomas, or Nedelec elements),
-   * that function can no more be used, so it can be difficult to find out
-   * which for vector component we would like to query the
-   * restriction-is-additive flags.
+   * is that it is sometimes impossible to query this flag in the vector-
+   * valued case: this used to be done with the #system_to_component_index
+   * function that returns which vector component a shape function is
+   * associated with. The point is that since we now support shape functions
+   * that are associated with more than one vector component (for example the
+   * shape functions of Raviart-Thomas, or Nedelec elements), that function
+   * can no more be used, so it can be difficult to find out which for vector
+   * component we would like to query the restriction-is-additive flags.
    */
   const std::vector<bool> restriction_is_additive_flags;
 
@@ -1951,8 +1913,8 @@ protected:
   /**
    * Return the size of interface constraint matrices. Since this is needed in
    * every derived finite element class when initializing their size, it is
-   * placed into this function, to avoid having to recompute the
-   * dimension-dependent size of these matrices each time.
+   * placed into this function, to avoid having to recompute the dimension-
+   * dependent size of these matrices each time.
    *
    * Note that some elements do not implement the interface constraints for
    * certain polynomial degrees. In this case, this function still returns the
@@ -1974,8 +1936,8 @@ protected:
 
   /**
    * Given the pattern of nonzero components for each shape function, compute
-   * for each entry how many components are non-zero for each shape
-   * function. This function is used in the constructor of this class.
+   * for each entry how many components are non-zero for each shape function.
+   * This function is used in the constructor of this class.
    */
   static
   std::vector<unsigned int>
index 0c61e5dcc12b5af9666dc956650aaf14fe7730f2..beb4503bf372b8ad15be05ea6e4cb474cd2dca82 100644 (file)
@@ -37,86 +37,78 @@ template <int dim, int spacedim> class MappingQ;
 
 /**
  * Implementation of Arnold-Boffi-Falk (ABF) elements, conforming with the
- * space H<sup>div</sup>. These elements generate vector fields with
- * normal components continuous between mesh cells.
+ * space H<sup>div</sup>. These elements generate vector fields with normal
+ * components continuous between mesh cells.
  *
  * These elements are based on an article from Arnold, Boffi and Falk:
- * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal.
- * Vol.42, No.6, pp.2429-2451
+ * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal. Vol.42, No.6,
+ * pp.2429-2451
  *
- * In this article, the authors demonstrate that the usual RT elements
- * and also BDM and other proposed finite dimensional subspaces of
- * H(div) do not work properly on arbitrary FE grids. I.e. the
- * convergence rates deteriorate on these meshes. As a solution the
- * authors propose the ABF elements, which are implemented in this
- * module.
+ * In this article, the authors demonstrate that the usual RT elements and
+ * also BDM and other proposed finite dimensional subspaces of H(div) do not
+ * work properly on arbitrary FE grids. I.e. the convergence rates deteriorate
+ * on these meshes. As a solution the authors propose the ABF elements, which
+ * are implemented in this module.
  *
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
  *
  * @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
  *
  * <h3>Interpolation</h3>
  *
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the RT element are constructed such that interpolation and
- * computing the divergence are commuting operations. We require this
- * from interpolating arbitrary functions as well as the #restriction
- * matrices.  It can be achieved by two interpolation schemes, the
- * simplified one in FE_RaviartThomasNodal and the original one here:
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * RT element are constructed such that interpolation and computing the
+ * divergence are commuting operations. We require this from interpolating
+ * arbitrary functions as well as the #restriction matrices.  It can be
+ * achieved by two interpolation schemes, the simplified one in
+ * FE_RaviartThomasNodal and the original one here:
  *
  * <h4>Node values on edges/faces</h4>
  *
- * On edges or faces, the @ref GlossNodes "node values" are the moments of
- * the normal component of the interpolated function with respect to
- * the traces of the RT polynomials. Since the normal trace of the RT
- * space of degree <i>k</i> on an edge/face is the space
- * <i>Q<sub>k</sub></i>, the moments are taken with respect to this
- * space.
+ * On edges or faces, the @ref GlossNodes "node values" are the moments of the
+ * normal component of the interpolated function with respect to the traces of
+ * the RT polynomials. Since the normal trace of the RT space of degree
+ * <i>k</i> on an edge/face is the space <i>Q<sub>k</sub></i>, the moments are
+ * taken with respect to this space.
  *
  * <h4>Interior node values</h4>
  *
- * Higher order RT spaces have interior nodes. These are moments taken
- * with respect to the gradient of functions in <i>Q<sub>k</sub></i>
- * on the cell (this space is the matching space for RT<sub>k</sub> in
- * a mixed formulation).
+ * Higher order RT spaces have interior nodes. These are moments taken with
+ * respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell
+ * (this space is the matching space for RT<sub>k</sub> in a mixed
+ * formulation).
  *
  * <h4>Generalized support points</h4>
  *
  * The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are those of
- * QGauss<sub>k+1</sub> on each face as well as QGauss<sub>k</sub> in
- * the interior of the cell (or none for RT<sub>0</sub>).
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are those of QGauss<sub>k+1</sub> on each face as well as
+ * QGauss<sub>k</sub> in the interior of the cell (or none for
+ * RT<sub>0</sub>). See the @ref GlossGeneralizedSupport "glossary entry on
+ * generalized support points" for more information.
  *
  *
- * @author Oliver Kayser-Herold, 2006, based on previous work
- * by Guido Kanschat and Wolfgang Bangerth
+ * @author Oliver Kayser-Herold, 2006, based on previous work by Guido
+ * Kanschat and Wolfgang Bangerth
  */
 template <int dim>
 class FE_ABF : public FE_PolyTensor<PolynomialsABF<dim>, dim>
 {
 public:
   /**
-   * Constructor for the ABF
-   * element of degree @p p.
+   * Constructor for the ABF element of degree @p p.
    */
   FE_ABF (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_ABF<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_ABF<dim>(degree)</tt>, with @p dim and @p degree replaced
+   * by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -143,213 +135,130 @@ public:
 
 private:
   /**
-   * The order of the
-   * ABF element. The
-   * lowest order elements are
-   * usually referred to as RT0,
-   * even though their shape
-   * functions are piecewise
+   * The order of the ABF element. The lowest order elements are usually
+   * referred to as RT0, even though their shape functions are piecewise
    * quadratics.
    */
   const unsigned int rt_order;
 
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree);
 
   /**
-   * Initialize the @p
-   * generalized_support_points
-   * field of the FiniteElement
-   * class and fill the tables with
-   * interpolation weights
-   * (#boundary_weights and
-   * #interior_weights). Called
-   * from the constructor.
-  *
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * Initialize the @p generalized_support_points field of the FiniteElement
+   * class and fill the tables with interpolation weights (#boundary_weights
+   * and #interior_weights). Called from the constructor.
+   *
+   * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+   * support points" for more information.
    */
   void initialize_support_points (const unsigned int rt_degree);
 
   /**
-   * Initialize the interpolation
-   * from functions on refined mesh
-   * cells onto the father
-   * cell. According to the
-   * philosophy of the
-   * Raviart-Thomas element, this
-   * restriction operator preserves
-   * the divergence of a function
+   * Initialize the interpolation from functions on refined mesh cells onto
+   * the father cell. According to the philosophy of the Raviart-Thomas
+   * element, this restriction operator preserves the divergence of a function
    * weakly.
    */
   void initialize_restriction ();
 
   /**
-   * Given a set of flags indicating
-   * what quantities are requested
-   * from a @p FEValues object,
-   * return which of these can be
-   * precomputed once and for
-   * all. Often, the values of
-   * shape function at quadrature
-   * points can be precomputed, for
-   * example, in which case the
-   * return value of this function
-   * would be the logical and of
-   * the input @p flags and
-   * @p update_values.
+   * Given a set of flags indicating what quantities are requested from a @p
+   * FEValues object, return which of these can be precomputed once and for
+   * all. Often, the values of shape function at quadrature points can be
+   * precomputed, for example, in which case the return value of this function
+   * would be the logical and of the input @p flags and @p update_values.
    *
-   * For the present kind of finite
-   * element, this is exactly the
-   * case.
+   * For the present kind of finite element, this is exactly the case.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
   /**
-   * This is the opposite to the
-   * above function: given a set of
-   * flags indicating what we want
-   * to know, return which of these
-   * need to be computed each time
-   * we visit a new cell.
+   * This is the opposite to the above function: given a set of flags
+   * indicating what we want to know, return which of these need to be
+   * computed each time we visit a new cell.
    *
-   * If for the computation of one
-   * quantity something else is
-   * also required (for example, we
-   * often need the covariant
-   * transformation when gradients
-   * need to be computed), include
-   * this in the result as well.
+   * If for the computation of one quantity something else is also required
+   * (for example, we often need the covariant transformation when gradients
+   * need to be computed), include this in the result as well.
    */
   virtual UpdateFlags update_each (const UpdateFlags flags) const;
 
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points. There is one row
-     * for each shape function,
-     * containing values for each
-     * quadrature point. Since
-     * the shape functions are
-     * vector-valued (with as
-     * many components as there
-     * are space dimensions), the
-     * value is a tensor.
+     * Array with shape function values in quadrature points. There is one row
+     * for each shape function, containing values for each quadrature point.
+     * Since the shape functions are vector-valued (with as many components as
+     * there are space dimensions), the value is a tensor.
      *
-     * In this array, we store
-     * the values of the shape
-     * function in the quadrature
-     * points on the unit
-     * cell. The transformation
-     * to the real space cell is
-     * then simply done by
-     * multiplication with the
-     * Jacobian of the mapping.
+     * In this array, we store the values of the shape function in the
+     * quadrature points on the unit cell. The transformation to the real
+     * space cell is then simply done by multiplication with the Jacobian of
+     * the mapping.
      */
     std::vector<std::vector<Tensor<1,dim> > > shape_values;
 
     /**
-     * Array with shape function
-     * gradients in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
+     * Array with shape function gradients in quadrature points. There is one
+     * row for each shape function, containing values for each quadrature
      * point.
      *
-     * We store the gradients in
-     * the quadrature points on
-     * the unit cell. We then
-     * only have to apply the
-     * transformation (which is a
-     * matrix-vector
-     * multiplication) when
-     * visiting an actual cell.
+     * We store the gradients in the quadrature points on the unit cell. We
+     * then only have to apply the transformation (which is a matrix-vector
+     * multiplication) when visiting an actual cell.
      */
     std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
   };
 
   /**
-   * These are the factors
-   * multiplied to a function in
-   * the
-   * #generalized_face_support_points
-   * when computing the
-   * integration. They are
-   * organized such that there is
-   * one row for each generalized
-   * face support point and one
-   * column for each degree of
-   * freedom on the face.
+   * These are the factors multiplied to a function in the
+   * #generalized_face_support_points when computing the integration. They are
+   * organized such that there is one row for each generalized face support
+   * point and one column for each degree of freedom on the face.
    */
   Table<2, double> boundary_weights;
   /**
-   * Precomputed factors for
-   * interpolation of interior
-   * degrees of freedom. The
-   * rationale for this Table is
-   * the same as for
-   * #boundary_weights. Only, this
-   * table has a third coordinate
-   * for the space direction of the
-   * component evaluated.
+   * Precomputed factors for interpolation of interior degrees of freedom. The
+   * rationale for this Table is the same as for #boundary_weights. Only, this
+   * table has a third coordinate for the space direction of the component
+   * evaluated.
    */
   Table<3, double> interior_weights;
 
 
 
   /**
-   * These are the factors
-   * multiplied to a function in
-   * the
-   * #generalized_face_support_points
-   * when computing the
-   * integration. They are
-   * organized such that there is
-   * one row for each generalized
-   * face support point and one
-   * column for each degree of
-   * freedom on the face.
+   * These are the factors multiplied to a function in the
+   * #generalized_face_support_points when computing the integration. They are
+   * organized such that there is one row for each generalized face support
+   * point and one column for each degree of freedom on the face.
    */
   Table<2, double> boundary_weights_abf;
   /**
-   * Precomputed factors for
-   * interpolation of interior
-   * degrees of freedom. The
-   * rationale for this Table is
-   * the same as for
-   * #boundary_weights. Only, this
-   * table has a third coordinate
-   * for the space direction of the
-   * component evaluated.
+   * Precomputed factors for interpolation of interior degrees of freedom. The
+   * rationale for this Table is the same as for #boundary_weights. Only, this
+   * table has a third coordinate for the space direction of the component
+   * evaluated.
    */
   Table<3, double> interior_weights_abf;
 
 
   /**
-   * Allow access from other
-   * dimensions.
+   * Allow access from other dimensions.
    */
   template <int dim1> friend class FE_ABF;
 };
index 79c87d401ed7de6599cc9547953c2d6c7ea51453..008f8b377374dd547475859473488ae0d86fa136 100644 (file)
@@ -130,7 +130,8 @@ namespace FiniteElementDomination
  * to the implementation in a concrete finite element class.
  *
  * @ingroup febase
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2001, 2003, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2001, 2003,
+ * 2005
  */
 template <int dim>
 class FiniteElementData
@@ -156,10 +157,10 @@ public:
    * <li> <i>H<sup>2</sup></i> implies that the function is continuously
    * differentiable over cell boundaries.
    *
-   * <li> <i>L<sup>2</sup></i> indicates that the element is
-   * discontinuous. Since discontinuous elements have no topological couplings
-   * between grid cells and code may actually depend on this property,
-   * <i>L<sup>2</sup></i> conformity is handled in a special way in the sense
+   * <li> <i>L<sup>2</sup></i> indicates that the element is discontinuous.
+   * Since discontinuous elements have no topological couplings between grid
+   * cells and code may actually depend on this property, <i>L<sup>2</sup></i>
+   * conformity is handled in a special way in the sense
    * that it is <b>not</b> implied by any higher conformity.  </ol>
    *
    * In order to test if a finite element conforms to a certain space, use
index 0cac3826efe45adb7421bff56dc94c13a4fe760b..9516c693d8997fa7b3674fd421812d9bd349b007 100644 (file)
@@ -38,18 +38,18 @@ DEAL_II_NAMESPACE_OPEN
  *
  * @todo Restriction matrices are missing.
  *
- * The matching pressure space for FE_BDM of order <i>k</i> is the
- * element FE_DGP of order <i>k</i>.
+ * The matching pressure space for FE_BDM of order <i>k</i> is the element
+ * FE_DGP of order <i>k</i>.
  *
- * The BDM element of order @p p has <i>p+1</i> degrees of freedom on
- * each face. These are implemented as the function values in the
- * <i>p+1</i> Gauss points on each face.
+ * The BDM element of order @p p has <i>p+1</i> degrees of freedom on each
+ * face. These are implemented as the function values in the <i>p+1</i> Gauss
+ * points on each face.
  *
  * Additionally, for order greater or equal 2, we have additional
  * <i>p(p-1)</i>, the number of vector valued polynomials in
- * <i>P<sub>p</sub></i>, interior degrees of freedom. These are the
- * vector function values in the first <i>p(p-1)/2</i> of the
- * <i>p<sup>2</sup></i> Gauss points in the cell.
+ * <i>P<sub>p</sub></i>, interior degrees of freedom. These are the vector
+ * function values in the first <i>p(p-1)/2</i> of the <i>p<sup>2</sup></i>
+ * Gauss points in the cell.
  */
 template <int dim>
 class FE_BDM
@@ -58,19 +58,14 @@ class FE_BDM
 {
 public:
   /**
-   * Constructor for the BDM
-   * element of degree @p p.
+   * Constructor for the BDM element of degree @p p.
    */
   FE_BDM (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_BDM<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_BDM<dim>(degree)</tt>, with @p dim and @p degree replaced
+   * by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -86,45 +81,31 @@ public:
     const VectorSlice<const std::vector<std::vector<double> > > &values) const;
 private:
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree);
 
   /**
-   * Compute the vector used for
-   * the
-   * @p restriction_is_additive
-   * field passed to the base
-   * class's constructor.
+   * Compute the vector used for the @p restriction_is_additive field passed
+   * to the base class's constructor.
    */
   static std::vector<bool>
   get_ria_vector (const unsigned int degree);
   /**
-   * Initialize the
-   * FiniteElement<dim>::generalized_support_points
-   * and FiniteElement<dim>::generalized_face_support_points
-   * fields. Called from the
-   * constructor.
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * Initialize the FiniteElement<dim>::generalized_support_points and
+   * FiniteElement<dim>::generalized_face_support_points fields. Called from
+   * the constructor. See the @ref GlossGeneralizedSupport "glossary entry on
+   * generalized support points" for more information.
    */
   void initialize_support_points (const unsigned int rt_degree);
   /**
-   * The values in the interior
-   * support points of the
-   * polynomials needed as test
-   * functions. The outer vector is
-   * indexed by quadrature points,
-   * the inner by the test
-   * function.
+   * The values in the interior support points of the polynomials needed as
+   * test functions. The outer vector is indexed by quadrature points, the
+   * inner by the test function.
    */
   std::vector<std::vector<double> > test_values;
 };
index 3b7b4932771817dbb722cbc698831c1545b96d7d..73d338dab9033c3f640d35e2cb444eeef0ef2999 100644 (file)
@@ -37,16 +37,16 @@ template <int dim, int spacedim> class MappingQ;
 /**
  * DG elements based on vector valued polynomials.
  *
- * These elements use vector valued polynomial spaces as they have
- * been introduced for H<sup>div</sup> and H<sup>curl</sup> conforming
- * finite elements, but do not use the usual continuity of these
- * elements. Thus, they are suitable for DG and hybrid formulations
- * involving these function spaces.
+ * These elements use vector valued polynomial spaces as they have been
+ * introduced for H<sup>div</sup> and H<sup>curl</sup> conforming finite
+ * elements, but do not use the usual continuity of these elements. Thus, they
+ * are suitable for DG and hybrid formulations involving these function
+ * spaces.
  *
- * The template argument <tt>POLY</tt> refers to a vector valued
- * polynomial space like PolynomialsRaviartThomas or
- * PolynomialsNedelec. Note that the dimension of the polynomial space
- * and the argument <tt>dim</tt> must coincide.
+ * The template argument <tt>POLY</tt> refers to a vector valued polynomial
+ * space like PolynomialsRaviartThomas or PolynomialsNedelec. Note that the
+ * dimension of the polynomial space and the argument <tt>dim</tt> must
+ * coincide.
  *
  * @ingroup febase
  * @author Guido Kanschat
@@ -59,8 +59,7 @@ class FE_DGVector
 {
 public:
   /**
-   * Constructor for the vector
-   * element of degree @p p.
+   * Constructor for the vector element of degree @p p.
    */
   FE_DGVector (const unsigned int p, MappingType m);
 public:
@@ -68,13 +67,9 @@ public:
   FiniteElement<dim, spacedim> *clone() const;
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_RaviartThomas<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree
+   * replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -100,40 +95,28 @@ public:
 
 private:
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree);
 
   /**
-   * Initialize the @p
-   * generalized_support_points
-   * field of the FiniteElement
-   * class and fill the tables with
-   * @p interior_weights. Called
-   * from the constructor.
-  *
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * Initialize the @p generalized_support_points field of the FiniteElement
+   * class and fill the tables with @p interior_weights. Called from the
+   * constructor.
+   *
+   * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+   * support points" for more information.
    */
   void initialize_support_points (const unsigned int degree);
 
   /**
-   * Initialize the interpolation
-   * from functions on refined mesh
-   * cells onto the father
-   * cell. According to the
-   * philosophy of the
-   * Raviart-Thomas element, this
-   * restriction operator preserves
-   * the divergence of a function
+   * Initialize the interpolation from functions on refined mesh cells onto
+   * the father cell. According to the philosophy of the Raviart-Thomas
+   * element, this restriction operator preserves the divergence of a function
    * weakly.
    */
   void initialize_restriction ();
@@ -141,56 +124,33 @@ private:
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points. There is one row
-     * for each shape function,
-     * containing values for each
-     * quadrature point. Since
-     * the shape functions are
-     * vector-valued (with as
-     * many components as there
-     * are space dimensions), the
-     * value is a tensor.
+     * Array with shape function values in quadrature points. There is one row
+     * for each shape function, containing values for each quadrature point.
+     * Since the shape functions are vector-valued (with as many components as
+     * there are space dimensions), the value is a tensor.
      *
-     * In this array, we store
-     * the values of the shape
-     * function in the quadrature
-     * points on the unit
-     * cell. The transformation
-     * to the real space cell is
-     * then simply done by
-     * multiplication with the
-     * Jacobian of the mapping.
+     * In this array, we store the values of the shape function in the
+     * quadrature points on the unit cell. The transformation to the real
+     * space cell is then simply done by multiplication with the Jacobian of
+     * the mapping.
      */
     std::vector<std::vector<Tensor<1,dim> > > shape_values;
 
     /**
-     * Array with shape function
-     * gradients in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
+     * Array with shape function gradients in quadrature points. There is one
+     * row for each shape function, containing values for each quadrature
      * point.
      *
-     * We store the gradients in
-     * the quadrature points on
-     * the unit cell. We then
-     * only have to apply the
-     * transformation (which is a
-     * matrix-vector
-     * multiplication) when
-     * visiting an actual cell.
+     * We store the gradients in the quadrature points on the unit cell. We
+     * then only have to apply the transformation (which is a matrix-vector
+     * multiplication) when visiting an actual cell.
      */
     std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
   };
@@ -211,19 +171,15 @@ class FE_DGNedelec : public FE_DGVector<PolynomialsNedelec<dim>, dim, spacedim>
 {
 public:
   /**
-   * Constructor for the discontinuous N&eacute;d&eacute;lec
-   * element of degree @p p.
+   * Constructor for the discontinuous N&eacute;d&eacute;lec element of degree
+   * @p p.
    */
   FE_DGNedelec (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGNedelec<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGNedelec<dim>(degree)</tt>, with @p dim and @p degree
+   * replaced by appropriate values.
    */
   virtual std::string get_name () const;
 };
@@ -231,7 +187,8 @@ public:
 
 
 /**
- * A vector-valued DG element based on the polynomials space of FE_RaviartThomas.
+ * A vector-valued DG element based on the polynomials space of
+ * FE_RaviartThomas.
  *
  * @ingroup fe
  * @author Guido Kanschat
@@ -242,19 +199,14 @@ class FE_DGRaviartThomas : public FE_DGVector<PolynomialsRaviartThomas<dim>, dim
 {
 public:
   /**
-   * Constructor for the Raviart-Thomas
-   * element of degree @p p.
+   * Constructor for the Raviart-Thomas element of degree @p p.
    */
   FE_DGRaviartThomas (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGRaviartThomas<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGRaviartThomas<dim>(degree)</tt>, with @p dim and @p
+   * degree replaced by appropriate values.
    */
   virtual std::string get_name () const;
 };
@@ -273,19 +225,14 @@ class FE_DGBDM : public FE_DGVector<PolynomialsBDM<dim>, dim, spacedim>
 {
 public:
   /**
-   * Constructor for the discontinuous BDM
-   * element of degree @p p.
+   * Constructor for the discontinuous BDM element of degree @p p.
    */
   FE_DGBDM (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGBDM<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGBDM<dim>(degree)</tt>, with @p dim and @p degree
+   * replaced by appropriate values.
    */
   virtual std::string get_name () const;
 };
index 479315ecd4b58d118c763a7d815364721cc33c4a..c66eda590ba92485531d801ea74de2fa71adaa89 100644 (file)
@@ -30,80 +30,74 @@ template <int dim, int spacedim> class MappingQ;
 /**
  * Discontinuous finite elements based on Legendre polynomials.
  *
- * This finite element implements complete polynomial spaces, that is,
- * dim-dimensional polynomials of degree p. For example, in 2d the
- * element FE_DGP(1) would represent the span of the functions
- * $\{1,\hat x,\hat y\}$, which is in contrast to the element FE_DGQ(1)
- * that is formed by the span of $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the
- * DGP space has only three unknowns for each quadrilateral, it is
- * immediately clear that this element can not be continuous.
+ * This finite element implements complete polynomial spaces, that is, dim-
+ * dimensional polynomials of degree p. For example, in 2d the element
+ * FE_DGP(1) would represent the span of the functions $\{1,\hat x,\hat y\}$,
+ * which is in contrast to the element FE_DGQ(1) that is formed by the span of
+ * $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the DGP space has only three
+ * unknowns for each quadrilateral, it is immediately clear that this element
+ * can not be continuous.
  *
- * The basis functions used in this element for the space described above
- * are chosen to form a Legendre basis on the unit square. As a consequence,
- * the first basis function of this element is always the function that
- * is constant and equal to one.  As a result of the orthogonality of
- * the basis functions, the mass matrix is diagonal if the
- * grid cells are parallelograms. Note that this is in contrast to the
- * FE_DGPMonomial class that actually uses the monomial basis listed
- * above as basis functions.
+ * The basis functions used in this element for the space described above are
+ * chosen to form a Legendre basis on the unit square. As a consequence, the
+ * first basis function of this element is always the function that is
+ * constant and equal to one.  As a result of the orthogonality of the basis
+ * functions, the mass matrix is diagonal if the grid cells are
+ * parallelograms. Note that this is in contrast to the FE_DGPMonomial class
+ * that actually uses the monomial basis listed above as basis functions.
  *
  * The shape functions are defined in the class PolynomialSpace. The
- * polynomials used inside PolynomialSpace are Polynomials::Legendre
- * up to degree <tt>p</tt> given in FE_DGP. For the ordering of the
- * basis functions, refer to PolynomialSpace, remembering that the
- * Legendre polynomials are ordered by ascending degree.
+ * polynomials used inside PolynomialSpace are Polynomials::Legendre up to
+ * degree <tt>p</tt> given in FE_DGP. For the ordering of the basis functions,
+ * refer to PolynomialSpace, remembering that the Legendre polynomials are
+ * ordered by ascending degree.
  *
- * @note This element is not defined by finding shape functions within
- * the given function space that interpolate a particular set of points.
- * Consequently, there are no support points to which a given function
- * could be interpolated; finding a finite element function that approximates
- * a given function is therefore only possible through projection, rather
- * than interpolation. Secondly, the shape functions of this element do not
- * jointly add up to one. As a consequence of this, adding or subtracting
- * a constant value -- such as one would do to make a function have mean
- * value zero -- can not be done by simply subtracting the constant value
- * from each degree of freedom. Rather, one needs to use the fact that the
- * first basis function is constant equal to one and simply subtract the
- * constant from the value of the degree of freedom corresponding to this
- * first shape function on each cell.
+ * @note This element is not defined by finding shape functions within the
+ * given function space that interpolate a particular set of points.
+ * Consequently, there are no support points to which a given function could
+ * be interpolated; finding a finite element function that approximates a
+ * given function is therefore only possible through projection, rather than
+ * interpolation. Secondly, the shape functions of this element do not jointly
+ * add up to one. As a consequence of this, adding or subtracting a constant
+ * value -- such as one would do to make a function have mean value zero --
+ * can not be done by simply subtracting the constant value from each degree
+ * of freedom. Rather, one needs to use the fact that the first basis function
+ * is constant equal to one and simply subtract the constant from the value of
+ * the degree of freedom corresponding to this first shape function on each
+ * cell.
  *
  *
  * @note This class is only partially implemented for the codimension one case
- * (<tt>spacedim != dim </tt>), since no passage of information
- * between meshes of different refinement level is possible because
- * the embedding and projection matrices are not computed in the class
- * constructor.
+ * (<tt>spacedim != dim </tt>), since no passage of information between meshes
+ * of different refinement level is possible because the embedding and
+ * projection matrices are not computed in the class constructor.
  *
  * <h3>Transformation properties</h3>
  *
- * It is worth noting that under a (bi-, tri-)linear mapping, the
- * space described by this element does not contain $P(k)$, even if we
- * use a basis of polynomials of degree $k$. Consequently, for
- * example, on meshes with non-affine cells, a linear function can not
- * be exactly represented by elements of type FE_DGP(1) or
- * FE_DGPMonomial(1).
+ * It is worth noting that under a (bi-, tri-)linear mapping, the space
+ * described by this element does not contain $P(k)$, even if we use a basis
+ * of polynomials of degree $k$. Consequently, for example, on meshes with
+ * non-affine cells, a linear function can not be exactly represented by
+ * elements of type FE_DGP(1) or FE_DGPMonomial(1).
  *
- * This can be understood by the following 2-d example: consider the
- * cell with vertices at $(0,0),(1,0),(0,1),(s,s)$:
- * @image html dgp_doesnt_contain_p.png
+ * This can be understood by the following 2-d example: consider the cell with
+ * vertices at $(0,0),(1,0),(0,1),(s,s)$: @image html dgp_doesnt_contain_p.png
  *
- * For this cell, a bilinear transformation $F$ produces the relations
- * $x=\hat x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate
- * reference coordinates $\hat x,\hat y$ and coordinates in real space
- * $x,y$. Under this mapping, the constant function is clearly mapped
- * onto itself, but the two other shape functions of the $P_1$ space,
- * namely $\phi_1(\hat x,\hat y)=\hat x$ and $\phi_2(\hat x,\hat
- * y)=\hat y$ are mapped onto
+ * For this cell, a bilinear transformation $F$ produces the relations $x=\hat
+ * x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate reference
+ * coordinates $\hat x,\hat y$ and coordinates in real space $x,y$. Under this
+ * mapping, the constant function is clearly mapped onto itself, but the two
+ * other shape functions of the $P_1$ space, namely $\phi_1(\hat x,\hat
+ * y)=\hat x$ and $\phi_2(\hat x,\hat y)=\hat y$ are mapped onto
  * $\phi_1(x,y)=\frac{x-t}{t(s-1)},\phi_2(x,y)=t$ where
  * $t=\frac{y}{s-x+sx+y-sy}$.
  *
- * For the simple case that $s=1$, i.e. if the real cell is the unit
- * square, the expressions can be simplified to $t=y$ and
- * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the
- * functions $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and
- * neither is any linear combincation of them. Consequently, the
- * linear functions are not within the range of the mapped $P_1$
- * polynomials.
+ * For the simple case that $s=1$, i.e. if the real cell is the unit square,
+ * the expressions can be simplified to $t=y$ and
+ * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the functions
+ * $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and neither is any
+ * linear combincation of them. Consequently, the linear functions are not
+ * within the range of the mapped $P_1$ polynomials.
  *
  *
  * @author Guido Kanschat, 2001, 2002, Ralf Hartmann 2004
@@ -113,19 +107,14 @@ class FE_DGP : public FE_Poly<PolynomialSpace<dim>,dim,spacedim>
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials of degree @p p.
+   * Constructor for tensor product polynomials of degree @p p.
    */
   FE_DGP (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGP<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGP<dim>(degree)</tt>, with @p dim and @p degree replaced
+   * by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -135,49 +124,43 @@ public:
    */
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as
-   * hp_vertex_dof_indices(),
-   * except that the function
-   * treats degrees of freedom on
-   * quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    *
-   * This being a discontinuous element,
-   * the set of such constraints is of
+   * This being a discontinuous element, the set of such constraints is of
    * course empty.
    */
   virtual
@@ -185,29 +168,21 @@ public:
   hp_quad_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Return whether this element
-   * implements its hanging node
-   * constraints in the new way,
-   * which has to be used to make
-   * elements "hp compatible".
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
    *
-   * For the FE_DGP class the result is
-   * always true (independent of the degree
-   * of the element), as it has no hanging
-   * nodes (being a discontinuous element).
+   * For the FE_DGP class the result is always true (independent of the degree
+   * of the element), as it has no hanging nodes (being a discontinuous
+   * element).
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    */
   virtual
@@ -219,24 +194,14 @@ public:
    */
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -244,24 +209,14 @@ public:
                                  FullMatrix<double>       &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -277,42 +232,31 @@ public:
                                     const unsigned int face_index) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual,
-   * since finite element objects
-   * are usually accessed through
-   * pointers to their base class,
-   * rather than the class itself.
+   * This function is made virtual, since finite element objects are usually
+   * accessed through pointers to their base class, rather than the class
+   * itself.
    */
   virtual std::size_t memory_consumption () const;
 
 
   /**
-   * Declare a nested class which
-   * will hold static definitions of
-   * various matrices such as
-   * constraint and embedding
-   * matrices. The definition of
-   * the various static fields are
-   * in the files <tt>fe_dgp_[123]d.cc</tt>
-   * in the source directory.
+   * Declare a nested class which will hold static definitions of various
+   * matrices such as constraint and embedding matrices. The definition of the
+   * various static fields are in the files <tt>fe_dgp_[123]d.cc</tt> in the
+   * source directory.
    */
   struct Matrices
   {
     /**
-     * As @p embedding but for
-     * projection matrices.
+     * As @p embedding but for projection matrices.
      */
     static const double *const projection_matrices[][GeometryInfo<dim>::max_children_per_cell];
 
     /**
-     * As
-     * @p n_embedding_matrices
-     * but for projection
-     * matrices.
+     * As @p n_embedding_matrices but for projection matrices.
      */
     static const unsigned int n_projection_matrices;
   };
@@ -327,25 +271,19 @@ public:
 protected:
 
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim,spacedim> *clone() const;
 
 private:
 
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
 };
index 2d694f65922a7dae17519057c61fd22d0aeac1d1..44a30b64fa661cf5172dd5b0cea70e864d6e05be 100644 (file)
@@ -31,58 +31,52 @@ template <int dim, int spacedim> class MappingQ;
 /**
  * Discontinuous finite elements based on monomials.
  *
- * This finite element implements complete polynomial spaces, that is,
- * dim-dimensional polynomials of degree p. For example, in 2d the
- * element FE_DGP(1) would represent the span of the functions
- * $\{1,\hat x,\hat y\}$, which is in contrast to the element FE_DGQ(1)
- * that is formed by the span of $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the
- * DGP space has only three unknowns for each quadrilateral, it is
- * immediately clear that this element can not be continuous.
+ * This finite element implements complete polynomial spaces, that is, dim-
+ * dimensional polynomials of degree p. For example, in 2d the element
+ * FE_DGP(1) would represent the span of the functions $\{1,\hat x,\hat y\}$,
+ * which is in contrast to the element FE_DGQ(1) that is formed by the span of
+ * $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the DGP space has only three
+ * unknowns for each quadrilateral, it is immediately clear that this element
+ * can not be continuous.
  *
- * The basis functions for this element are chosen to be the monomials
- * listed above. Note that this is the main difference to the FE_DGP
- * class that uses a set of polynomials of complete degree
- * <code>p</code> that form a Legendre basis on the unit square. Thus,
- * there, the mass matrix is diagonal, if the grid cells are
- * parallelograms. The basis here does not have this property;
- * however, it is simpler to compute. On the other hand, this element
- * has the additional disadvantage that the local cell matrices
- * usually have a worse condition number than the ones originating
- * from the FE_DGP element.
+ * The basis functions for this element are chosen to be the monomials listed
+ * above. Note that this is the main difference to the FE_DGP class that uses
+ * a set of polynomials of complete degree <code>p</code> that form a Legendre
+ * basis on the unit square. Thus, there, the mass matrix is diagonal, if the
+ * grid cells are parallelograms. The basis here does not have this property;
+ * however, it is simpler to compute. On the other hand, this element has the
+ * additional disadvantage that the local cell matrices usually have a worse
+ * condition number than the ones originating from the FE_DGP element.
  *
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
  *
  * <h3>Transformation properties</h3>
  *
- * It is worth noting that under a (bi-, tri-)linear mapping, the
- * space described by this element does not contain $P(k)$, even if we
- * use a basis of polynomials of degree $k$. Consequently, for
- * example, on meshes with non-affine cells, a linear function can not
- * be exactly represented by elements of type FE_DGP(1) or
- * FE_DGPMonomial(1).
+ * It is worth noting that under a (bi-, tri-)linear mapping, the space
+ * described by this element does not contain $P(k)$, even if we use a basis
+ * of polynomials of degree $k$. Consequently, for example, on meshes with
+ * non-affine cells, a linear function can not be exactly represented by
+ * elements of type FE_DGP(1) or FE_DGPMonomial(1).
  *
- * This can be understood by the following 2-d example: consider the
- * cell with vertices at $(0,0),(1,0),(0,1),(s,s)$:
- * @image html dgp_doesnt_contain_p.png
+ * This can be understood by the following 2-d example: consider the cell with
+ * vertices at $(0,0),(1,0),(0,1),(s,s)$: @image html dgp_doesnt_contain_p.png
  *
- * For this cell, a bilinear transformation $F$ produces the relations
- * $x=\hat x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate
- * reference coordinates $\hat x,\hat y$ and coordinates in real space
- * $x,y$. Under this mapping, the constant function is clearly mapped
- * onto itself, but the two other shape functions of the $P_1$ space,
- * namely $\phi_1(\hat x,\hat y)=\hat x$ and $\phi_2(\hat x,\hat
- * y)=\hat y$ are mapped onto
+ * For this cell, a bilinear transformation $F$ produces the relations $x=\hat
+ * x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate reference
+ * coordinates $\hat x,\hat y$ and coordinates in real space $x,y$. Under this
+ * mapping, the constant function is clearly mapped onto itself, but the two
+ * other shape functions of the $P_1$ space, namely $\phi_1(\hat x,\hat
+ * y)=\hat x$ and $\phi_2(\hat x,\hat y)=\hat y$ are mapped onto
  * $\phi_1(x,y)=\frac{x-t}{t(s-1)},\phi_2(x,y)=t$ where
  * $t=\frac{y}{s-x+sx+y-sy}$.
  *
- * For the simple case that $s=1$, i.e. if the real cell is the unit
- * square, the expressions can be simplified to $t=y$ and
- * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the
- * functions $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and
- * neither is any linear combincation of them. Consequently, the
- * linear functions are not within the range of the mapped $P_1$
- * polynomials.
+ * For the simple case that $s=1$, i.e. if the real cell is the unit square,
+ * the expressions can be simplified to $t=y$ and
+ * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the functions
+ * $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and neither is any
+ * linear combincation of them. Consequently, the linear functions are not
+ * within the range of the mapped $P_1$ polynomials.
  *
  *
  * @author Ralf Hartmann, 2004
@@ -92,19 +86,14 @@ class FE_DGPMonomial : public FE_Poly<PolynomialsP<dim>,dim>
 {
 public:
   /**
-   * Constructor for the polynomial
-   * space of degree <tt>p</tt>.
+   * Constructor for the polynomial space of degree <tt>p</tt>.
    */
   FE_DGPMonomial (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGPMonomial<dim>(degree)</tt>,
-   * with <tt>dim</tt> and
-   * <tt>p</tt> replaced by
-   * appropriate values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGPMonomial<dim>(degree)</tt>, with <tt>dim</tt> and
+   * <tt>p</tt> replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -114,49 +103,43 @@ public:
    */
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Same as
-   * hp_vertex_dof_indices(),
-   * except that the function
-   * treats degrees of freedom on
-   * quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    *
-   * This being a discontinuous element,
-   * the set of such constraints is of
+   * This being a discontinuous element, the set of such constraints is of
    * course empty.
    */
   virtual
@@ -164,30 +147,21 @@ public:
   hp_quad_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Return whether this element
-   * implements its hanging node
-   * constraints in the new way,
-   * which has to be used to make
-   * elements "hp compatible".
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
    *
-   * For the FE_DGPMonomial class the
-   * result is always true (independent of
-   * the degree of the element), as it has
-   * no hanging nodes (being a
+   * For the FE_DGPMonomial class the result is always true (independent of
+   * the degree of the element), as it has no hanging nodes (being a
    * discontinuous element).
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    */
   virtual
@@ -199,44 +173,27 @@ public:
    */
 
   /**
-   * Return the matrix
-   * interpolating from the given
-   * finite element to the present
-   * one. The size of the matrix is
-   * then @p dofs_per_cell times
+   * Return the matrix interpolating from the given finite element to the
+   * present one. The size of the matrix is then @p dofs_per_cell times
    * <tt>source.dofs_per_cell</tt>.
    *
-   * These matrices are only
-   * available if the source
-   * element is also a @p FE_Q
-   * element. Otherwise, an
-   * exception of type
-   * FiniteElement<dim>::ExcInterpolationNotImplemented
-   * is thrown.
+   * These matrices are only available if the source element is also a @p FE_Q
+   * element. Otherwise, an exception of type
+   * FiniteElement<dim>::ExcInterpolationNotImplemented is thrown.
    */
   virtual void
   get_interpolation_matrix (const FiniteElement<dim> &source,
                             FullMatrix<double>           &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then @p dofs_per_face times
-   * <tt>source.dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then @p
+   * dofs_per_face times <tt>source.dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -244,24 +201,14 @@ public:
                                  FullMatrix<double>       &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then @p dofs_per_face times
-   * <tt>source.dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then @p
+   * dofs_per_face times <tt>source.dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -277,54 +224,41 @@ public:
                                     const unsigned int face_index) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual,
-   * since finite element objects
-   * are usually accessed through
-   * pointers to their base class,
-   * rather than the class itself.
+   * This function is made virtual, since finite element objects are usually
+   * accessed through pointers to their base class, rather than the class
+   * itself.
    */
   virtual std::size_t memory_consumption () const;
 
 protected:
 
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim> *clone() const;
 
 private:
 
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
 
   /**
-   * Initialize the embedding
-   * matrices. Called from the
-   * constructor.
+   * Initialize the embedding matrices. Called from the constructor.
    */
   void initialize_embedding ();
 
   /**
-   * Initialize the restriction
-   * matrices. Called from the
-   * constructor.
+   * Initialize the restriction matrices. Called from the constructor.
    */
   void initialize_restriction ();
 };
index 8f6c7d4d09160212306061df31c130b9bdf35b26..4a2dcf46c5b0dedb5408014a64577b36c1721f98 100644 (file)
@@ -38,15 +38,14 @@ template <int dim, int spacedim> class MappingQ;
  * This finite element implements complete polynomial spaces, that is,
  * $d$-dimensional polynomials of order $k$.
  *
- * The polynomials are not mapped. Therefore, they are constant,
- * linear, quadratic, etc. on any grid cell.
+ * The polynomials are not mapped. Therefore, they are constant, linear,
+ * quadratic, etc. on any grid cell.
  *
- * Since the polynomials are evaluated at the quadrature points of the
- * actual grid cell, no grid transfer and interpolation matrices are
- * available.
+ * Since the polynomials are evaluated at the quadrature points of the actual
+ * grid cell, no grid transfer and interpolation matrices are available.
  *
- * The purpose of this class is experimental, therefore the
- * implementation will remain incomplete.
+ * The purpose of this class is experimental, therefore the implementation
+ * will remain incomplete.
  *
  * Besides, this class is not implemented for the codimension one case
  * (<tt>spacedim != dim</tt>).
@@ -58,50 +57,32 @@ class FE_DGPNonparametric : public FiniteElement<dim,spacedim>
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials of degree @p k.
+   * Constructor for tensor product polynomials of degree @p k.
    */
   FE_DGPNonparametric (const unsigned int k);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGPNonparametric<dim>(degree)</tt>,
-   * with @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGPNonparametric<dim>(degree)</tt>, with @p dim and @p
+   * degree replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
   /**
-   * Return the value of the
-   * @p ith shape function at the
-   * point @p p. See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
+   * Return the value of the @p ith shape function at the point @p p. See the
+   * FiniteElement base class for more information about the semantics of this
    * function.
    */
   virtual double shape_value (const unsigned int i,
                               const Point<dim> &p) const;
 
   /**
-   * Return the value of the
-   * @p componentth vector
-   * component of the @p ith shape
-   * function at the point
-   * @p p. See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
-   * function.
+   * Return the value of the @p componentth vector component of the @p ith
+   * shape function at the point @p p. See the FiniteElement base class for
+   * more information about the semantics of this function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * @p _component suffix were
-   * called, provided that the
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the @p _component suffix were called, provided that the
    * specified component is zero.
    */
   virtual double shape_value_component (const unsigned int i,
@@ -109,33 +90,20 @@ public:
                                         const unsigned int component) const;
 
   /**
-   * Return the gradient of the
-   * @p ith shape function at the
-   * point @p p. See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
-   * function.
+   * Return the gradient of the @p ith shape function at the point @p p. See
+   * the FiniteElement base class for more information about the semantics of
+   * this function.
    */
   virtual Tensor<1,dim> shape_grad (const unsigned int  i,
                                     const Point<dim>   &p) const;
 
   /**
-   * Return the gradient of the
-   * @p componentth vector
-   * component of the @p ith shape
-   * function at the point
-   * @p p. See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
-   * function.
+   * Return the gradient of the @p componentth vector component of the @p ith
+   * shape function at the point @p p. See the FiniteElement base class for
+   * more information about the semantics of this function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * @p _component suffix were
-   * called, provided that the
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the @p _component suffix were called, provided that the
    * specified component is zero.
    */
   virtual Tensor<1,dim> shape_grad_component (const unsigned int i,
@@ -143,34 +111,20 @@ public:
                                               const unsigned int component) const;
 
   /**
-   * Return the tensor of second
-   * derivatives of the @p ith
-   * shape function at point @p p
-   * on the unit cell.  See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
-   * function.
+   * Return the tensor of second derivatives of the @p ith shape function at
+   * point @p p on the unit cell.  See the FiniteElement base class for more
+   * information about the semantics of this function.
    */
   virtual Tensor<2,dim> shape_grad_grad (const unsigned int  i,
                                          const Point<dim> &p) const;
 
   /**
-   * Return the second derivative
-   * of the @p componentth vector
-   * component of the @p ith shape
-   * function at the point
-   * @p p. See the
-   * FiniteElement base
-   * class for more information
-   * about the semantics of this
-   * function.
+   * Return the second derivative of the @p componentth vector component of
+   * the @p ith shape function at the point @p p. See the FiniteElement base
+   * class for more information about the semantics of this function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * @p _component suffix were
-   * called, provided that the
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the @p _component suffix were called, provided that the
    * specified component is zero.
    */
   virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
@@ -178,32 +132,20 @@ public:
                                                    const unsigned int component) const;
 
   /**
-   * Return the polynomial degree
-   * of this finite element,
-   * i.e. the value passed to the
-   * constructor.
+   * Return the polynomial degree of this finite element, i.e. the value
+   * passed to the constructor.
    */
   unsigned int get_degree () const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -211,24 +153,14 @@ public:
                                  FullMatrix<double>       &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -242,76 +174,65 @@ public:
    */
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_quad_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Return whether this element
-   * implements its hanging node
-   * constraints in the new way,
-   * which has to be used to make
-   * elements "hp compatible".
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
    *
-   * For the FE_DGPNonparametric class the
-   * result is always true (independent of
-   * the degree of the element), as it has
-   * no hanging nodes (being a
+   * For the FE_DGPNonparametric class the result is always true (independent
+   * of the degree of the element), as it has no hanging nodes (being a
    * discontinuous element).
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    */
   virtual
@@ -330,62 +251,45 @@ public:
                                     const unsigned int face_index) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual,
-   * since finite element objects
-   * are usually accessed through
-   * pointers to their base class,
-   * rather than the class itself.
+   * This function is made virtual, since finite element objects are usually
+   * accessed through pointers to their base class, rather than the class
+   * itself.
    */
   virtual std::size_t memory_consumption () const;
 
 
 private:
   /**
-   * Declare a nested class which
-   * will hold static definitions of
-   * various matrices such as
-   * constraint and embedding
-   * matrices. The definition of
-   * the various static fields are
-   * in the files <tt>fe_dgp_[123]d.cc</tt>
-   * in the source directory.
+   * Declare a nested class which will hold static definitions of various
+   * matrices such as constraint and embedding matrices. The definition of the
+   * various static fields are in the files <tt>fe_dgp_[123]d.cc</tt> in the
+   * source directory.
    */
   struct Matrices
   {
     /**
-     * Pointers to the embedding
-     * matrices, one for each
-     * polynomial degree starting
-     * from constant elements
+     * Pointers to the embedding matrices, one for each polynomial degree
+     * starting from constant elements
      */
     static const double *const embedding[][GeometryInfo<dim>::max_children_per_cell];
 
     /**
-     * Number of elements (first
-     * index) the above field
-     * has. Equals the highest
-     * polynomial degree plus one
-     * for which the embedding
-     * matrices have been
-     * computed.
+     * Number of elements (first index) the above field has. Equals the
+     * highest polynomial degree plus one for which the embedding matrices
+     * have been computed.
      */
     static const unsigned int n_embedding_matrices;
 
     /**
-     * As @p embedding but for
-     * projection matrices.
+     * As @p embedding but for projection matrices.
      */
     static const double *const projection_matrices[][GeometryInfo<dim>::max_children_per_cell];
 
     /**
-     * As
-     * @p n_embedding_matrices
-     * but for projection
-     * matrices.
+     * As @p n_embedding_matrices but for projection matrices.
      */
     static const unsigned int n_projection_matrices;
   };
@@ -393,18 +297,15 @@ private:
 protected:
 
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim,spacedim> *clone() const;
 
   /**
-   * Prepare internal data
-   * structures and fill in values
-   * independent of the cell.
+   * Prepare internal data structures and fill in values independent of the
+   * cell.
    */
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
@@ -413,9 +314,7 @@ protected:
             const Quadrature<dim> &quadrature) const ;
 
   /**
-   * Implementation of the same
-   * function in
-   * FiniteElement.
+   * Implementation of the same function in FiniteElement.
    */
   virtual void
   fill_fe_values (const Mapping<dim,spacedim> &mapping,
@@ -427,9 +326,7 @@ protected:
                   CellSimilarity::Similarity                       &cell_similarity) const;
 
   /**
-   * Implementation of the same
-   * function in
-   * FiniteElement.
+   * Implementation of the same function in FiniteElement.
    */
   virtual void
   fill_fe_face_values (const Mapping<dim,spacedim> &mapping,
@@ -441,9 +338,7 @@ protected:
                        FEValuesData<dim,spacedim> &data) const ;
 
   /**
-   * Implementation of the same
-   * function in
-   * FiniteElement.
+   * Implementation of the same function in FiniteElement.
    */
   virtual void
   fill_fe_subface_values (const Mapping<dim,spacedim> &mapping,
@@ -458,53 +353,32 @@ protected:
 private:
 
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
 
   /**
-   * Given a set of flags indicating
-   * what quantities are requested
-   * from a @p FEValues object,
-   * return which of these can be
-   * precomputed once and for
-   * all. Often, the values of
-   * shape function at quadrature
-   * points can be precomputed, for
-   * example, in which case the
-   * return value of this function
-   * would be the logical and of
-   * the input @p flags and
-   * @p update_values.
+   * Given a set of flags indicating what quantities are requested from a @p
+   * FEValues object, return which of these can be precomputed once and for
+   * all. Often, the values of shape function at quadrature points can be
+   * precomputed, for example, in which case the return value of this function
+   * would be the logical and of the input @p flags and @p update_values.
    *
-   * For the present kind of finite
-   * element, this is exactly the
-   * case.
+   * For the present kind of finite element, this is exactly the case.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
   /**
-   * This is the opposite to the
-   * above function: given a set of
-   * flags indicating what we want
-   * to know, return which of these
-   * need to be computed each time
-   * we visit a new cell.
+   * This is the opposite to the above function: given a set of flags
+   * indicating what we want to know, return which of these need to be
+   * computed each time we visit a new cell.
    *
-   * If for the computation of one
-   * quantity something else is
-   * also required (for example, we
-   * often need the covariant
-   * transformation when gradients
-   * need to be computed), include
-   * this in the result as well.
+   * If for the computation of one quantity something else is also required
+   * (for example, we often need the covariant transformation when gradients
+   * need to be computed), include this in the result as well.
    */
   virtual UpdateFlags update_each (const UpdateFlags flags) const;
 
@@ -514,19 +388,15 @@ private:
   const unsigned int degree;
 
   /**
-   * Pointer to an object
-   * representing the polynomial
-   * space used here.
+   * Pointer to an object representing the polynomial space used here.
    */
   const PolynomialSpace<dim> polynomial_space;
 
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
   {
@@ -543,9 +413,7 @@ private:
   template <int, int> friend class FE_DGPNonparametric;
 
   /**
-   * Allows @p MappingQ class to
-   * access to build_renumbering
-   * function.
+   * Allows @p MappingQ class to access to build_renumbering function.
    */
   template <int, int> friend class MappingQ;
 //    friend class MappingQ<dim>;
index 8c093741919958d4e62ec75941a945849c5e81bf..bf996354e342ddd4cb84acf324add4e0cecc7fcc 100644 (file)
@@ -30,16 +30,16 @@ template <int dim> class Quadrature;
 /*@{*/
 
 /**
- * Implementation of scalar, discontinuous tensor product elements
- * based on equidistant support points.
+ * Implementation of scalar, discontinuous tensor product elements based on
+ * equidistant support points.
  *
  * This is a discontinuous finite element based on tensor products of
- * Lagrangian polynomials. The shape functions are Lagrangian
- * interpolants of an equidistant grid of points on the unit cell. The
- * points are numbered in lexicographical order, with <i>x</i> running
- * fastest, then <i>y</i>, then <i>z</i> (if these coordinates are present for a
- * given space dimension at all). For example, these are the node
- * orderings for <tt>FE_DGQ(1)</tt> in 3d:
+ * Lagrangian polynomials. The shape functions are Lagrangian interpolants of
+ * an equidistant grid of points on the unit cell. The points are numbered in
+ * lexicographical order, with <i>x</i> running fastest, then <i>y</i>, then
+ * <i>z</i> (if these coordinates are present for a given space dimension at
+ * all). For example, these are the node orderings for <tt>FE_DGQ(1)</tt> in
+ * 3d:
  *  @verbatim
  *         6-------7        6-------7
  *        /|       |       /       /|
@@ -67,16 +67,14 @@ template <int dim> class Quadrature;
  *  @endverbatim
  * with node 13 being placed in the interior of the hex.
  *
- * Note, however, that these are just the Lagrange interpolation
- * points of the shape functions. Even though they may physically be
- * on the surface of the cell, they are logically in the interior
- * since there are no continuity requirements for these shape
- * functions across cell boundaries.
- * This class if partially implemented for the codimension one case
- * (<tt>spacedim != dim </tt>), since no passage of information
- * between meshes of different refinement level is possible because
- * the embedding and projection matrices are not computed in the class
- * constructor.
+ * Note, however, that these are just the Lagrange interpolation points of the
+ * shape functions. Even though they may physically be on the surface of the
+ * cell, they are logically in the interior since there are no continuity
+ * requirements for these shape functions across cell boundaries. This class
+ * if partially implemented for the codimension one case (<tt>spacedim != dim
+ * </tt>), since no passage of information between meshes of different
+ * refinement level is possible because the embedding and projection matrices
+ * are not computed in the class constructor.
  *
  * @author Ralf Hartmann, Guido Kanschat 2001, 2004
  */
@@ -85,68 +83,42 @@ class FE_DGQ : public FE_Poly<TensorProductPolynomials<dim>, dim, spacedim>
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials of degree
-   * <tt>p</tt>. The shape
-   * functions created using this
-   * constructor correspond to
-   * Lagrange interpolation
-   * polynomials for equidistantly
-   * spaced support points in each
+   * Constructor for tensor product polynomials of degree <tt>p</tt>. The
+   * shape functions created using this constructor correspond to Lagrange
+   * interpolation polynomials for equidistantly spaced support points in each
    * coordinate direction.
    */
   FE_DGQ (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGQ<dim>(degree)</tt>, with
-   * <tt>dim</tt> and <tt>degree</tt>
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGQ<dim>(degree)</tt>, with <tt>dim</tt> and
+   * <tt>degree</tt> replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
   /**
-   * Return the matrix
-   * interpolating from the given
-   * finite element to the present
-   * one. The size of the matrix is
-   * then @p dofs_per_cell times
+   * Return the matrix interpolating from the given finite element to the
+   * present one. The size of the matrix is then @p dofs_per_cell times
    * <tt>source.dofs_per_cell</tt>.
    *
-   * These matrices are only
-   * available if the source
-   * element is also a @p FE_DGQ
-   * element. Otherwise, an
-   * exception of type
-   * FiniteElement<dim>::ExcInterpolationNotImplemented
-   * is thrown.
+   * These matrices are only available if the source element is also a @p
+   * FE_DGQ element. Otherwise, an exception of type
+   * FiniteElement<dim>::ExcInterpolationNotImplemented is thrown.
    */
   virtual void
   get_interpolation_matrix (const FiniteElement<dim, spacedim> &source,
                             FullMatrix<double>           &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -154,24 +126,14 @@ public:
                                  FullMatrix<double>       &matrix) const;
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the face of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to
-   * implement this function. They
-   * may only provide interpolation
-   * matrices for certain source
-   * finite elements, for example
-   * those from the same family. If
-   * they don't implement
-   * interpolation from a given
-   * element, then they must throw
-   * an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * FiniteElement<dim>::ExcInterpolationNotImplemented.
    */
   virtual void
@@ -231,75 +193,65 @@ public:
    */
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    *
-   * This being a discontinuous element, the set of such constraints
-   * is of course empty.
+   * This being a discontinuous element, the set of such constraints is of
+   * course empty.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_quad_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
 
   /**
-   * Return whether this element
-   * implements its hanging node
-   * constraints in the new way,
-   * which has to be used to make
-   * elements "hp compatible".
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
    *
-   * For the FE_DGQ class the result is
-   * always true (independent of the degree
-   * of the element), as it has no hanging
-   * nodes (being a discontinuous element).
+   * For the FE_DGQ class the result is always true (independent of the degree
+   * of the element), as it has no hanging nodes (being a discontinuous
+   * element).
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    */
   virtual
@@ -325,83 +277,58 @@ public:
   get_constant_modes () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual,
-   * since finite element objects
-   * are usually accessed through
-   * pointers to their base class,
-   * rather than the class itself.
+   * This function is made virtual, since finite element objects are usually
+   * accessed through pointers to their base class, rather than the class
+   * itself.
    */
   virtual std::size_t memory_consumption () const;
 
 
 protected:
   /**
-   * Constructor for tensor product
-   * polynomials based on
-   * Polynomials::Lagrange
-   * interpolation of the support
-   * points in the quadrature rule
-   * <tt>points</tt>. The degree of
-   * these polynomials is
+   * Constructor for tensor product polynomials based on Polynomials::Lagrange
+   * interpolation of the support points in the quadrature rule
+   * <tt>points</tt>. The degree of these polynomials is
    * <tt>points.size()-1</tt>.
    *
-   * Note: The FE_DGQ::clone function
-   * does not work properly for FE with
+   * Note: The FE_DGQ::clone function does not work properly for FE with
    * arbitrary nodes!
    */
   FE_DGQ (const Quadrature<1> &points);
 
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim, spacedim> *clone() const;
 
 private:
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
 
   /**
-   * Compute renumbering for rotation
-   * of degrees of freedom.
+   * Compute renumbering for rotation of degrees of freedom.
    *
-   * Rotates a tensor product
-   * numbering of degrees of
-   * freedom by 90 degrees. It is
-   * used to compute the transfer
-   * matrices of the children by
-   * using only the matrix for the
-   * first child.
+   * Rotates a tensor product numbering of degrees of freedom by 90 degrees.
+   * It is used to compute the transfer matrices of the children by using only
+   * the matrix for the first child.
    *
-   * The direction parameter
-   * determines the type of
-   * rotation. It is one character
-   * of @p xXyYzZ. The character
-   * determines the axis of
-   * rotation, case determines the
-   * direction. Lower case is
-   * counter-clockwise seen in
+   * The direction parameter determines the type of rotation. It is one
+   * character of @p xXyYzZ. The character determines the axis of rotation,
+   * case determines the direction. Lower case is counter-clockwise seen in
    * direction of the axis.
    *
-   * Since rotation around the
-   * y-axis is not used, it is not
-   * implemented either.
+   * Since rotation around the y-axis is not used, it is not implemented
+   * either.
    */
   void rotate_indices (std::vector<unsigned int> &indices,
                        const char                 direction) const;
@@ -417,9 +344,7 @@ private:
   template <int dim1, int spacedim1> friend class FE_DGQ;
 
   /**
-   * Allows @p MappingQ class to
-   * access to build_renumbering
-   * function.
+   * Allows @p MappingQ class to access to build_renumbering function.
    */
   template <int dim1, int spacedim1> friend class MappingQ;
 };
@@ -446,35 +371,25 @@ class FE_DGQArbitraryNodes : public FE_DGQ<dim,spacedim>
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials based on
-   * Polynomials::Lagrange
-   * interpolation of the support
-   * points in the quadrature rule
-   * <tt>points</tt>. The degree of
-   * these polynomials is
+   * Constructor for tensor product polynomials based on Polynomials::Lagrange
+   * interpolation of the support points in the quadrature rule
+   * <tt>points</tt>. The degree of these polynomials is
    * <tt>points.size()-1</tt>.
    */
   FE_DGQArbitraryNodes (const Quadrature<1> &points);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGQArbitraryNodes<dim>(degree)</tt>,
-   * with <tt>dim</tt> and <tt>degree</tt>
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGQArbitraryNodes<dim>(degree)</tt>, with <tt>dim</tt> and
+   * <tt>degree</tt> replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
 protected:
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim,spacedim> *clone() const;
 };
index 6fa513d8b2d72997acb27fe5ef985cc1e2e711da..ecedda82bce1d02154ffc8c0e1661b3e6a48ca76 100644 (file)
@@ -32,18 +32,17 @@ DEAL_II_NAMESPACE_OPEN
  * and two, the polynomials hence correspond to the usual Lagrange polynomials
  * on equidistant points.
  *
- * Although the name does not give it away, the element is discontinuous
- * at locations where faces of cells meet. In particular,
- * this finite element is the trace space of FE_RaviartThomas on the faces and
- * serves in hybridized methods, e.g. in combination with the FE_DGQ
- * element. Its use is demonstrated in the step-51 tutorial program.
+ * Although the name does not give it away, the element is discontinuous at
+ * locations where faces of cells meet. In particular, this finite element is
+ * the trace space of FE_RaviartThomas on the faces and serves in hybridized
+ * methods, e.g. in combination with the FE_DGQ element. Its use is
+ * demonstrated in the step-51 tutorial program.
  *
- * @note Since this element is defined only on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, using a (cell) FEValues object will not fail using this finite
- * element space, but all shape function values extracted will be equal
- * to zero.
+ * @note Since this element is defined only on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, using a (cell)
+ * FEValues object will not fail using this finite element space, but all
+ * shape function values extracted will be equal to zero.
  *
  * @ingroup fe
  * @author Guido Kanschat, Martin Kronbichler
@@ -279,11 +278,11 @@ protected:
    * FiniteElement.
    *
    * This class assumes that shape functions of this FiniteElement do
-   * <em>not</em> depend on the actual shape of the cells in real
-   * space. Therefore, the effect in this element is as follows: if
-   * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the
-   * result. All other flags of the result are cleared, since everything else
-   * must be computed for each cell.
+   * <em>not</em> depend on the actual shape of the cells in real space.
+   * Therefore, the effect in this element is as follows: if
+   * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+   * All other flags of the result are cleared, since everything else must be
+   * computed for each cell.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
@@ -328,22 +327,20 @@ private:
 
 /**
  * A finite element, which is a Legendre element of complete polynomials on
- * each face (i.e., it is the face equivalent of what FE_DGP is on cells)
- * and undefined in the interior of the cells. The basis functions on
- * the faces are from Polynomials::Legendre.
+ * each face (i.e., it is the face equivalent of what FE_DGP is on cells) and
+ * undefined in the interior of the cells. The basis functions on the faces
+ * are from Polynomials::Legendre.
  *
- * Although the name does not give it away, the element is discontinuous
- * at locations where faces of cells meet. The element
- * serves in hybridized methods, e.g. in combination with the FE_DGP
- * element. An example of hybridizes methods can be found in the
- * step-51 tutorial program.
+ * Although the name does not give it away, the element is discontinuous at
+ * locations where faces of cells meet. The element serves in hybridized
+ * methods, e.g. in combination with the FE_DGP element. An example of
+ * hybridizes methods can be found in the step-51 tutorial program.
  *
- * @note Since this element is defined only on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, using a (cell) FEValues object will not fail using this finite
- * element space, but all shape function values extracted will be equal
- * to zero.
+ * @note Since this element is defined only on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, using a (cell)
+ * FEValues object will not fail using this finite element space, but all
+ * shape function values extracted will be equal to zero.
  *
  * @ingroup fe
  * @author Martin Kronbichler
index 629bc1acfad2814467cca7d36aad018874bbea04..340742f5c2dbd24631e88cd46f8e77104bb47539 100644 (file)
@@ -38,14 +38,14 @@ template <int dim, int spacedim> class MappingQ;
 /*@{*/
 
 /**
- * @warning Several aspects of the implementation are
- * experimental. For the moment, it is safe to use the element on
- * globally refined meshes with consistent orientation of faces. See
- * the todo entries below for more detailed caveats.
+ * @warning Several aspects of the implementation are experimental. For the
+ * moment, it is safe to use the element on globally refined meshes with
+ * consistent orientation of faces. See the todo entries below for more
+ * detailed caveats.
  *
- * Implementation of N&eacute;d&eacute;lec elements, conforming with the
- * space H<sup>curl</sup>. These elements generate vector fields with
- * tangential components continuous between mesh cells.
+ * Implementation of N&eacute;d&eacute;lec elements, conforming with the space
+ * H<sup>curl</sup>. These elements generate vector fields with tangential
+ * components continuous between mesh cells.
  *
  * We follow the convention that the degree of N&eacute;d&eacute;lec elements
  * denotes the polynomial degree of the largest complete polynomial subspace
@@ -60,97 +60,92 @@ template <int dim, int spacedim> class MappingQ;
  *   \stackrel{\text{div}}{\rightarrow}
  *   DGQ_{k}
  * @f]
- * Consequently, approximation order of
- * the Nédélec space equals the value <i>degree</i> given to the constructor.
- * In this scheme, the lowest order element would be created by the call
- * FE_Nedelec<dim>(0). Note that this follows the convention of Brezzi and
- * Raviart, though not the one used in the original paper by Nédélec.
+ * Consequently, approximation order of the Nédélec space equals the value
+ * <i>degree</i> given to the constructor. In this scheme, the lowest order
+ * element would be created by the call FE_Nedelec<dim>(0). Note that this
+ * follows the convention of Brezzi and Raviart, though not the one used in
+ * the original paper by Nédélec.
  *
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
  *
  * @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
  *
  * <h3>Restriction on transformations</h3>
  *
- * In some sense, the implementation of this element is not complete,
- * but you will rarely notice. Here is the fact: since the element is
- * vector-valued already on the unit cell, the Jacobian matrix (or its
- * inverse) is needed already to generate the values of the shape
- * functions on the cells in real space. This is in contrast to most
- * other elements, where you only need the Jacobian for the
- * gradients. Thus, to generate the gradients of Nédélec shape
- * functions, one would need to have the derivatives of the inverse of
+ * In some sense, the implementation of this element is not complete, but you
+ * will rarely notice. Here is the fact: since the element is vector-valued
+ * already on the unit cell, the Jacobian matrix (or its inverse) is needed
+ * already to generate the values of the shape functions on the cells in real
+ * space. This is in contrast to most other elements, where you only need the
+ * Jacobian for the gradients. Thus, to generate the gradients of Nédélec
+ * shape functions, one would need to have the derivatives of the inverse of
  * the Jacobian matrix.
  *
- * Basically, the Nédélec shape functions can be understood as the
- * gradients of scalar shape functions on the real cell. They are thus
- * the inverse Jacobian matrix times the gradients of scalar shape
- * functions on the unit cell. The gradient of Nédélec shape functions
- * is then, by the product rule, the sum of first the derivative (with
- * respect to true coordinates) of the inverse Jacobian times the
- * gradient (in unit coordinates) of the scalar shape function, plus
- * second the inverse Jacobian times the derivative (in true
- * coordinates) of the gradient (in unit coordinates) of the scalar
- * shape functions. Note that each of the derivatives in true
- * coordinates can be expressed as inverse Jacobian times gradient in
- * unit coordinates.
+ * Basically, the Nédélec shape functions can be understood as the gradients
+ * of scalar shape functions on the real cell. They are thus the inverse
+ * Jacobian matrix times the gradients of scalar shape functions on the unit
+ * cell. The gradient of Nédélec shape functions is then, by the product
+ * rule, the sum of first the derivative (with respect to true coordinates) of
+ * the inverse Jacobian times the gradient (in unit coordinates) of the scalar
+ * shape function, plus second the inverse Jacobian times the derivative (in
+ * true coordinates) of the gradient (in unit coordinates) of the scalar shape
+ * functions. Note that each of the derivatives in true coordinates can be
+ * expressed as inverse Jacobian times gradient in unit coordinates.
  *
- * The problem is the derivative of the inverse Jacobian. This rank-3
- * tensor can actually be computed (and we did so in very early
- * versions of the library), but is a large task and very time
- * consuming, so we dropped it. Since it is not available, we simply
- * drop this first term.
+ * The problem is the derivative of the inverse Jacobian. This rank-3 tensor
+ * can actually be computed (and we did so in very early versions of the
+ * library), but is a large task and very time consuming, so we dropped it.
+ * Since it is not available, we simply drop this first term.
  *
- * What this means for the present case: first the computation of
- * gradients of Nédélec shape functions is wrong in general. Second,
- * in the following two cases you will not notice this:
+ * What this means for the present case: first the computation of gradients of
+ * Nédélec shape functions is wrong in general. Second, in the following two
+ * cases you will not notice this:
  *
- * - If the cell is a parallelogram, then the usual bi-/trilinear mapping
- *   is in fact affine. In that case, the gradient of the Jacobian vanishes
- *   and the gradient of the shape functions is computed exactly, since the
- *   first term is zero.
+ * - If the cell is a parallelogram, then the usual bi-/trilinear mapping is
+ * in fact affine. In that case, the gradient of the Jacobian vanishes and the
+ * gradient of the shape functions is computed exactly, since the first term
+ * is zero.
  *
- * - With the Nédélec elements, you will usually want to compute
- *   the curl, not the general derivative tensor. However, the curl of the
- *   Jacobian vanishes, so for the curl of shape functions the first term
- *   is irrelevant, and the curl will always be computed correctly even on
- *   cells that are not parallelograms.
+ * - With the Nédélec elements, you will usually want to compute the curl,
+ * not the general derivative tensor. However, the curl of the Jacobian
+ * vanishes, so for the curl of shape functions the first term is irrelevant,
+ * and the curl will always be computed correctly even on cells that are not
+ * parallelograms.
  *
  *
  * <h3>Interpolation</h3>
  *
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the N&eacute;d&eacute;lec element are constructed such that
- * interpolation and computing the curl are commuting operations on
- * rectangular mesh cells. We require this from interpolating
- * arbitrary functions as well as the #restriction matrices.
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * N&eacute;d&eacute;lec element are constructed such that interpolation and
+ * computing the curl are commuting operations on rectangular mesh cells. We
+ * require this from interpolating arbitrary functions as well as the
+ * #restriction matrices.
  *
  * <h4>Node values</h4>
  *
- * The @ref GlossNodes "node values" for an element of degree <i>k</i>
- * on the reference cell are:
+ * The @ref GlossNodes "node values" for an element of degree <i>k</i> on the
+ * reference cell are:
  * <ol>
- * <li> On edges: the moments of the tangential component with respect
- * to polynomials of degree <i>k</i>.
- * <li> On faces: the moments of the tangential components with
- * respect to <tt>dim</tt>-1 dimensional FE_Nedelec
- * polynomials of degree <i>k</i>-1.
- * <li> In cells: the moments with respect to gradients of polynomials
- * in FE_Q of degree <i>k</i>.
+ * <li> On edges: the moments of the tangential component with respect to
+ * polynomials of degree <i>k</i>.
+ * <li> On faces: the moments of the tangential components with respect to
+ * <tt>dim</tt>-1 dimensional FE_Nedelec polynomials of degree <i>k</i>-1.
+ * <li> In cells: the moments with respect to gradients of polynomials in FE_Q
+ * of degree <i>k</i>.
  * </ol>
  *
  * <h4>Generalized support points</h4>
  *
  * The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are those of
- * QGauss<sub>k+1</sub> on each edge and QGauss<sub>k+2</sub> on each face and in
- * the interior of the cell (or none for N<sub>1</sub>).
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are those of QGauss<sub>k+1</sub> on each edge and
+ * QGauss<sub>k+2</sub> on each face and in the interior of the cell (or none
+ * for N<sub>1</sub>).
  *
  * @author Markus B&uuml;rg
  * @date 2009, 2010, 2011
@@ -160,19 +155,14 @@ class FE_Nedelec : public FE_PolyTensor<PolynomialsNedelec<dim>, dim>
 {
 public:
   /**
-   * Constructor for the N&eacute;d&eacute;lec
-   * element of degree @p p.
+   * Constructor for the N&eacute;d&eacute;lec element of degree @p p.
    */
   FE_Nedelec (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_Nedelec<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_Nedelec<dim>(degree)</tt>, with @p dim and @p degree
+   * replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -185,69 +175,63 @@ public:
                                     const unsigned int face_index) const;
 
   /**
-   * Return whether this element implements its
-   * hanging node constraints in the new way, which
-   * has to be used to make elements "hp compatible".
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
    *
-   * For the <tt>FE_Nedelec</tt> class the result is
-   * always true (independent of the degree of the
-   * element), as it implements the complete set of
+   * For the <tt>FE_Nedelec</tt> class the result is always true (independent
+   * of the degree of the element), as it implements the complete set of
    * functions necessary for hp capability.
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * Return whether this element dominates the one,
-   * which is given as argument.
+   * Return whether this element dominates the one, which is given as
+   * argument.
    */
   virtual FiniteElementDomination::Domination
   compare_for_face_domination (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    */
   virtual std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that
-   * the function treats degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    */
   virtual std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that
-   * the function treats degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    */
   virtual std::vector<std::pair<unsigned int, unsigned int> >
   hp_quad_dof_identities (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Return the matrix interpolating from a face of one
-   * element to the face of the neighboring element. The
-   * size of the matrix is then <tt>source.dofs_per_face</tt>
-   * times <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of one element to the face of
+   * the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to implement this function.
-   * They may only provide interpolation matrices for certain
-   * source finite elements, for example those from the same
-   * family. If they don't implement interpolation from a given
-   * element, then they must throw an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * <tt>FiniteElement<dim>::ExcInterpolationNotImplemented</tt>.
    */
   virtual void
@@ -255,16 +239,14 @@ public:
                                  FullMatrix<double> &matrix) const;
 
   /**
-   * Return the matrix interpolating from a face of one element
-   * to the subface of the neighboring element. The size of
-   * the matrix is then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of one element to the subface
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to implement this function.
-   * They may only provide interpolation matrices for certain
-   * source finite elements, for example those from the same
-   * family. If they don't implement interpolation from a given
-   * element, then they must throw an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * <tt>ExcInterpolationNotImplemented</tt>.
    */
   virtual void
@@ -334,117 +316,72 @@ public:
 
 private:
   /**
-       * Only for internal use. Its
-       * full name is
-       * @p get_dofs_per_object_vector
-       * function and it creates the
-       * @p dofs_per_object vector that is
-       * needed within the constructor to
-       * be passed to the constructor of
-       * @p FiniteElementData.
-       *
-       * If the optional argument
-       * <tt>dg</tt> is true, the
-       * vector returned will have all
-       * degrees of freedom assigned to
-       * the cell, none on the faces
-       * and edges.
-       */
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
+   *
+   * If the optional argument <tt>dg</tt> is true, the vector returned will
+   * have all degrees of freedom assigned to the cell, none on the faces and
+   * edges.
+   */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree, bool dg=false);
 
   /**
-   * Initialize the @p
-   * generalized_support_points
-   * field of the FiniteElement
-   * class and fill the tables with
-   * interpolation weights
-   * (#boundary_weights and
-   * interior_weights). Called
-   * from the constructor.
+   * Initialize the @p generalized_support_points field of the FiniteElement
+   * class and fill the tables with interpolation weights (#boundary_weights
+   * and interior_weights). Called from the constructor.
    */
   void initialize_support_points (const unsigned int degree);
 
   /**
-   * Initialize the interpolation
-   * from functions on refined mesh
-   * cells onto the father
-   * cell. According to the
-   * philosophy of the
-   * Nédélec element, this
-   * restriction operator preserves
-   * the curl of a function
-   * weakly.
+   * Initialize the interpolation from functions on refined mesh cells onto
+   * the father cell. According to the philosophy of the Nédélec element,
+   * this restriction operator preserves the curl of a function weakly.
    */
   void initialize_restriction ();
 
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points. There is one row
-     * for each shape function,
-     * containing values for each
-     * quadrature point. Since
-     * the shape functions are
-     * vector-valued (with as
-     * many components as there
-     * are space dimensions), the
-     * value is a tensor.
+     * Array with shape function values in quadrature points. There is one row
+     * for each shape function, containing values for each quadrature point.
+     * Since the shape functions are vector-valued (with as many components as
+     * there are space dimensions), the value is a tensor.
      *
-     * In this array, we store
-     * the values of the shape
-     * function in the quadrature
-     * points on the unit
-     * cell. The transformation
-     * to the real space cell is
-     * then simply done by
-     * multiplication with the
-     * Jacobian of the mapping.
+     * In this array, we store the values of the shape function in the
+     * quadrature points on the unit cell. The transformation to the real
+     * space cell is then simply done by multiplication with the Jacobian of
+     * the mapping.
      */
     std::vector<std::vector<Tensor<1, dim> > > shape_values;
 
     /**
-     * Array with shape function
-     * gradients in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
+     * Array with shape function gradients in quadrature points. There is one
+     * row for each shape function, containing values for each quadrature
      * point.
      *
-     * We store the gradients in
-     * the quadrature points on
-     * the unit cell. We then
-     * only have to apply the
-     * transformation (which is a
-     * matrix-vector
-     * multiplication) when
-     * visiting an actual cell.
+     * We store the gradients in the quadrature points on the unit cell. We
+     * then only have to apply the transformation (which is a matrix-vector
+     * multiplication) when visiting an actual cell.
      */
     std::vector<std::vector<Tensor<2, dim> > > shape_gradients;
   };
 
   /**
-   * These are the factors
-   * multiplied to a function in
-   * the
-   * #generalized_face_support_points
-   * when computing the
-   * integration.
-  *
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * These are the factors multiplied to a function in the
+   * #generalized_face_support_points when computing the integration.
+   *
+   * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+   * support points" for more information.
    */
   Table<2, double> boundary_weights;
 
@@ -454,8 +391,7 @@ private:
   mutable Threads::Mutex mutex;
 
   /**
-   * Allow access from other
-   * dimensions.
+   * Allow access from other dimensions.
    */
   template <int dim1> friend class FE_Nedelec;
 };
index e4ef19ccd408614109a959bb8cda00f78be62ea6..21624e675c3e8d1e133027205de147c117b61192 100644 (file)
@@ -35,16 +35,17 @@ DEAL_II_NAMESPACE_OPEN
  * FE_Nothing elements are used.  The hp::DoFHandler will therefore assign no
  * degrees of freedom to the FE_Nothing cells, and this subregion is therefore
  * implicitly deleted from the computation. step-46 shows a use case for this
- * element. An interesting application for this element is also presented in the
- * paper A. Cangiani, J. Chapman, E. Georgoulis, M. Jensen:
- * <b>Implementation of the Continuous-Discontinuous Galerkin Finite Element Method</b>,
- * arXiv:1201.2878v1 [math.NA], 2012 (see http://arxiv.org/abs/1201.2878).
+ * element. An interesting application for this element is also presented in
+ * the paper A. Cangiani, J. Chapman, E. Georgoulis, M. Jensen:
+ * <b>Implementation of the Continuous-Discontinuous Galerkin Finite Element
+ * Method</b>, arXiv:1201.2878v1 [math.NA], 2012 (see
+ * http://arxiv.org/abs/1201.2878).
  *
  * Note that some care must be taken that the resulting mesh topology
- * continues to make sense when FE_Nothing elements are introduced.
- * This is particularly true when dealing with hanging node constraints,
- * because the library makes some basic assumptions about the nature
- * of those constraints.  The following geometries are acceptable:
+ * continues to make sense when FE_Nothing elements are introduced. This is
+ * particularly true when dealing with hanging node constraints, because the
+ * library makes some basic assumptions about the nature of those constraints.
+ * The following geometries are acceptable:
  * @code
  * +---------+----+----+
  * |         | 0  |    |
@@ -59,11 +60,10 @@ DEAL_II_NAMESPACE_OPEN
  * |         | 1  |    |
  * +---------+----+----+
  * @endcode
- * Here, 0 denotes an FE_Nothing cell, and 1 denotes some other
- * element type.  The library has no difficulty computing the necessary
- * hanging node constraints in these cases (i.e. no constraint).
- * However, the following geometry is NOT acceptable (at least
- * in the current implementation):
+ * Here, 0 denotes an FE_Nothing cell, and 1 denotes some other element type.
+ * The library has no difficulty computing the necessary hanging node
+ * constraints in these cases (i.e. no constraint). However, the following
+ * geometry is NOT acceptable (at least in the current implementation):
  * @code
  * +---------+----+----+
  * |         | 0  |    |
@@ -71,8 +71,8 @@ DEAL_II_NAMESPACE_OPEN
  * |         | 1  |    |
  * +---------+----+----+
  * @endcode
- * The distinction lies in the mixed nature of the child faces,
- * a case we have not implemented as of yet.
+ * The distinction lies in the mixed nature of the child faces, a case we have
+ * not implemented as of yet.
  *
  * @author Joshua White, Wolfgang Bangerth
  */
@@ -82,60 +82,41 @@ class FE_Nothing : public FiniteElement<dim,spacedim>
 public:
 
   /**
-    * Constructor. Argument denotes the
-    * number of components to give this
-    * finite element (default = 1).
-    */
+   * Constructor. Argument denotes the number of components to give this
+   * finite element (default = 1).
+   */
   FE_Nothing (const unsigned int n_components = 1);
 
   /**
-   * A sort of virtual copy
-   * constructor. Some places in
-   * the library, for example the
-   * constructors of FESystem as
-   * well as the hp::FECollection
-   * class, need to make copied of
-   * finite elements without
-   * knowing their exact type. They
-   * do so through this function.
+   * A sort of virtual copy constructor. Some places in the library, for
+   * example the constructors of FESystem as well as the hp::FECollection
+   * class, need to make copied of finite elements without knowing their exact
+   * type. They do so through this function.
    */
   virtual
   FiniteElement<dim,spacedim> *
   clone() const;
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. In this case it is
-   * <code>FE_Nothing@<dim@></code>.
+   * Return a string that uniquely identifies a finite element. In this case
+   * it is <code>FE_Nothing@<dim@></code>.
    */
   virtual
   std::string
   get_name() const;
 
   /**
-   * Determine the values a finite
-   * element should compute on
-   * initialization of data for
-   * FEValues.
+   * Determine the values a finite element should compute on initialization of
+   * data for FEValues.
    *
-   * Given a set of flags
-   * indicating what quantities are
-   * requested from a FEValues
-   * object, update_once() and
-   * update_each() compute which
-   * values must really be
-   * computed. Then, the
-   * <tt>fill_*_values</tt> functions
-   * are called with the result of
-   * these.
+   * Given a set of flags indicating what quantities are requested from a
+   * FEValues object, update_once() and update_each() compute which values
+   * must really be computed. Then, the <tt>fill_*_values</tt> functions are
+   * called with the result of these.
    *
-   * In this case, since the element
-   * has zero degrees of freedom and
-   * no information can be computed on
-   * it, this function simply returns
-   * the default (empty) set of update
-   * flags.
+   * In this case, since the element has zero degrees of freedom and no
+   * information can be computed on it, this function simply returns the
+   * default (empty) set of update flags.
    */
 
   virtual
@@ -143,33 +124,23 @@ public:
   update_once (const UpdateFlags flags) const;
 
   /**
-   * Complementary function for
-   * update_once().
+   * Complementary function for update_once().
    *
-   * While update_once() returns
-   * the values to be computed on
-   * the unit cell for yielding the
-   * required data, this function
-   * determines the values that
-   * must be recomputed on each
-   * cell.
+   * While update_once() returns the values to be computed on the unit cell
+   * for yielding the required data, this function determines the values that
+   * must be recomputed on each cell.
    *
-   * Refer to update_once() for
-   * more details.
+   * Refer to update_once() for more details.
    */
   virtual
   UpdateFlags
   update_each (const UpdateFlags flags) const;
 
   /**
-   * Return the value of the
-   * @p ith shape function at the
-   * point @p p. @p p is a point
-   * on the reference element. Because the
-   * current element has no degrees of freedom,
-   * this function should obviously not be
-   * called in practice.  All this function
-   * really does, therefore, is trigger an
+   * Return the value of the @p ith shape function at the point @p p. @p p is
+   * a point on the reference element. Because the current element has no
+   * degrees of freedom, this function should obviously not be called in
+   * practice.  All this function really does, therefore, is trigger an
    * exception.
    */
   virtual
@@ -177,16 +148,11 @@ public:
   shape_value (const unsigned int i, const Point<dim> &p) const;
 
   /**
-   * Fill the fields of
-   * FEValues. This function
-   * performs all the operations
-   * needed to compute the data of an
-   * FEValues object.
+   * Fill the fields of FEValues. This function performs all the operations
+   * needed to compute the data of an FEValues object.
    *
-   * In the current case, this function
-   * returns no meaningful information,
-   * since the element has no degrees of
-   * freedom.
+   * In the current case, this function returns no meaningful information,
+   * since the element has no degrees of freedom.
    */
   virtual
   void
@@ -199,16 +165,11 @@ public:
                   CellSimilarity::Similarity &cell_similarity) const;
 
   /**
-   * Fill the fields of
-   * FEFaceValues. This function
-   * performs all the operations
-   * needed to compute the data of an
-   * FEFaceValues object.
+   * Fill the fields of FEFaceValues. This function performs all the
+   * operations needed to compute the data of an FEFaceValues object.
    *
-   * In the current case, this function
-   * returns no meaningful information,
-   * since the element has no degrees of
-   * freedom.
+   * In the current case, this function returns no meaningful information,
+   * since the element has no degrees of freedom.
    */
   virtual
   void
@@ -221,16 +182,11 @@ public:
                        FEValuesData<dim,spacedim> &data) const;
 
   /**
-   * Fill the fields of
-   * FESubFaceValues. This function
-   * performs all the operations
-   * needed to compute the data of an
-   * FESubFaceValues object.
+   * Fill the fields of FESubFaceValues. This function performs all the
+   * operations needed to compute the data of an FESubFaceValues object.
    *
-   * In the current case, this function
-   * returns no meaningful information,
-   * since the element has no degrees of
-   * freedom.
+   * In the current case, this function returns no meaningful information,
+   * since the element has no degrees of freedom.
    */
   virtual
   void
@@ -244,20 +200,13 @@ public:
                           FEValuesData<dim,spacedim> &data) const;
 
   /**
-   * Prepare internal data
-   * structures and fill in values
-   * independent of the
-   * cell. Returns a pointer to an
-   * object of which the caller of
-   * this function then has to
-   * assume ownership (which
-   * includes destruction when it
-   * is no more needed).
+   * Prepare internal data structures and fill in values independent of the
+   * cell. Returns a pointer to an object of which the caller of this function
+   * then has to assume ownership (which includes destruction when it is no
+   * more needed).
    *
-   * In the current case, this function
-   * just returns a default pointer, since
-   * no meaningful data exists for this
-   * element.
+   * In the current case, this function just returns a default pointer, since
+   * no meaningful data exists for this element.
    */
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
@@ -266,21 +215,15 @@ public:
             const Quadrature<dim> &quadrature) const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    *
-   * In the current case, this element
-   * is always assumed to dominate, unless
-   * it is also of type FE_Nothing().  In
-   * that situation, either element can
+   * In the current case, this element is always assumed to dominate, unless
+   * it is also of type FE_Nothing().  In that situation, either element can
    * dominate.
    */
   virtual
@@ -306,18 +249,13 @@ public:
   hp_constraints_are_implemented () const;
 
   /**
-  * Return the matrix
-  * interpolating from a face of
-  * of one element to the face of
-  * the neighboring element.
-  * The size of the matrix is
-  * then <tt>source.#dofs_per_face</tt> times
-  * <tt>this->#dofs_per_face</tt>.
-  *
-  * Since the current finite element has no
-  * degrees of freedom, the interpolation
-  * matrix is necessarily empty.
-  */
+   * Return the matrix interpolating from a face of of one element to the face
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
+   *
+   * Since the current finite element has no degrees of freedom, the
+   * interpolation matrix is necessarily empty.
+   */
 
   virtual
   void
@@ -326,17 +264,12 @@ public:
 
 
   /**
-   * Return the matrix
-   * interpolating from a face of
-   * of one element to the subface of
-   * the neighboring element.
-   * The size of the matrix is
-   * then <tt>source.#dofs_per_face</tt> times
-   * <tt>this->#dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of of one element to the
+   * subface of the neighboring element. The size of the matrix is then
+   * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
    *
-   * Since the current finite element has no
-   * degrees of freedom, the interpolation
-   * matrix is necessarily empty.
+   * Since the current finite element has no degrees of freedom, the
+   * interpolation matrix is necessarily empty.
    */
 
   virtual
index 40308866b76e9c55f7933e93fa67172da5773880..4e22673283f0c1ac892b6b6662acaf13d8064a6c 100644 (file)
@@ -29,8 +29,8 @@ DEAL_II_NAMESPACE_OPEN
  * FiniteElement classes based on polynomial spaces like the
  * TensorProductPolynomials or PolynomialSpace classes.
  *
- * Every class conforming to the following interface can be used as
- * template parameter POLY.
+ * Every class conforming to the following interface can be used as template
+ * parameter POLY.
  *
  * @code
  * static const unsigned int dimension;
@@ -47,24 +47,22 @@ DEAL_II_NAMESPACE_OPEN
  * Example classes are TensorProductPolynomials, PolynomialSpace or
  * PolynomialsP.
  *
- * This class is not a fully implemented FiniteElement class. Instead
- * there are several pure virtual functions declared in the
- * FiniteElement and FiniteElement classes which cannot
- * implemented by this class but are left for implementation in
- * derived classes.
+ * This class is not a fully implemented FiniteElement class. Instead there
+ * are several pure virtual functions declared in the FiniteElement and
+ * FiniteElement classes which cannot implemented by this class but are left
+ * for implementation in derived classes.
  *
- * Furthermore, this class assumes that shape functions of the
- * FiniteElement under consideration do <em>not</em> depend on the
- * actual shape of the cells in real space, i.e. update_once()
- * includes <tt>update_values</tt>. For FiniteElements whose shape
- * functions depend on the cells in real space, the update_once() and
- * update_each() functions must be overloaded.
+ * Furthermore, this class assumes that shape functions of the FiniteElement
+ * under consideration do <em>not</em> depend on the actual shape of the cells
+ * in real space, i.e. update_once() includes <tt>update_values</tt>. For
+ * FiniteElements whose shape functions depend on the cells in real space, the
+ * update_once() and update_each() functions must be overloaded.
  *
- * @todo Since nearly all functions for spacedim != dim are
- * specialized, this class needs cleaning up.
+ * @todo Since nearly all functions for spacedim != dim are specialized, this
+ * class needs cleaning up.
  *
  * @author Ralf Hartmann 2004, Guido Kanschat, 2009
- **/
+ */
 template <class POLY, int dim=POLY::dimension, int spacedim=dim>
 class FE_Poly : public FiniteElement<dim,spacedim>
 {
@@ -207,11 +205,11 @@ protected:
    * FiniteElement.
    *
    * This class assumes that shape functions of this FiniteElement do
-   * <em>not</em> depend on the actual shape of the cells in real
-   * space. Therefore, the effect in this element is as follows: if
-   * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the
-   * result. All other flags of the result are cleared, since everything else
-   * must be computed for each cell.
+   * <em>not</em> depend on the actual shape of the cells in real space.
+   * Therefore, the effect in this element is as follows: if
+   * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+   * All other flags of the result are cleared, since everything else must be
+   * computed for each cell.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
index f42f12e3ffce903202b52a6b3070d30dabef93e8..10f31fcc9e363fa24baaf24da11716f3cccc5fbd 100644 (file)
@@ -28,12 +28,12 @@ DEAL_II_NAMESPACE_OPEN
  * @warning This class is not sufficiently tested yet!
  *
  * This class gives a unified framework for the implementation of
- * FiniteElement classes only located on faces of the mesh. They are
- * based on polynomial spaces like the TensorProductPolynomials or a
- * PolynomialSpace classes.
+ * FiniteElement classes only located on faces of the mesh. They are based on
+ * polynomial spaces like the TensorProductPolynomials or a PolynomialSpace
+ * classes.
  *
- * Every class that implements the following functions can be used as
- * template parameter POLY.
+ * Every class that implements the following functions can be used as template
+ * parameter POLY.
  *
  * @code
  * double compute_value (const unsigned int i,
@@ -47,15 +47,14 @@ DEAL_II_NAMESPACE_OPEN
  * which cannot be implemented by this class but are left for implementation
  * in derived classes.
  *
- * Furthermore, this class assumes that shape functions of the
- * FiniteElement under consideration do <em>not</em> depend on the
- * actual shape of the cells in real space, i.e. update_once()
- * includes <tt>update_values</tt>. For FiniteElements whose shape
- * functions depend on the cells in real space, the update_once() and
- * update_each() functions must be overloaded.
+ * Furthermore, this class assumes that shape functions of the FiniteElement
+ * under consideration do <em>not</em> depend on the actual shape of the cells
+ * in real space, i.e. update_once() includes <tt>update_values</tt>. For
+ * FiniteElements whose shape functions depend on the cells in real space, the
+ * update_once() and update_each() functions must be overloaded.
  *
  * @author Guido Kanschat, 2009
- **/
+ */
 template <class POLY, int dim=POLY::dimension+1, int spacedim=dim>
 class FE_PolyFace : public FiniteElement<dim,spacedim>
 {
@@ -68,106 +67,72 @@ public:
                const std::vector<bool> &restriction_is_additive_flags);
 
   /**
-   * Return the polynomial degree
-   * of this finite element,
-   * i.e. the value passed to the
-   * constructor.
+   * Return the polynomial degree of this finite element, i.e. the value
+   * passed to the constructor.
    */
   unsigned int get_degree () const;
 
   /**
-   * Return the value of the
-   * <tt>i</tt>th shape function at
-   * the point <tt>p</tt>. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the value of the <tt>i</tt>th shape function at the point
+   * <tt>p</tt>. See the FiniteElement base class for more information about
+   * the semantics of this function.
    */
 //    virtual double shape_value (const unsigned int i,
 //                              const Point<dim> &p) const;
 
   /**
-   * Return the value of the
-   * <tt>component</tt>th vector
-   * component of the <tt>i</tt>th
-   * shape function at the point
-   * <tt>p</tt>. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the value of the <tt>component</tt>th vector component of the
+   * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+   * FiniteElement base class for more information about the semantics of this
+   * function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * <tt>_component</tt> suffix
-   * were called, provided that the
-   * specified component is zero.
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the <tt>_component</tt> suffix were called, provided
+   * that the specified component is zero.
    */
 //    virtual double shape_value_component (const unsigned int i,
 //                                        const Point<dim> &p,
 //                                        const unsigned int component) const;
 
   /**
-   * Return the gradient of the
-   * <tt>i</tt>th shape function at
-   * the point <tt>p</tt>. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the gradient of the <tt>i</tt>th shape function at the point
+   * <tt>p</tt>. See the FiniteElement base class for more information about
+   * the semantics of this function.
    */
 //    virtual Tensor<1,dim> shape_grad (const unsigned int  i,
 //                                    const Point<dim>   &p) const;
 
   /**
-   * Return the gradient of the
-   * <tt>component</tt>th vector
-   * component of the <tt>i</tt>th
-   * shape function at the point
-   * <tt>p</tt>. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the gradient of the <tt>component</tt>th vector component of the
+   * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+   * FiniteElement base class for more information about the semantics of this
+   * function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * <tt>_component</tt> suffix
-   * were called, provided that the
-   * specified component is zero.
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the <tt>_component</tt> suffix were called, provided
+   * that the specified component is zero.
    */
 //    virtual Tensor<1,dim> shape_grad_component (const unsigned int i,
 //                                              const Point<dim> &p,
 //                                              const unsigned int component) const;
 
   /**
-   * Return the tensor of second
-   * derivatives of the
-   * <tt>i</tt>th shape function at
-   * point <tt>p</tt> on the unit
-   * cell. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the tensor of second derivatives of the <tt>i</tt>th shape
+   * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
+   * class for more information about the semantics of this function.
    */
 //    virtual Tensor<2,dim> shape_grad_grad (const unsigned int  i,
 //                                         const Point<dim> &p) const;
 
   /**
-   * Return the second derivative
-   * of the <tt>component</tt>th
-   * vector component of the
-   * <tt>i</tt>th shape function at
-   * the point <tt>p</tt>. See the
-   * FiniteElement base class
-   * for more information about the
-   * semantics of this function.
+   * Return the second derivative of the <tt>component</tt>th vector component
+   * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+   * FiniteElement base class for more information about the semantics of this
+   * function.
    *
-   * Since this element is scalar,
-   * the returned value is the same
-   * as if the function without the
-   * <tt>_component</tt> suffix
-   * were called, provided that the
-   * specified component is zero.
+   * Since this element is scalar, the returned value is the same as if the
+   * function without the <tt>_component</tt> suffix were called, provided
+   * that the specified component is zero.
    */
 //    virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
 //                                                   const Point<dim> &p,
@@ -221,54 +186,32 @@ protected:
 
 
   /**
-   * Determine the values that need
-   * to be computed on the unit
-   * cell to be able to compute all
-   * values required by
-   * <tt>flags</tt>.
+   * Determine the values that need to be computed on the unit cell to be able
+   * to compute all values required by <tt>flags</tt>.
    *
-   * For the purpuse of this
-   * function, refer to the
-   * documentation in
+   * For the purpuse of this function, refer to the documentation in
    * FiniteElement.
    *
-   * This class assumes that shape
-   * functions of this
-   * FiniteElement do <em>not</em>
-   * depend on the actual shape of
-   * the cells in real
-   * space. Therefore, the effect
-   * in this element is as follows:
-   * if <tt>update_values</tt> is
-   * set in <tt>flags</tt>, copy it
-   * to the result. All other flags
-   * of the result are cleared,
-   * since everything else must be
+   * This class assumes that shape functions of this FiniteElement do
+   * <em>not</em> depend on the actual shape of the cells in real space.
+   * Therefore, the effect in this element is as follows: if
+   * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+   * All other flags of the result are cleared, since everything else must be
    * computed for each cell.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
   /**
-   * Determine the values that need
-   * to be computed on every cell
-   * to be able to compute all
-   * values required by
-   * <tt>flags</tt>.
+   * Determine the values that need to be computed on every cell to be able to
+   * compute all values required by <tt>flags</tt>.
    *
-   * For the purpuse of this
-   * function, refer to the
-   * documentation in
+   * For the purpuse of this function, refer to the documentation in
    * FiniteElement.
    *
-   * This class assumes that shape
-   * functions of this
-   * FiniteElement do <em>not</em>
-   * depend on the actual shape of
-   * the cells in real
-   * space.
+   * This class assumes that shape functions of this FiniteElement do
+   * <em>not</em> depend on the actual shape of the cells in real space.
    *
-   * The effect in this element is
-   * as follows:
+   * The effect in this element is as follows:
    * <ul>
    *
    * <li> if <tt>update_gradients</tt> is set, the result will contain
@@ -292,46 +235,30 @@ protected:
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points on one face. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
-     * point.
+     * Array with shape function values in quadrature points on one face.
+     * There is one row for each shape function, containing values for each
+     * quadrature point.
      *
-     * In this array, we store
-     * the values of the shape
-     * function in the quadrature
-     * points on one face of the unit
-     * cell. Since these values
-     * do not change under
-     * transformation to the real
-     * cell, we only need to copy
-     * them over when visiting a
-     * concrete cell.
+     * In this array, we store the values of the shape function in the
+     * quadrature points on one face of the unit cell. Since these values do
+     * not change under transformation to the real cell, we only need to copy
+     * them over when visiting a concrete cell.
      *
-     * In particular, we can
-     * simply copy the same set
-     * of values to each of the
+     * In particular, we can simply copy the same set of values to each of the
      * faces.
      */
     std::vector<std::vector<double> > shape_values;
   };
 
   /**
-   * The polynomial space. Its type
-   * is given by the template
-   * parameter POLY.
+   * The polynomial space. Its type is given by the template parameter POLY.
    */
   POLY poly_space;
 };
index b8171a5eaf2ab4a30854554741060c1ecc2c7bee..97aebd7a73a32b09c86945b5b573e2721712c911 100644 (file)
@@ -28,8 +28,8 @@ DEAL_II_NAMESPACE_OPEN
  * FiniteElement classes based on Tensor valued polynomial spaces like
  * PolynomialsBDM and PolynomialsRaviartThomas.
  *
- * Every class that implements following function can be used as
- * template parameter POLY.
+ * Every class that implements following function can be used as template
+ * parameter POLY.
  *
  * @code
  * void compute (const Point<dim>            &unit_point,
@@ -38,41 +38,38 @@ DEAL_II_NAMESPACE_OPEN
  *               std::vector<Tensor<3,dim> > &grad_grads) const;
  * @endcode
  *
- * In many cases, the node functionals depend on the shape of the mesh
- * cell, since they evaluate normal or tangential components on the
- * faces. In order to allow for a set of transformations, the variable
- * #mapping_type has been introduced. It should also be set in the
- * constructor of a derived class.
+ * In many cases, the node functionals depend on the shape of the mesh cell,
+ * since they evaluate normal or tangential components on the faces. In order
+ * to allow for a set of transformations, the variable #mapping_type has been
+ * introduced. It should also be set in the constructor of a derived class.
  *
- * This class is not a fully implemented FiniteElement class, but
- * implements some common features of vector valued elements based on
- * vector valued polynomial classes. What's missing here in particular
- * is information on the topological location of the node values.
+ * This class is not a fully implemented FiniteElement class, but implements
+ * some common features of vector valued elements based on vector valued
+ * polynomial classes. What's missing here in particular is information on the
+ * topological location of the node values.
  *
- * For more information on the template parameter <tt>spacedim</tt>,
- * see the documentation for the class Triangulation.
+ * For more information on the template parameter <tt>spacedim</tt>, see the
+ * documentation for the class Triangulation.
  *
  * <h3>Deriving classes</h3>
  *
  * Any derived class must decide on the polynomial space to use.  This
- * polynomial space should be implemented simply as a set of vector
- * valued polynomials like PolynomialsBDM and
- * PolynomialsRaviartThomas.  In order to facilitate this
- * implementation, the basis of this space may be arbitrary.
+ * polynomial space should be implemented simply as a set of vector valued
+ * polynomials like PolynomialsBDM and PolynomialsRaviartThomas.  In order to
+ * facilitate this implementation, the basis of this space may be arbitrary.
  *
  * <h4>Determining the correct basis</h4>
  *
- * In most cases, the set of desired node values $N_i$ and the basis
- * functions $v_j$ will not fulfill the interpolation condition
- * $N_i(v_j) = \delta_{ij}$.
+ * In most cases, the set of desired node values $N_i$ and the basis functions
+ * $v_j$ will not fulfill the interpolation condition $N_i(v_j) =
+ * \delta_{ij}$.
  *
- * The use of the member data #inverse_node_matrix allows to compute
- * the basis $v_j$ automatically, after the node values
- * for each original basis function of the polynomial space have been
- * computed.
+ * The use of the member data #inverse_node_matrix allows to compute the basis
+ * $v_j$ automatically, after the node values for each original basis function
+ * of the polynomial space have been computed.
  *
- * Therefore, the constructor of a derived class should have a
- * structure like this (example for interpolation in support points):
+ * Therefore, the constructor of a derived class should have a structure like
+ * this (example for interpolation in support points):
  *
  * @code
  *  fill_support_points();
@@ -94,18 +91,16 @@ DEAL_II_NAMESPACE_OPEN
  *  this->inverse_node_matrix.invert(N);
  * @endcode
  *
- * @note The matrix #inverse_node_matrix should have dimensions zero
- * before this piece of code is executed. Only then,
- * shape_value_component() will return the raw polynomial <i>j</i> as
- * defined in the polynomial space POLY.
+ * @note The matrix #inverse_node_matrix should have dimensions zero before
+ * this piece of code is executed. Only then, shape_value_component() will
+ * return the raw polynomial <i>j</i> as defined in the polynomial space POLY.
  *
  * <h4>Setting the transformation</h4>
  *
- * In most cases, vector valued basis functions must be transformed
- * when mapped from the reference cell to the actual grid cell. These
- * transformations can be selected from the set MappingType and stored
- * in #mapping_type. Therefore, each constructor should contain a line
- * like:
+ * In most cases, vector valued basis functions must be transformed when
+ * mapped from the reference cell to the actual grid cell. These
+ * transformations can be selected from the set MappingType and stored in
+ * #mapping_type. Therefore, each constructor should contain a line like:
  * @code
  * this->mapping_type = this->mapping_none;
  * @endcode
@@ -114,7 +109,7 @@ DEAL_II_NAMESPACE_OPEN
  * @ingroup febase
  * @author Guido Kanschat
  * @date 2005
- **/
+ */
 template <class POLY, int dim, int spacedim=dim>
 class FE_PolyTensor : public FiniteElement<dim,spacedim>
 {
@@ -122,9 +117,7 @@ public:
   /**
    * Constructor.
    *
-   * @arg @c degree: constructor
-   * argument for poly. May be
-   * different from @p
+   * @arg @c degree: constructor argument for poly. May be different from @p
    * fe_data.degree.
    */
   FE_PolyTensor (const unsigned int degree,
@@ -133,9 +126,7 @@ public:
                  const std::vector<ComponentMask> &nonzero_components);
 
   /**
-   * Since these elements are
-   * vector valued, an exception is
-   * thrown.
+   * Since these elements are vector valued, an exception is thrown.
    */
   virtual double shape_value (const unsigned int i,
                               const Point<dim> &p) const;
@@ -145,9 +136,7 @@ public:
                                         const unsigned int component) const;
 
   /**
-   * Since these elements are
-   * vector valued, an exception is
-   * thrown.
+   * Since these elements are vector valued, an exception is thrown.
    */
   virtual Tensor<1,dim> shape_grad (const unsigned int  i,
                                     const Point<dim>   &p) const;
@@ -157,9 +146,7 @@ public:
                                               const unsigned int component) const;
 
   /**
-   * Since these elements are
-   * vector valued, an exception is
-   * thrown.
+   * Since these elements are vector valued, an exception is thrown.
    */
   virtual Tensor<2,dim> shape_grad_grad (const unsigned int  i,
                                          const Point<dim> &p) const;
@@ -169,34 +156,22 @@ public:
                                                    const unsigned int component) const;
 
   /**
-   * Given <tt>flags</tt>,
-   * determines the values which
-   * must be computed only for the
-   * reference cell. Make sure,
-   * that #mapping_type is set by
-   * the derived class, such that
-   * this function can operate
-   * correctly.
+   * Given <tt>flags</tt>, determines the values which must be computed only
+   * for the reference cell. Make sure, that #mapping_type is set by the
+   * derived class, such that this function can operate correctly.
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
   /**
-   * Given <tt>flags</tt>,
-   * determines the values which
-   * must be computed in each cell
-   * cell. Make sure, that
-   * #mapping_type is set by the
-   * derived class, such that this
-   * function can operate
-   * correctly.
+   * Given <tt>flags</tt>, determines the values which must be computed in
+   * each cell cell. Make sure, that #mapping_type is set by the derived
+   * class, such that this function can operate correctly.
    */
   virtual UpdateFlags update_each (const UpdateFlags flags) const;
 
 protected:
   /**
-   * The mapping type to be used to
-   * map shape functions from the
-   * reference cell to the mesh
-   * cell.
+   * The mapping type to be used to map shape functions from the reference
+   * cell to the mesh cell.
    */
   MappingType mapping_type;
 
@@ -235,104 +210,68 @@ protected:
                           FEValuesData<dim,spacedim> &data) const ;
 
   /**
-   * Fields of cell-independent
-   * data for FE_PolyTensor. Stores
-   * the values of the shape
-   * functions and their
-   * derivatives on the reference
-   * cell for later use.
+   * Fields of cell-independent data for FE_PolyTensor. Stores the values of
+   * the shape functions and their derivatives on the reference cell for later
+   * use.
    *
-   * All tables are organized in a
-   * way, that the value for shape
-   * function <i>i</i> at
-   * quadrature point <i>k</i> is
-   * accessed by indices
+   * All tables are organized in a way, that the value for shape function
+   * <i>i</i> at quadrature point <i>k</i> is accessed by indices
    * <i>(i,k)</i>.
    */
   class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
-     * point.
+     * Array with shape function values in quadrature points. There is one row
+     * for each shape function, containing values for each quadrature point.
      */
     std::vector<std::vector<Tensor<1,dim> > > shape_values;
 
     /**
-     * Array with shape function
-     * gradients in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
+     * Array with shape function gradients in quadrature points. There is one
+     * row for each shape function, containing values for each quadrature
      * point.
      */
     std::vector< std::vector< DerivativeForm<1, dim, spacedim> > > shape_grads;
   };
 
   /**
-   * The polynomial space. Its type
-   * is given by the template
-   * parameter POLY.
+   * The polynomial space. Its type is given by the template parameter POLY.
    */
   POLY poly_space;
 
   /**
-   * The inverse of the matrix
-   * <i>a<sub>ij</sub></i> of node
-   * values <i>N<sub>i</sub></i>
-   * applied to polynomial
-   * <i>p<sub>j</sub></i>. This
-   * matrix is used to convert
-   * polynomials in the "raw" basis
-   * provided in #poly_space to the
-   * basis dual to the node
-   * functionals on the reference cell.
+   * The inverse of the matrix <i>a<sub>ij</sub></i> of node values
+   * <i>N<sub>i</sub></i> applied to polynomial <i>p<sub>j</sub></i>. This
+   * matrix is used to convert polynomials in the "raw" basis provided in
+   * #poly_space to the basis dual to the node functionals on the reference
+   * cell.
    *
-   * This object is not filled by
-   * FE_PolyTensor, but is a chance
-   * for a derived class to allow
-   * for reorganization of the
-   * basis functions. If it is left
-   * empty, the basis in
-   * #poly_space is used.
+   * This object is not filled by FE_PolyTensor, but is a chance for a derived
+   * class to allow for reorganization of the basis functions. If it is left
+   * empty, the basis in #poly_space is used.
    */
   FullMatrix<double> inverse_node_matrix;
 
   /**
-   * If a shape function is
-   * computed at a single point, we
-   * must compute all of them to
-   * apply #inverse_node_matrix. In
-   * order to avoid too much
-   * overhead, we cache the point
-   * and the function values for
-   * the next evaluation.
+   * If a shape function is computed at a single point, we must compute all of
+   * them to apply #inverse_node_matrix. In order to avoid too much overhead,
+   * we cache the point and the function values for the next evaluation.
    */
   mutable Point<dim> cached_point;
 
   /**
-   * Cached shape function values after
-   * call to
-   * shape_value_component().
+   * Cached shape function values after call to shape_value_component().
    */
   mutable std::vector<Tensor<1,dim> > cached_values;
 
   /**
-   * Cached shape function gradients after
-   * call to
-   * shape_grad_component().
+   * Cached shape function gradients after call to shape_grad_component().
    */
   mutable std::vector<Tensor<2,dim> > cached_grads;
 
   /**
-   * Cached second derivatives of
-   * shape functions after call to
+   * Cached second derivatives of shape functions after call to
    * shape_grad_grad_component().
    */
   mutable std::vector<Tensor<3,dim> > cached_grad_grads;
index 83a736fea6c95b2449d93abbe8a564e7198ba725..6a632bc960a7420e94a7ab9b46c63010c2261206 100644 (file)
@@ -34,11 +34,11 @@ DEAL_II_NAMESPACE_OPEN
  *
  * The standard constructor of this class takes the degree @p p of this finite
  * element. Alternatively, it can take a quadrature formula @p points defining
- * the support points of the Lagrange interpolation in one coordinate direction.
+ * the support points of the Lagrange interpolation in one coordinate
+ * direction.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * <h3>Implementation</h3>
  *
@@ -49,21 +49,20 @@ DEAL_II_NAMESPACE_OPEN
  * creates a TensorProductPolynomials object that includes the tensor product
  * of @p Lagrange polynomials with the support points from @p points.
  *
- * Furthermore the constructor fills the @p interface_constraints, the
- * @p prolongation (embedding) and the @p restriction matrices. These
- * are implemented only up to a certain degree and may not be
- * available for very high polynomial degree.
+ * Furthermore the constructor fills the @p interface_constraints, the @p
+ * prolongation (embedding) and the @p restriction matrices. These are
+ * implemented only up to a certain degree and may not be available for very
+ * high polynomial degree.
  *
  *
  * <h3>Numbering of the degrees of freedom (DoFs)</h3>
  *
  * The original ordering of the shape functions represented by the
- * TensorProductPolynomials is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. To be explicit, these numberings are listed in the
- * following:
+ * TensorProductPolynomials is a tensor product numbering. However, the shape
+ * functions on a cell are renumbered beginning with the shape functions whose
+ * support points are at the vertices, then on the line, on the quads, and
+ * finally (for 3d) on the hexes. To be explicit, these numberings are listed
+ * in the following:
  *
  * <h4>Q1 elements</h4>
  * <ul>
@@ -95,60 +94,38 @@ DEAL_II_NAMESPACE_OPEN
  *     0-------1        0-------1
  *   @endverbatim
  *
- *   The respective coordinate values of the support points of the shape
- *   functions are as follows:
- *   <ul>
- *   <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- *   <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- *   <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- *   <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- *   <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- *   <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- *   <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- *   <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- *   </ul>
+ * The respective coordinate values of the support points of the shape
+ * functions are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * </ul>
  * </ul>
  *
- * In 2d, these shape functions look as follows:
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_1$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_1$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_1$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_1$ element, shape function 3
- *     </td>
- *   </tr>
- * </table>
+ * In 2d, these shape functions look as follows: <table> <tr> <td
+ * align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_1$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_1$ element, shape function 3 </td> </tr> </table>
  *
  *
  * <h4>Q2 elements</h4>
@@ -191,138 +168,87 @@ DEAL_II_NAMESPACE_OPEN
  *     |/       /       |       |/
  *     *-------*        *-------*
  *   @endverbatim
- *   The center vertex has number 26.
- *
- *   The respective coordinate values of the support points of the shape
- *   functions are as follows:
- *   <ul>
- *   <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- *   <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- *   <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- *   <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- *   <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- *   <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- *   <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- *   <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- *   <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
- *   <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
- *   <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
- *   <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
- *   <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
- *   <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
- *   <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
- *   <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
- *   <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
- *   <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
- *   <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
- *   <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
- *   <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
- *   <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
- *   <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
- *   <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
- *   <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
- *   <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
- *   <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
- *   </ul>
+ * The center vertex has number 26.
+ *
+ * The respective coordinate values of the support points of the shape
+ * functions are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
  * </ul>
  *
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_2$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_2$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_2$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_2$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_2$ element,
+ * shape function 8 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
  *
  *
  * <h4>Q3 elements</h4>
@@ -345,160 +271,78 @@ DEAL_II_NAMESPACE_OPEN
  * </ul>
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0009.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 9
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0010.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0011.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 10
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 11
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0012.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0013.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 12
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 13
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0014.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0015.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3$ element, shape function 14
- *     </td>
- *
- *     <td align="center">
- *       $Q_3$ element, shape function 15
- *     </td>
- *   </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 15 </td> </tr> </table>
  *
  *
  * <h4>Q4 elements</h4>
@@ -523,257 +367,128 @@ DEAL_II_NAMESPACE_OPEN
  * </ul>
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0009.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 9
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0010.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0011.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 10
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 11
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0012.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0013.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 12
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 13
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0014.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0015.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 14
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 15
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0016.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0017.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 16
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 17
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0018.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0019.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 18
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 19
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0020.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0021.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 20
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 21
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0022.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0023.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 22
- *     </td>
- *
- *     <td align="center">
- *       $Q_4$ element, shape function 23
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0024.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4$ element, shape function 24
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- * </table>
- *
- *
- *
- * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann, 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008; Martin Kronbichler, 2008
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 15 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0016.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0017.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 16 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 17 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0018.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0019.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 18 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 19 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0020.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0021.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 20 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 21 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0022.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0023.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 22 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 23 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0024.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_4$ element,
+ * shape function 24 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
+ *
+ *
+ *
+ * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann,
+ * 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008;
+ * Martin Kronbichler, 2008
  */
 template <int dim, int spacedim=dim>
 class FE_Q : public FE_Q_Base<TensorProductPolynomials<dim>,dim,spacedim>
index 8bab2a6932620d3837a2fe152bd759916e47cc81..61165e8fad7d5c22d6c0d6c3c4d461f82a23ca39 100644 (file)
@@ -28,10 +28,12 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * This class collects the basic methods used in FE_Q and FE_Q_DG0. There is
- * no public constructor for this class as it is not functional as a
- * stand-alone. The completion of definitions is left to the derived classes.
+ * no public constructor for this class as it is not functional as a stand-
+ * alone. The completion of definitions is left to the derived classes.
  *
- * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann, 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008; Martin Kronbichler, 2008, 2013
+ * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann,
+ * 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008;
+ * Martin Kronbichler, 2008, 2013
  */
 template <class POLY, int dim=POLY::dimension, int spacedim=dim>
 class FE_Q_Base : public FE_Poly<POLY,dim,spacedim>
@@ -154,10 +156,10 @@ public:
    *
    * To explain the concept, consider the case where we would like to know
    * whether a degree of freedom on a face, for example as part of an FESystem
-   * element, is primitive. Unfortunately, the
-   * is_primitive() function in the FiniteElement class takes a cell index, so
-   * we would need to find the cell index of the shape function that
-   * corresponds to the present face index. This function does that.
+   * element, is primitive. Unfortunately, the is_primitive() function in the
+   * FiniteElement class takes a cell index, so we would need to find the cell
+   * index of the shape function that corresponds to the present face index.
+   * This function does that.
    *
    * Code implementing this would then look like this:
    * @code
@@ -169,19 +171,18 @@ public:
    * actual faces can be in their standard ordering with respect to the cell
    * under consideration, or can be flipped, oriented, etc.
    *
-   * @param face_dof_index The index of the degree of freedom on a face.
-   *   This index must be between zero and dofs_per_face.
-   * @param face The number of the face this degree of freedom lives on.
-   *   This number must be between zero and GeometryInfo::faces_per_cell.
-   * @param face_orientation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_flip One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_rotation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @return The index of this degree of freedom within the set
-   *   of degrees of freedom on the entire cell. The returned value
-   *   will be between zero and dofs_per_cell.
+   * @param face_dof_index The index of the degree of freedom on a face. This
+   * index must be between zero and dofs_per_face.
+   * @param face The number of the face this degree of freedom lives on. This
+   * number must be between zero and GeometryInfo::faces_per_cell.
+   * @param face_orientation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation .
+   * @param face_flip One part of the description of the orientation of the
+   * face. See @ref GlossFaceOrientation .
+   * @param face_rotation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation . @return The index of this
+   * degree of freedom within the set of degrees of freedom on the entire
+   * cell. The returned value will be between zero and dofs_per_cell.
    */
   virtual
   unsigned int face_to_cell_index (const unsigned int face_dof_index,
@@ -213,37 +214,35 @@ public:
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
@@ -285,15 +284,15 @@ protected:
   void initialize_constraints (const std::vector<Point<1> > &points);
 
   /**
-  * Initialize the @p unit_support_points field of the FiniteElement
-  * class. Called from initialize().
-  */
+   * Initialize the @p unit_support_points field of the FiniteElement class.
+   * Called from initialize().
+   */
   void initialize_unit_support_points (const std::vector<Point<1> > &points);
 
   /**
-  * Initialize the @p unit_face_support_points field of the FiniteElement
-  * class. Called from initialize().
-  */
+   * Initialize the @p unit_face_support_points field of the FiniteElement
+   * class. Called from initialize().
+   */
   void initialize_unit_face_support_points (const std::vector<Point<1> > &points);
 
   /**
index e377c0e1df78db5ad769909b15fcda9c53da9fb9..fe5014e47b0e223064a7b85baefba401c4215850 100644 (file)
@@ -28,28 +28,29 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Implementation of a scalar Lagrange finite element @p Qp+DG0 that yields the
- * finite element space of continuous, piecewise polynomials of degree @p p in
- * each coordinate direction plus the space of locally constant functions.
- * This class is realized using tensor product polynomials based on equidistant
- * or given support points.
+ * Implementation of a scalar Lagrange finite element @p Qp+DG0 that yields
+ * the finite element space of continuous, piecewise polynomials of degree @p
+ * p in each coordinate direction plus the space of locally constant
+ * functions. This class is realized using tensor product polynomials based on
+ * equidistant or given support points.
  *
  * The standard constructor of this class takes the degree @p p of this finite
  * element. Alternatively, it can take a quadrature formula @p points defining
- * the support points of the Lagrange interpolation in one coordinate direction.
+ * the support points of the Lagrange interpolation in one coordinate
+ * direction.
  *
  * For more information about the <tt>spacedim</tt> template parameter check
  * the documentation of FiniteElement or the one of Triangulation.
  *
- * For more information regarding this element see:
- * Boffi, D., et al. "Local Mass Conservation of Stokes Finite Elements."
- * Journal of Scientific Computing (2012): 1-18.
+ * For more information regarding this element see: Boffi, D., et al. "Local
+ * Mass Conservation of Stokes Finite Elements." Journal of Scientific
+ * Computing (2012): 1-18.
  *
  * <h3>Implementation</h3>
  *
  * The constructor creates a TensorProductPolynomials object that includes the
- * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus the
- * locally constant function. This @p TensorProductPolynomialsConst object
+ * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus
+ * the locally constant function. This @p TensorProductPolynomialsConst object
  * provides all values and derivatives of the shape functions. In case a
  * quadrature rule is given, the constructor creates a
  * TensorProductPolynomialsConst object that includes the tensor product of @p
@@ -62,13 +63,12 @@ DEAL_II_NAMESPACE_OPEN
  * <h3>Numbering of the degrees of freedom (DoFs)</h3>
  *
  * The original ordering of the shape functions represented by the
- * TensorProductPolynomialsConst is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. Finally there is a support point for the discontinuous shape
- * function in the middle of the cell. To be explicit, these numberings are
- * listed in the following:
+ * TensorProductPolynomialsConst is a tensor product numbering. However, the
+ * shape functions on a cell are renumbered beginning with the shape functions
+ * whose support points are at the vertices, then on the line, on the quads,
+ * and finally (for 3d) on the hexes. Finally there is a support point for the
+ * discontinuous shape function in the middle of the cell. To be explicit,
+ * these numberings are listed in the following:
  *
  * <h4>Q1 elements</h4>
  * <ul>
@@ -100,19 +100,19 @@ DEAL_II_NAMESPACE_OPEN
  *     0-------1        0-------1
  *   @endverbatim
  *
- *   The respective coordinate values of the support points of the degrees
- *   of freedom are as follows:
- *   <ul>
- *   <li> Index 0: <tt>[ 0,  0, 0]</tt>;
- *   <li> Index 1: <tt>[ 1,  0, 0]</tt>;
- *   <li> Index 2: <tt>[ 0,  1, 0]</tt>;
- *   <li> Index 3: <tt>[ 1,  1, 0]</tt>;
- *   <li> Index 4: <tt>[ 0,  0, 1]</tt>;
- *   <li> Index 5: <tt>[ 1,  0, 1]</tt>;
- *   <li> Index 6: <tt>[ 0,  1, 1]</tt>;
- *   <li> Index 7: <tt>[ 1,  1, 1]</tt>;
- *   <li> Index 8: <tt>[1/2, 1/2, 1/2]</tt>;
- *   </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Index 0: <tt>[ 0,  0, 0]</tt>;
+ * <li> Index 1: <tt>[ 1,  0, 0]</tt>;
+ * <li> Index 2: <tt>[ 0,  1, 0]</tt>;
+ * <li> Index 3: <tt>[ 1,  1, 0]</tt>;
+ * <li> Index 4: <tt>[ 0,  0, 1]</tt>;
+ * <li> Index 5: <tt>[ 1,  0, 1]</tt>;
+ * <li> Index 6: <tt>[ 0,  1, 1]</tt>;
+ * <li> Index 7: <tt>[ 1,  1, 1]</tt>;
+ * <li> Index 8: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
  * </ul>
  * <h4>Q2 elements</h4>
  * <ul>
@@ -120,7 +120,7 @@ DEAL_II_NAMESPACE_OPEN
  *   @verbatim
  *      0---2---1
  *   @endverbatim
- *   Index 3 has the same coordinates as index 2
+ * Index 3 has the same coordinates as index 2
  *
  * <li> 2D case:
  *   @verbatim
@@ -130,7 +130,7 @@ DEAL_II_NAMESPACE_OPEN
  *      |       |
  *      0---6---1
  *   @endverbatim
- *   Index 9 has the same coordinates as index 2
+ * Index 9 has the same coordinates as index 2
  *
  * <li> 3D case:
  *   @verbatim
@@ -156,40 +156,40 @@ DEAL_II_NAMESPACE_OPEN
  *     |/       /       |       |/
  *     *-------*        *-------*
  *   @endverbatim
- *   The center vertices have number 26 and 27.
+ * The center vertices have number 26 and 27.
  *
- *   The respective coordinate values of the support points of the degrees
- *   of freedom are as follows:
- *   <ul>
- *   <li> Index 0: <tt>[0, 0, 0]</tt>;
- *   <li> Index 1: <tt>[1, 0, 0]</tt>;
- *   <li> Index 2: <tt>[0, 1, 0]</tt>;
- *   <li> Index 3: <tt>[1, 1, 0]</tt>;
- *   <li> Index 4: <tt>[0, 0, 1]</tt>;
- *   <li> Index 5: <tt>[1, 0, 1]</tt>;
- *   <li> Index 6: <tt>[0, 1, 1]</tt>;
- *   <li> Index 7: <tt>[1, 1, 1]</tt>;
- *   <li> Index 8: <tt>[0, 1/2, 0]</tt>;
- *   <li> Index 9: <tt>[1, 1/2, 0]</tt>;
- *   <li> Index 10: <tt>[1/2, 0, 0]</tt>;
- *   <li> Index 11: <tt>[1/2, 1, 0]</tt>;
- *   <li> Index 12: <tt>[0, 1/2, 1]</tt>;
- *   <li> Index 13: <tt>[1, 1/2, 1]</tt>;
- *   <li> Index 14: <tt>[1/2, 0, 1]</tt>;
- *   <li> Index 15: <tt>[1/2, 1, 1]</tt>;
- *   <li> Index 16: <tt>[0, 0, 1/2]</tt>;
- *   <li> Index 17: <tt>[1, 0, 1/2]</tt>;
- *   <li> Index 18: <tt>[0, 1, 1/2]</tt>;
- *   <li> Index 19: <tt>[1, 1, 1/2]</tt>;
- *   <li> Index 20: <tt>[0, 1/2, 1/2]</tt>;
- *   <li> Index 21: <tt>[1, 1/2, 1/2]</tt>;
- *   <li> Index 22: <tt>[1/2, 0, 1/2]</tt>;
- *   <li> Index 23: <tt>[1/2, 1, 1/2]</tt>;
- *   <li> Index 24: <tt>[1/2, 1/2, 0]</tt>;
- *   <li> Index 25: <tt>[1/2, 1/2, 1]</tt>;
- *   <li> Index 26: <tt>[1/2, 1/2, 1/2]</tt>;
- *   <li> Index 27: <tt>[1/2, 1/2, 1/2]</tt>;
- *   </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Index 0: <tt>[0, 0, 0]</tt>;
+ * <li> Index 1: <tt>[1, 0, 0]</tt>;
+ * <li> Index 2: <tt>[0, 1, 0]</tt>;
+ * <li> Index 3: <tt>[1, 1, 0]</tt>;
+ * <li> Index 4: <tt>[0, 0, 1]</tt>;
+ * <li> Index 5: <tt>[1, 0, 1]</tt>;
+ * <li> Index 6: <tt>[0, 1, 1]</tt>;
+ * <li> Index 7: <tt>[1, 1, 1]</tt>;
+ * <li> Index 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Index 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Index 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Index 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Index 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Index 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Index 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Index 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Index 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Index 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Index 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Index 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Index 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Index 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Index 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Index 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Index 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Index 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Index 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * <li> Index 27: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
  * </ul>
  * <h4>Q3 elements</h4>
  * <ul>
@@ -215,7 +215,7 @@ DEAL_II_NAMESPACE_OPEN
  *   @verbatim
  *      0--2--3--4--1
  *   @endverbatim
- *   Index 5 has the same coordinates as index 3
+ * Index 5 has the same coordinates as index 3
  *
  * <li> 2D case:
  *   @verbatim
@@ -229,7 +229,7 @@ DEAL_II_NAMESPACE_OPEN
  *      |           |
  *      0--10-11-12-1
  *   @endverbatim
- *   Index 21 has the same coordinates as index 20
+ * Index 21 has the same coordinates as index 20
  * </ul>
  *
  */
@@ -327,8 +327,8 @@ protected:
 private:
 
   /**
-   * Returns the restriction_is_additive flags.
-   * Only the last component is true.
+   * Returns the restriction_is_additive flags. Only the last component is
+   * true.
    */
   static std::vector<bool> get_riaf_vector(const unsigned int degree);
 
index da7030bd82e01981be2730503d32dfe795b04bc6..96d15f165605bc78ca8baa57edc831915f4dc454 100644 (file)
@@ -29,53 +29,50 @@ template <int dim, int spacedim> class MappingQ;
 /*@{*/
 
 /**
- * Implementation of Hierarchical finite elements @p Qp that yield the
- * finite element space of continuous, piecewise polynomials of degree
- * @p p. This class is realized using tensor product polynomials
- * based on a hierarchical basis @p Hierarchical on the interval
- * <tt>[0,1]</tt> which is suitable for building an @p hp tensor product
- * finite element, if we assume that each element has a single degree.
- *
- * There are not many differences between @p FE_Q_Hierarchical and
- * @p FE_Q, except that we add a function @p embedding_dofs that takes
- * a given integer @p q, between @p 1 and @p p, and
- * returns the numbering of basis functions of the element of order
- * @p q in basis of order @p p.  This function is
- * useful if one wants to make calculations using the hierarchical
- * nature of these shape functions.
+ * Implementation of Hierarchical finite elements @p Qp that yield the finite
+ * element space of continuous, piecewise polynomials of degree @p p. This
+ * class is realized using tensor product polynomials based on a hierarchical
+ * basis @p Hierarchical on the interval <tt>[0,1]</tt> which is suitable for
+ * building an @p hp tensor product finite element, if we assume that each
+ * element has a single degree.
+ *
+ * There are not many differences between @p FE_Q_Hierarchical and @p FE_Q,
+ * except that we add a function @p embedding_dofs that takes a given integer
+ * @p q, between @p 1 and @p p, and returns the numbering of basis functions
+ * of the element of order @p q in basis of order @p p.  This function is
+ * useful if one wants to make calculations using the hierarchical nature of
+ * these shape functions.
  *
  * The unit support points now are reduced to @p 0, @p 1, and <tt>0.5</tt> in
  * one dimension, and tensor products in higher dimensions. Thus, various
  * interpolation functions will only work correctly for the linear case.
  *
- * The constructor of this class takes the degree @p p of this finite
- * element.
+ * The constructor of this class takes the degree @p p of this finite element.
  *
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
  *
  * <h3>Implementation</h3>
  *
- * The constructor creates a TensorProductPolynomials object
- * that includes the tensor product of @p Hierarchical
- * polynomials of degree @p p. This @p TensorProductPolynomials
- * object provides all values and derivatives of the shape functions.
+ * The constructor creates a TensorProductPolynomials object that includes the
+ * tensor product of @p Hierarchical polynomials of degree @p p. This @p
+ * TensorProductPolynomials object provides all values and derivatives of the
+ * shape functions.
  *
  * <h3>Numbering of the degrees of freedom (DoFs)</h3>
  *
  * The original ordering of the shape functions represented by the
- * TensorProductPolynomials is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. To be explicit, these numberings are listed in the
- * following:
+ * TensorProductPolynomials is a tensor product numbering. However, the shape
+ * functions on a cell are renumbered beginning with the shape functions whose
+ * support points are at the vertices, then on the line, on the quads, and
+ * finally (for 3d) on the hexes. To be explicit, these numberings are listed
+ * in the following:
  *
  * <h4>Q1 elements</h4>
  *
- * The $Q_1^H$ element is of polynomial degree one and, consequently,
- * is exactly the same as the $Q_1$ element in class FE_Q. In particular,
- * the shape function are defined in the exact same way:
+ * The $Q_1^H$ element is of polynomial degree one and, consequently, is
+ * exactly the same as the $Q_1$ element in class FE_Q. In particular, the
+ * shape function are defined in the exact same way:
  *
  * <ul>
  * <li> 1D case:
@@ -106,60 +103,38 @@ template <int dim, int spacedim> class MappingQ;
  *     0-------1        0-------1
  *   @endverbatim
  *
- *   The respective coordinate values of the support points of the degrees
- *   of freedom are as follows:
- *   <ul>
- *   <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- *   <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- *   <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- *   <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- *   <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- *   <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- *   <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- *   <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- *   </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * </ul>
  * </ul>
  *
- * In 2d, these shape functions look as follows:
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_1^H$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_1^H$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_1^H$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_1^H$ element, shape function 3
- *     </td>
- *   </tr>
- * </table>
+ * In 2d, these shape functions look as follows: <table> <tr> <td
+ * align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_1^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_1^H$ element, shape function 3 </td> </tr> </table>
  *
  *
  * <h4>Q2 elements</h4>
@@ -202,138 +177,87 @@ template <int dim, int spacedim> class MappingQ;
  *     |/       /       |       |/
  *     *-------*        *-------*
  *   @endverbatim
- *   The center vertex has number 26.
- *
- *   The respective coordinate values of the support points of the degrees
- *   of freedom are as follows:
- *   <ul>
- *   <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- *   <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- *   <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- *   <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- *   <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- *   <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- *   <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- *   <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- *   <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
- *   <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
- *   <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
- *   <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
- *   <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
- *   <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
- *   <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
- *   <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
- *   <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
- *   <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
- *   <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
- *   <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
- *   <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
- *   <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
- *   <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
- *   <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
- *   <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
- *   <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
- *   <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
- *   </ul>
+ * The center vertex has number 26.
+ *
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
  * </ul>
  *
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2^H$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_2^H$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2^H$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_2^H$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2^H$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_2^H$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2^H$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_2^H$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_2^H$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_2^H$ element,
+ * shape function 8 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
  *
  *
  * <h4>Q3 elements</h4>
@@ -356,160 +280,78 @@ template <int dim, int spacedim> class MappingQ;
  * </ul>
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0009.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 9
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0010.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0011.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 10
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 11
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0012.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0013.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 12
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 13
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0014.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0015.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_3^H$ element, shape function 14
- *     </td>
- *
- *     <td align="center">
- *       $Q_3^H$ element, shape function 15
- *     </td>
- *   </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 15 </td> </tr> </table>
  *
  *
  * <h4>Q4 elements</h4>
@@ -534,253 +376,122 @@ template <int dim, int spacedim> class MappingQ;
  * </ul>
  *
  * In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0000.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0001.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 0
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 1
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0002.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0003.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 2
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 3
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0004.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0005.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 4
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 5
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0006.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0007.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 6
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 7
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0008.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0009.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 8
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 9
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0010.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0011.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 10
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 11
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0012.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0013.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 12
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 13
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0014.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0015.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 14
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 15
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0016.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0017.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 16
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 17
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0018.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0019.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 18
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 19
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0020.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0021.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 20
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 21
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0022.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0023.png" alt="">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 22
- *     </td>
- *
- *     <td align="center">
- *       $Q_4^H$ element, shape function 23
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td align="center">
- *       <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0024.png" alt="">
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- *   <tr>
- *     <td align="center">
- *       $Q_4^H$ element, shape function 24
- *     </td>
- *
- *     <td align="center">
- *     </td>
- *   </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 15 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0016.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0017.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 16 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 17 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0018.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0019.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 18 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 19 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0020.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0021.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 20 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 21 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0022.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0023.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 22 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 23 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0024.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_4^H$ element,
+ * shape function 24 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
  *
  *
  *
@@ -791,19 +502,14 @@ class FE_Q_Hierarchical : public FE_Poly<TensorProductPolynomials<dim>,dim>
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials of degree @p p.
+   * Constructor for tensor product polynomials of degree @p p.
    */
   FE_Q_Hierarchical (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_Q_Hierarchical<dim>(degree)</tt>,
-   * with @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_Q_Hierarchical<dim>(degree)</tt>, with @p dim and @p
+   * degree replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -820,36 +526,29 @@ public:
    */
 
   /**
-   * Return whether this element
-   * implements its hanging node
-   * constraints in the new way,
-                   * which has to be used to make
-                   * elements "hp compatible".
-                   *
-                   * For the FE_Q_Hierarchical class the
-                   * result is always true (independent of
-                   * the degree of the element), as it
-                   * implements the complete set of
-                   * functions necessary for hp capability.
+   * Return whether this element implements its hanging node constraints in
+   * the new way, which has to be used to make elements "hp compatible".
+   *
+   * For the FE_Q_Hierarchical class the result is always true (independent of
+   * the degree of the element), as it implements the complete set of
+   * functions necessary for hp capability.
    */
   virtual bool hp_constraints_are_implemented () const;
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
@@ -858,45 +557,37 @@ public:
   /*@}*/
 
   /**
-   * Return the matrix interpolating from a face of one
-   * element to the face of the neighboring element. The
-   * size of the matrix is then <tt>source.dofs_per_face</tt>
-   * times <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of one element to the face of
+   * the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to implement this function.
-   * They may only provide interpolation matrices for certain
-   * source finite elements, for example those from the same
-   * family. If they don't implement interpolation from a given
-   * element, then they must throw an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * <tt>FiniteElement<dim>::ExcInterpolationNotImplemented</tt>.
    */
   virtual void get_face_interpolation_matrix (const FiniteElement<dim> &source, FullMatrix<double> &matrix) const;
 
   /**
-   * Return the matrix interpolating from a face of one element
-   * to the subface of the neighboring element. The size of
-   * the matrix is then <tt>source.dofs_per_face</tt> times
-   * <tt>this->dofs_per_face</tt>.
+   * Return the matrix interpolating from a face of one element to the subface
+   * of the neighboring element. The size of the matrix is then
+   * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
    *
-   * Derived elements will have to implement this function.
-   * They may only provide interpolation matrices for certain
-   * source finite elements, for example those from the same
-   * family. If they don't implement interpolation from a given
-   * element, then they must throw an exception of type
+   * Derived elements will have to implement this function. They may only
+   * provide interpolation matrices for certain source finite elements, for
+   * example those from the same family. If they don't implement interpolation
+   * from a given element, then they must throw an exception of type
    * <tt>ExcInterpolationNotImplemented</tt>.
    */
   virtual void get_subface_interpolation_matrix (const FiniteElement<dim> &source, const unsigned int subface, FullMatrix<double> &matrix) const;
 
   /**
-   * Return whether this element dominates
-   * the one given as argument when they
-   * meet at a common face,
-   * whether it is the other way around,
-   * whether neither dominates, or if
-   * either could dominate.
+   * Return whether this element dominates the one given as argument when they
+   * meet at a common face, whether it is the other way around, whether
+   * neither dominates, or if either could dominate.
    *
-   * For a definition of domination, see
-   * FiniteElementBase::Domination and in
+   * For a definition of domination, see FiniteElementBase::Domination and in
    * particular the @ref hp_paper "hp paper".
    */
   virtual
@@ -904,24 +595,18 @@ public:
   compare_for_face_domination (const FiniteElement<dim> &fe_other) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual,
-   * since finite element objects
-   * are usually accessed through
-   * pointers to their base class,
-   * rather than the class itself.
+   * This function is made virtual, since finite element objects are usually
+   * accessed through pointers to their base class, rather than the class
+   * itself.
    */
   virtual std::size_t memory_consumption () const;
 
   /**
-   * For a finite element of degree
-   * @p sub_degree < @p degree, we
-   * return a vector which maps the
-   * numbering on an FE
-   * of degree @p sub_degree into the
+   * For a finite element of degree @p sub_degree < @p degree, we return a
+   * vector which maps the numbering on an FE of degree @p sub_degree into the
    * numbering on this element.
    */
   std::vector<unsigned int> get_embedding_dofs (const unsigned int sub_degree) const;
@@ -936,81 +621,47 @@ public:
 
 protected:
   /**
-   * @p clone function instead of
-   * a copy constructor.
+   * @p clone function instead of a copy constructor.
    *
-   * This function is needed by the
-   * constructors of @p FESystem.
+   * This function is needed by the constructors of @p FESystem.
    */
   virtual FiniteElement<dim> *clone() const;
 
 private:
 
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int> get_dpo_vector(const unsigned int degree);
 
   /**
-   * The numbering of the degrees
-   * of freedom in continuous finite
-   * elements is hierarchic,
-   * i.e. in such a way that we
-   * first number the vertex dofs,
-   * in the order of the vertices
-   * as defined by the
-   * triangulation, then the line
-   * dofs in the order and
-   * respecting the direction of
-   * the lines, then the dofs on
-   * quads, etc.
+   * The numbering of the degrees of freedom in continuous finite elements is
+   * hierarchic, i.e. in such a way that we first number the vertex dofs, in
+   * the order of the vertices as defined by the triangulation, then the line
+   * dofs in the order and respecting the direction of the lines, then the
+   * dofs on quads, etc.
    *
-   * The dofs associated with 1d
-   * hierarchical polynomials are
-   * ordered with the vertices
-   * first ($phi_0(x)=1-x$ and
-   * $phi_1(x)=x$) and then the
-   * line dofs (the higher degree
-   * polynomials).  The 2d and 3d
-   * hierarchical polynomials
-   * originate from the 1d
-   * hierarchical polynomials by
-   * tensor product. In the
-   * following, the resulting
-   * numbering of dofs will be
-   * denoted by `fe_q_hierarchical
-   * numbering`.
+   * The dofs associated with 1d hierarchical polynomials are ordered with the
+   * vertices first ($phi_0(x)=1-x$ and $phi_1(x)=x$) and then the line dofs
+   * (the higher degree polynomials).  The 2d and 3d hierarchical polynomials
+   * originate from the 1d hierarchical polynomials by tensor product. In the
+   * following, the resulting numbering of dofs will be denoted by
+   * `fe_q_hierarchical numbering`.
    *
-   * This function constructs a
-   * table which fe_q_hierarchical
-   * index each degree of freedom
-   * in the hierarchic numbering
-   * would have.
+   * This function constructs a table which fe_q_hierarchical index each
+   * degree of freedom in the hierarchic numbering would have.
    *
-   * This function is anologous to
-   * the
-   * FETools::hierarchical_to_lexicographic_numbering()
-   * function. However, in contrast
-   * to the fe_q_hierarchical
-   * numbering defined above, the
-   * lexicographic numbering
-   * originates from the tensor
-   * products of consecutive
-   * numbered dofs (like for
-   * LagrangeEquidistant).
+   * This function is anologous to the
+   * FETools::hierarchical_to_lexicographic_numbering() function. However, in
+   * contrast to the fe_q_hierarchical numbering defined above, the
+   * lexicographic numbering originates from the tensor products of
+   * consecutive numbered dofs (like for LagrangeEquidistant).
    *
-   * It is assumed that the size of
-   * the output argument already
-   * matches the correct size,
-   * which is equal to the number
-   * of degrees of freedom in the
+   * It is assumed that the size of the output argument already matches the
+   * correct size, which is equal to the number of degrees of freedom in the
    * finite element.
    */
   static
@@ -1018,70 +669,53 @@ private:
     const FiniteElementData<dim> &fe);
 
   /**
-   * This is an analogon to the
-   * previous function, but working
-   * on faces.
+   * This is an analogon to the previous function, but working on faces.
    */
   static
   std::vector<unsigned int>
   face_fe_q_hierarchical_to_hierarchic_numbering (const unsigned int degree);
 
   /**
-   * Initialize two auxiliary
-   * fields that will be used in
-   * setting up the various
-   * matrices in the constructor.
+   * Initialize two auxiliary fields that will be used in setting up the
+   * various matrices in the constructor.
    */
   void build_dofs_cell (std::vector<FullMatrix<double> > &dofs_cell,
                         std::vector<FullMatrix<double> > &dofs_subcell) const;
 
   /**
-   * Initialize the hanging node
-   * constraints matrices. Called
-   * from the constructor.
+   * Initialize the hanging node constraints matrices. Called from the
+   * constructor.
    */
   void initialize_constraints (const std::vector<FullMatrix<double> > &dofs_subcell);
 
   /**
-   * Initialize the embedding
-   * matrices. Called from the
-   * constructor.
+   * Initialize the embedding matrices. Called from the constructor.
    */
   void initialize_embedding_and_restriction (const std::vector<FullMatrix<double> > &dofs_cell,
                                              const std::vector<FullMatrix<double> > &dofs_subcell);
 
   /**
-   * Initialize the
-   * @p unit_support_points field
-   * of the FiniteElement
-   * class. Called from the
-   * constructor.
+   * Initialize the @p unit_support_points field of the FiniteElement class.
+   * Called from the constructor.
    */
   void initialize_unit_support_points ();
 
   /**
-   * Initialize the
-   * @p unit_face_support_points field
-   * of the FiniteElement
-   * class. Called from the
-   * constructor.
+   * Initialize the @p unit_face_support_points field of the FiniteElement
+   * class. Called from the constructor.
    */
   void initialize_unit_face_support_points ();
 
   /**
-   * Mapping from lexicographic to
-   * shape function numbering on first face.
+   * Mapping from lexicographic to shape function numbering on first face.
    */
   const std::vector<unsigned int> face_renumber;
 
   /**
-   * Allow access from other
-   * dimensions. We need this since
-   * we want to call the functions
-   * @p get_dpo_vector and
-   * @p lexicographic_to_hierarchic_numbering
-   * for the faces of the finite
-   * element of dimension dim+1.
+   * Allow access from other dimensions. We need this since we want to call
+   * the functions @p get_dpo_vector and @p
+   * lexicographic_to_hierarchic_numbering for the faces of the finite element
+   * of dimension dim+1.
    */
   template <int dim1> friend class FE_Q_Hierarchical;
 };
index a1b6be0b0a008a79e2931ae1a96ebc1bca23dc6f..e01d09e3ddb30c9b1daad179a67f021fe54d8255 100644 (file)
@@ -33,8 +33,8 @@ DEAL_II_NAMESPACE_OPEN
  * with @p p subdivisions in each coordinate direction. It yields an element
  * with the same number of degrees of freedom as the @p Qp elements but using
  * linear interpolation instead of higher order one. This type of element is
- * also called macro element in the literature as it really consists of several
- * smaller elements, namely <i>p</i><tt><sup>dim</sup></tt>.
+ * also called macro element in the literature as it really consists of
+ * several smaller elements, namely <i>p</i><tt><sup>dim</sup></tt>.
  *
  * The numbering of degrees of freedom is done in exactly the same way as in
  * FE_Q of degree @p p. See there for a detailed description on how degrees of
@@ -67,19 +67,18 @@ DEAL_II_NAMESPACE_OPEN
  * not higher order elements. </li>
  *
  * <li> Stokes/Navier Stokes systems as the one discussed in step-22 could be
- * solved with Q2-iso-Q1 elements for velocities instead of Q2
- * elements. Combined with Q1 pressures they give a stable mixed element
- * pair. However, they perform worse than the standard approach in most
- * situations.  </li>
+ * solved with Q2-iso-Q1 elements for velocities instead of Q2 elements.
+ * Combined with Q1 pressures they give a stable mixed element pair. However,
+ * they perform worse than the standard approach in most situations.  </li>
  *
  * <li> Preconditioning systems of FE_Q systems of higher order @p p with a
  * preconditioner based on @p Qp-iso-Q1 elements: Some preconditioners like
- * algebraic multigrid perform much better with linear elements than with higher
- * order elements because they often implicitly assume a sparse connectivity
- * between entries. Then, creating a preconditioner matrix based on these
- * elements yields the same number of degrees of freedom (and a spectrally
- * equivalent linear system), which can be combined with a (high order) system
- * matrix in an iterative solver like CG.  </li>
+ * algebraic multigrid perform much better with linear elements than with
+ * higher order elements because they often implicitly assume a sparse
+ * connectivity between entries. Then, creating a preconditioner matrix based
+ * on these elements yields the same number of degrees of freedom (and a
+ * spectrally equivalent linear system), which can be combined with a (high
+ * order) system matrix in an iterative solver like CG.  </li>
  * </ol>
  *
  * <h3>Appropriate integration</h3>
index 72195f375d77e31fe3dd88e507b4de16005337c1..79b8f25551422856aa9c1fb03e27d81584d81ec5 100644 (file)
@@ -36,15 +36,15 @@ template <int dim, int spacedim> class MappingQ;
 /*@{*/
 
 /**
- * Implementation of Raviart-Thomas (RT) elements, conforming with the
- * space H<sup>div</sup>. These elements generate vector fields with
- * normal components continuous between mesh cells.
+ * Implementation of Raviart-Thomas (RT) elements, conforming with the space
+ * H<sup>div</sup>. These elements generate vector fields with normal
+ * components continuous between mesh cells.
  *
- * We follow the usual definition of the degree of RT elements, which
- * denotes the polynomial degree of the largest complete polynomial
- * subspace contained in the RT space. Then, approximation order of
- * the function itself is <i>degree+1</i>, as with usual polynomial
- * spaces. The numbering so chosen implies the sequence
+ * We follow the usual definition of the degree of RT elements, which denotes
+ * the polynomial degree of the largest complete polynomial subspace contained
+ * in the RT space. Then, approximation order of the function itself is
+ * <i>degree+1</i>, as with usual polynomial spaces. The numbering so chosen
+ * implies the sequence
  * @f[
  *   Q_{k+1}
  *   \stackrel{\text{grad}}{\rightarrow}
@@ -56,47 +56,46 @@ template <int dim, int spacedim> class MappingQ;
  * @f]
  * The lowest order element is consequently FE_RaviartThomas(0).
  *
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
  *
  * @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
  *
  * <h3>Interpolation</h3>
  *
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the RT element are constructed such that interpolation and
- * computing the divergence are commuting operations. We require this
- * from interpolating arbitrary functions as well as the #restriction
- * matrices.  It can be achieved by two interpolation schemes, the
- * simplified one in FE_RaviartThomasNodal and the original one here:
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * RT element are constructed such that interpolation and computing the
+ * divergence are commuting operations. We require this from interpolating
+ * arbitrary functions as well as the #restriction matrices.  It can be
+ * achieved by two interpolation schemes, the simplified one in
+ * FE_RaviartThomasNodal and the original one here:
  *
  * <h4>Node values on edges/faces</h4>
  *
- * On edges or faces, the @ref GlossNodes "node values" are the moments of
- * the normal component of the interpolated function with respect to
- * the traces of the RT polynomials. Since the normal trace of the RT
- * space of degree <i>k</i> on an edge/face is the space
- * <i>Q<sub>k</sub></i>, the moments are taken with respect to this
- * space.
+ * On edges or faces, the @ref GlossNodes "node values" are the moments of the
+ * normal component of the interpolated function with respect to the traces of
+ * the RT polynomials. Since the normal trace of the RT space of degree
+ * <i>k</i> on an edge/face is the space <i>Q<sub>k</sub></i>, the moments are
+ * taken with respect to this space.
  *
  * <h4>Interior node values</h4>
  *
- * Higher order RT spaces have interior nodes. These are moments taken
- * with respect to the gradient of functions in <i>Q<sub>k</sub></i>
- * on the cell (this space is the matching space for RT<sub>k</sub> in
- * a mixed formulation).
+ * Higher order RT spaces have interior nodes. These are moments taken with
+ * respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell
+ * (this space is the matching space for RT<sub>k</sub> in a mixed
+ * formulation).
  *
  * <h4>Generalized support points</h4>
  *
  * The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are thode of
- * QGauss<sub>k+1</sub> on each face as well as QGauss<sub>k</sub> in
- * the interior of the cell (or none for RT<sub>0</sub>).
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are thode of QGauss<sub>k+1</sub> on each face as well as
+ * QGauss<sub>k</sub> in the interior of the cell (or none for
+ * RT<sub>0</sub>).
  *
  *
  * @author Guido Kanschat, 2005, based on previous Work by Wolfgang Bangerth
@@ -108,19 +107,14 @@ class FE_RaviartThomas
 {
 public:
   /**
-   * Constructor for the Raviart-Thomas
-   * element of degree @p p.
+   * Constructor for the Raviart-Thomas element of degree @p p.
    */
   FE_RaviartThomas (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_RaviartThomas<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree
+   * replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -156,39 +150,25 @@ public:
 
 private:
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree);
 
   /**
-   * Initialize the @p
-   * generalized_support_points
-   * field of the FiniteElement
-   * class and fill the tables with
-   * interpolation weights
-   * (#boundary_weights and
-   * #interior_weights). Called
-   * from the constructor.
+   * Initialize the @p generalized_support_points field of the FiniteElement
+   * class and fill the tables with interpolation weights (#boundary_weights
+   * and #interior_weights). Called from the constructor.
    */
   void initialize_support_points (const unsigned int rt_degree);
 
   /**
-   * Initialize the interpolation
-   * from functions on refined mesh
-   * cells onto the father
-   * cell. According to the
-   * philosophy of the
-   * Raviart-Thomas element, this
-   * restriction operator preserves
-   * the divergence of a function
+   * Initialize the interpolation from functions on refined mesh cells onto
+   * the father cell. According to the philosophy of the Raviart-Thomas
+   * element, this restriction operator preserves the divergence of a function
    * weakly.
    */
   void initialize_restriction ();
@@ -196,93 +176,57 @@ private:
   /**
    * Fields of cell-independent data.
    *
-   * For information about the
-   * general purpose of this class,
-   * see the documentation of the
-   * base class.
+   * For information about the general purpose of this class, see the
+   * documentation of the base class.
    */
   class InternalData : public FiniteElement<dim>::InternalDataBase
   {
   public:
     /**
-     * Array with shape function
-     * values in quadrature
-     * points. There is one row
-     * for each shape function,
-     * containing values for each
-     * quadrature point. Since
-     * the shape functions are
-     * vector-valued (with as
-     * many components as there
-     * are space dimensions), the
-     * value is a tensor.
+     * Array with shape function values in quadrature points. There is one row
+     * for each shape function, containing values for each quadrature point.
+     * Since the shape functions are vector-valued (with as many components as
+     * there are space dimensions), the value is a tensor.
      *
-     * In this array, we store
-     * the values of the shape
-     * function in the quadrature
-     * points on the unit
-     * cell. The transformation
-     * to the real space cell is
-     * then simply done by
-     * multiplication with the
-     * Jacobian of the mapping.
+     * In this array, we store the values of the shape function in the
+     * quadrature points on the unit cell. The transformation to the real
+     * space cell is then simply done by multiplication with the Jacobian of
+     * the mapping.
      */
     std::vector<std::vector<Tensor<1,dim> > > shape_values;
 
     /**
-     * Array with shape function
-     * gradients in quadrature
-     * points. There is one
-     * row for each shape
-     * function, containing
-     * values for each quadrature
+     * Array with shape function gradients in quadrature points. There is one
+     * row for each shape function, containing values for each quadrature
      * point.
      *
-     * We store the gradients in
-     * the quadrature points on
-     * the unit cell. We then
-     * only have to apply the
-     * transformation (which is a
-     * matrix-vector
-     * multiplication) when
-     * visiting an actual cell.
+     * We store the gradients in the quadrature points on the unit cell. We
+     * then only have to apply the transformation (which is a matrix-vector
+     * multiplication) when visiting an actual cell.
      */
     std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
   };
 
   /**
-   * These are the factors
-   * multiplied to a function in
-   * the
-   * #generalized_face_support_points
-   * when computing the
-   * integration. They are
-   * organized such that there is
-   * one row for each generalized
-   * face support point and one
-   * column for each degree of
-   * freedom on the face.
-  *
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * These are the factors multiplied to a function in the
+   * #generalized_face_support_points when computing the integration. They are
+   * organized such that there is one row for each generalized face support
+   * point and one column for each degree of freedom on the face.
+   *
+   * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+   * support points" for more information.
    */
   Table<2, double> boundary_weights;
   /**
-   * Precomputed factors for
-   * interpolation of interior
-   * degrees of freedom. The
-   * rationale for this Table is
-   * the same as for
-   * #boundary_weights. Only, this
-   * table has a third coordinate
-   * for the space direction of the
-   * component evaluated.
+   * Precomputed factors for interpolation of interior degrees of freedom. The
+   * rationale for this Table is the same as for #boundary_weights. Only, this
+   * table has a third coordinate for the space direction of the component
+   * evaluated.
    */
   Table<3, double> interior_weights;
 
   /**
-   * Allow access from other
-   * dimensions.
+   * Allow access from other dimensions.
    */
   template <int dim1> friend class FE_RaviartThomas;
 };
@@ -290,44 +234,41 @@ private:
 
 
 /**
- * The Raviart-Thomas elements with node functionals defined as point
- * values in Gauss points.
+ * The Raviart-Thomas elements with node functionals defined as point values
+ * in Gauss points.
  *
  * <h3>Description of node values</h3>
  *
- * For this Raviart-Thomas element, the node values are not cell and
- * face moments with respect to certain polynomials, but the values in
- * quadrature points. Following the general scheme for numbering
- * degrees of freedom, the node values on edges are first, edge by
- * edge, according to the natural ordering of the edges of a cell. The
- * interior degrees of freedom are last.
+ * For this Raviart-Thomas element, the node values are not cell and face
+ * moments with respect to certain polynomials, but the values in quadrature
+ * points. Following the general scheme for numbering degrees of freedom, the
+ * node values on edges are first, edge by edge, according to the natural
+ * ordering of the edges of a cell. The interior degrees of freedom are last.
  *
- * For an RT-element of degree <i>k</i>, we choose
- * <i>(k+1)<sup>d-1</sup></i> Gauss points on each face. These points
- * are ordered lexicographically with respect to the orientation of
- * the face. This way, the normal component which is in
- * <i>Q<sub>k</sub></i> is uniquely determined. Furthermore, since
- * this Gauss-formula is exact on <i>Q<sub>2k+1</sub></i>, these node
- * values correspond to the exact integration of the moments of the
- * RT-space.
+ * For an RT-element of degree <i>k</i>, we choose <i>(k+1)<sup>d-1</sup></i>
+ * Gauss points on each face. These points are ordered lexicographically with
+ * respect to the orientation of the face. This way, the normal component
+ * which is in <i>Q<sub>k</sub></i> is uniquely determined. Furthermore, since
+ * this Gauss-formula is exact on <i>Q<sub>2k+1</sub></i>, these node values
+ * correspond to the exact integration of the moments of the RT-space.
  *
  * In the interior of the cells, the moments are with respect to an
- * anisotropic <i>Q<sub>k</sub></i> space, where the test functions
- * are one degree lower in the direction corresponding to the vector
- * component under consideration. This is emulated by using an
- * anisotropic Gauss formula for integration.
+ * anisotropic <i>Q<sub>k</sub></i> space, where the test functions are one
+ * degree lower in the direction corresponding to the vector component under
+ * consideration. This is emulated by using an anisotropic Gauss formula for
+ * integration.
  *
- * @todo The current implementation is for Cartesian meshes
- * only. You must use MappingCartesian.
+ * @todo The current implementation is for Cartesian meshes only. You must use
+ * MappingCartesian.
  *
  * @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
  *
  * @note The degree stored in the member variable
- * FiniteElementData<dim>::degree is higher by one than the
- * constructor argument!
+ * FiniteElementData<dim>::degree is higher by one than the constructor
+ * argument!
  *
  * @author Guido Kanschat, 2005, Zhu Liang, 2008
  */
@@ -338,19 +279,14 @@ class FE_RaviartThomasNodal
 {
 public:
   /**
-   * Constructor for the Raviart-Thomas
-   * element of degree @p p.
+   * Constructor for the Raviart-Thomas element of degree @p p.
    */
   FE_RaviartThomasNodal (const unsigned int p);
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with
-   * @p dim and @p degree
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with @p dim and @p
+   * degree replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -388,24 +324,17 @@ public:
 
 private:
   /**
-   * Only for internal use. Its
-   * full name is
-   * @p get_dofs_per_object_vector
-   * function and it creates the
-   * @p dofs_per_object vector that is
-   * needed within the constructor to
-   * be passed to the constructor of
-   * @p FiniteElementData.
+   * Only for internal use. Its full name is @p get_dofs_per_object_vector
+   * function and it creates the @p dofs_per_object vector that is needed
+   * within the constructor to be passed to the constructor of @p
+   * FiniteElementData.
    */
   static std::vector<unsigned int>
   get_dpo_vector (const unsigned int degree);
 
   /**
-   * Compute the vector used for
-   * the
-   * @p restriction_is_additive
-   * field passed to the base
-   * class's constructor.
+   * Compute the vector used for the @p restriction_is_additive field passed
+   * to the base class's constructor.
    */
   static std::vector<bool>
   get_ria_vector (const unsigned int degree);
@@ -414,22 +343,18 @@ private:
    * This function returns @p true, if the shape function @p shape_index has
    * non-zero function values somewhere on the face @p face_index.
    *
-   * Right now, this is only
-   * implemented for RT0 in
-   * 1D. Otherwise, returns always
-   * @p true.
+   * Right now, this is only implemented for RT0 in 1D. Otherwise, returns
+   * always @p true.
    */
   virtual bool has_support_on_face (const unsigned int shape_index,
                                     const unsigned int face_index) const;
   /**
-   * Initialize the
-   * FiniteElement<dim>::generalized_support_points
-   * and FiniteElement<dim>::generalized_face_support_points
-   * fields. Called from the
-   * constructor.
-  *
-  * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
-  * for more information.
+   * Initialize the FiniteElement<dim>::generalized_support_points and
+   * FiniteElement<dim>::generalized_face_support_points fields. Called from
+   * the constructor.
+   *
+   * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+   * support points" for more information.
    */
   void initialize_support_points (const unsigned int rt_degree);
 };
index cc629c6abc74bf3bccd04c28af2bfb1d2580f650..aea3e2d749294ae8a8b7499506483030691fd671 100644 (file)
@@ -40,18 +40,17 @@ DEAL_II_NAMESPACE_OPEN
  * <h3>FESystem, components and blocks</h3>
  *
  * An FESystem, except in the most trivial case, produces a vector-valued
- * finite element with several components. The number of components n_components()
- * corresponds to the dimension of the solution function in the PDE system,
- * and correspondingly also to the number of equations your PDE system
- * has. For example, the mixed Laplace system covered in step-20 has $d+1$
- * components in $d$ space dimensions: the scalar pressure and the $d$
+ * finite element with several components. The number of components
+ * n_components() corresponds to the dimension of the solution function in the
+ * PDE system, and correspondingly also to the number of equations your PDE
+ * system has. For example, the mixed Laplace system covered in step-20 has
+ * $d+1$ components in $d$ space dimensions: the scalar pressure and the $d$
  * components of the velocity vector. Similarly, the elasticity equation
  * covered in step-8 has $d$ components in $d$ space dimensions. In general,
- * the number of components of a FESystem element is the
- * accumulated number of components of all base elements times their
- * multiplicities. A bit more on
- * components is also given in the
- * @ref GlossComponent "glossary entry on components".
+ * the number of components of a FESystem element is the accumulated number of
+ * components of all base elements times their multiplicities. A bit more on
+ * components is also given in the @ref GlossComponent "glossary entry on
+ * components".
  *
  * While the concept of components is important from the viewpoint of a
  * partial differential equation, the finite element side looks a bit
@@ -61,11 +60,11 @@ DEAL_II_NAMESPACE_OPEN
  * freedom associated with a single base element of an FESystem, where base
  * elements with multiplicities count multiple times. These blocks are usually
  * addressed using the information in DoFHandler::block_info(). The number of
- * blocks of a FESystem object is simply the sum of all multiplicities of
- * base elements and is given by n_blocks().
+ * blocks of a FESystem object is simply the sum of all multiplicities of base
+ * elements and is given by n_blocks().
  *
- * For example, the FESystem for the Taylor-Hood element for the
- * three-dimensional Stokes problem can be built using the code
+ * For example, the FESystem for the Taylor-Hood element for the three-
+ * dimensional Stokes problem can be built using the code
  *
  * @code
  * FE_Q<3> u(2);
@@ -103,12 +102,12 @@ DEAL_II_NAMESPACE_OPEN
  * FESystem<3> sys3(u,1, p,1);
  * @endcode
  *
- * This example also produces a system with four components, but only
- * two blocks.
+ * This example also produces a system with four components, but only two
+ * blocks.
  *
- * In most cases, the composed element behaves as if it were a usual
- * element. It just has more degrees of freedom than most of the "common"
- * elements. However the underlying structure is visible in the restriction,
+ * In most cases, the composed element behaves as if it were a usual element.
+ * It just has more degrees of freedom than most of the "common" elements.
+ * However the underlying structure is visible in the restriction,
  * prolongation and interface constraint matrices, which do not couple the
  * degrees of freedom of the base elements. E.g. the continuity requirement is
  * imposed for the shape functions of the subobjects separately; no
@@ -122,34 +121,31 @@ DEAL_II_NAMESPACE_OPEN
  * <h3>Internal information on numbering of degrees of freedom</h3>
  *
  * The overall numbering of degrees of freedom is as follows: for each
- * subobject (vertex, line, quad, or hex), the degrees of freedom are
- * numbered such that we run over all subelements first, before
- * turning for the next dof on this subobject or for the next
- * subobject. For example, for an element of three components in one
- * space dimension, the first two components being cubic lagrange
- * elements and the third being a quadratic lagrange element, the
- * ordering for the system <tt>s=(u,v,p)</tt> is:
+ * subobject (vertex, line, quad, or hex), the degrees of freedom are numbered
+ * such that we run over all subelements first, before turning for the next
+ * dof on this subobject or for the next subobject. For example, for an
+ * element of three components in one space dimension, the first two
+ * components being cubic lagrange elements and the third being a quadratic
+ * lagrange element, the ordering for the system <tt>s=(u,v,p)</tt> is:
  *
  * <ul>
  * <li> First vertex: <tt>u0, v0, p0 = s0, s1, s2</tt>
  * <li> Second vertex: <tt>u1, v1, p1 = s3, s4, s5</tt>
- * <li> First component on the line:
- *   <tt>u2, u3 = s4, s5</tt>
- * <li> Second component on the line:
- *   <tt>v2, v3 = s6, s7</tt>.
- * <li> Third component on the line:
- *   <tt>p2 = s8</tt>.
+ * <li> First component on the line: <tt>u2, u3 = s4, s5</tt>
+ * <li> Second component on the line: <tt>v2, v3 = s6, s7</tt>.
+ * <li> Third component on the line: <tt>p2 = s8</tt>.
  * </ul>
  * That said, you should not rely on this numbering in your application as
  * these %internals might change in future. Rather use the functions
  * system_to_component_index() and component_to_system_index().
  *
- * For more information on the template parameter <tt>spacedim</tt>
- * see the documentation of Triangulation.
+ * For more information on the template parameter <tt>spacedim</tt> see the
+ * documentation of Triangulation.
  *
  * @ingroup febase fe vector_valued
  *
- * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2003, 2006, Ralf Hartmann 2001.
+ * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2003, 2006, Ralf
+ * Hartmann 2001.
  */
 template <int dim, int spacedim=dim>
 class FESystem : public FiniteElement<dim,spacedim>
@@ -296,8 +292,8 @@ public:
    * cell with respect to unit cell coordinates. Since this finite element is
    * always vector-valued, we return the value of the only non-zero component
    * of the vector value of this shape function. If the shape function has
-   * more than one non-zero component (which we refer to with the term
-   * non-primitive), then throw an exception of type @p
+   * more than one non-zero component (which we refer to with the term non-
+   * primitive), then throw an exception of type @p
    * ExcShapeFunctionNotPrimitive.
    *
    * An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
@@ -414,10 +410,10 @@ public:
    *
    * To explain the concept, consider the case where we would like to know
    * whether a degree of freedom on a face, for example as part of an FESystem
-   * element, is primitive. Unfortunately, the
-   * is_primitive() function in the FiniteElement class takes a cell index, so
-   * we would need to find the cell index of the shape function that
-   * corresponds to the present face index. This function does that.
+   * element, is primitive. Unfortunately, the is_primitive() function in the
+   * FiniteElement class takes a cell index, so we would need to find the cell
+   * index of the shape function that corresponds to the present face index.
+   * This function does that.
    *
    * Code implementing this would then look like this:
    * @code
@@ -429,19 +425,18 @@ public:
    * actual faces can be in their standard ordering with respect to the cell
    * under consideration, or can be flipped, oriented, etc.
    *
-   * @param face_dof_index The index of the degree of freedom on a face.
-   *   This index must be between zero and dofs_per_face.
-   * @param face The number of the face this degree of freedom lives on.
-   *   This number must be between zero and GeometryInfo::faces_per_cell.
-   * @param face_orientation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_flip One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @param face_rotation One part of the description of the orientation
-   *   of the face. See @ref GlossFaceOrientation .
-   * @return The index of this degree of freedom within the set
-   *   of degrees of freedom on the entire cell. The returned value
-   *   will be between zero and dofs_per_cell.
+   * @param face_dof_index The index of the degree of freedom on a face. This
+   * index must be between zero and dofs_per_face.
+   * @param face The number of the face this degree of freedom lives on. This
+   * number must be between zero and GeometryInfo::faces_per_cell.
+   * @param face_orientation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation .
+   * @param face_flip One part of the description of the orientation of the
+   * face. See @ref GlossFaceOrientation .
+   * @param face_rotation One part of the description of the orientation of
+   * the face. See @ref GlossFaceOrientation . @return The index of this
+   * degree of freedom within the set of degrees of freedom on the entire
+   * cell. The returned value will be between zero and dofs_per_cell.
    */
   virtual
   unsigned int face_to_cell_index (const unsigned int face_dof_index,
@@ -523,37 +518,35 @@ public:
                                     FullMatrix<double>       &matrix) const;
 
   /**
-   * If, on a vertex, several finite elements are active, the hp code
-   * first assigns the degrees of freedom of each of these FEs
-   * different global indices. It then calls this function to find out
-   * which of them should get identical values, and consequently can
-   * receive the same global DoF index. This function therefore
-   * returns a list of identities between DoFs of the present finite
-   * element object with the DoFs of @p fe_other, which is a reference
-   * to a finite element object representing one of the other finite
-   * elements active on this particular vertex. The function computes
-   * which of the degrees of freedom of the two finite element objects
-   * are equivalent, both numbered between zero and the corresponding
-   * value of dofs_per_vertex of the two finite elements. The first
-   * index of each pair denotes one of the vertex dofs of the present
-   * element, whereas the second is the corresponding index of the
-   * other finite element.
+   * If, on a vertex, several finite elements are active, the hp code first
+   * assigns the degrees of freedom of each of these FEs different global
+   * indices. It then calls this function to find out which of them should get
+   * identical values, and consequently can receive the same global DoF index.
+   * This function therefore returns a list of identities between DoFs of the
+   * present finite element object with the DoFs of @p fe_other, which is a
+   * reference to a finite element object representing one of the other finite
+   * elements active on this particular vertex. The function computes which of
+   * the degrees of freedom of the two finite element objects are equivalent,
+   * both numbered between zero and the corresponding value of dofs_per_vertex
+   * of the two finite elements. The first index of each pair denotes one of
+   * the vertex dofs of the present element, whereas the second is the
+   * corresponding index of the other finite element.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on lines.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on lines.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
   hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
 
   /**
-   * Same as hp_vertex_dof_indices(), except that the function treats
-   * degrees of freedom on quads.
+   * Same as hp_vertex_dof_indices(), except that the function treats degrees
+   * of freedom on quads.
    */
   virtual
   std::vector<std::pair<unsigned int, unsigned int> >
@@ -710,8 +703,8 @@ private:
 
 
   /**
-   * Initialize the @p unit_support_points field of the FiniteElement
-   * class. Called from the constructor.
+   * Initialize the @p unit_support_points field of the FiniteElement class.
+   * Called from the constructor.
    */
   void initialize_unit_support_points ();
 
@@ -803,7 +796,7 @@ private:
    * Compute the nonzero components of a list of finite elements with
    * multiplicities given in the second argument. This function is called from
    * all the above functions.
-  */
+   */
   static std::vector<ComponentMask>
   compute_nonzero_components (const std::vector<const FiniteElement<dim,spacedim>*> &fes,
                               const std::vector<unsigned int>              &multiplicities);
@@ -851,8 +844,8 @@ private:
   public:
     /**
      * Constructor. Is called by the @p get_data function. Sets the size of
-     * the @p base_fe_datas vector to @p n_base_elements and initializes
-     * the compute_hessians field.
+     * the @p base_fe_datas vector to @p n_base_elements and initializes the
+     * compute_hessians field.
      */
     InternalData (const unsigned int n_base_elements,
                   const bool         compute_hessians);
@@ -901,8 +894,8 @@ private:
      * pointing to. Sets <tt>fe_datas[base_no]</tt> to zero.
      *
      * This function is used to delete @p FEValuesData that are needed only on
-     * the first cell but not any more afterwards.  This is the case for
-     * e.g. Lagrangian elements (see e.g. @p FE_Q classes).
+     * the first cell but not any more afterwards.  This is the case for e.g.
+     * Lagrangian elements (see e.g. @p FE_Q classes).
      */
     void delete_fe_values_data (const unsigned int base_no);
 
@@ -922,8 +915,8 @@ private:
      * are accessed to by the @p set_ and @p get_fe_data functions.
      *
      * The size of this vector is set to @p n_base_elements by the
-     * InternalData constructor.  It is filled by the @p get_data
-     * function. Note that since the data for each instance of a base class is
+     * InternalData constructor.  It is filled by the @p get_data function.
+     * Note that since the data for each instance of a base class is
      * necessarily the same, we only need as many of these objects as there
      * are base elements, irrespective of their multiplicity.
      */
index 2d1cfd54ddf6485bcc7db1bd82066c893e4426be..6968f55cce9d6c4b3126f5e85ebe686dd42c1eb7 100644 (file)
@@ -51,20 +51,18 @@ class ConstraintMatrix;
 
 /**
  * This namespace offers interpolations and extrapolations of discrete
- * functions of one @p FiniteElement @p fe1 to another @p FiniteElement
- * @p fe2.
+ * functions of one @p FiniteElement @p fe1 to another @p FiniteElement @p
+ * fe2.
  *
- * It also provides the local interpolation matrices that interpolate
- * on each cell. Furthermore it provides the difference matrix
- * $id-I_h$ that is needed for evaluating $(id-I_h)z$ for e.g. the
- * dual solution $z$.
+ * It also provides the local interpolation matrices that interpolate on each
+ * cell. Furthermore it provides the difference matrix $id-I_h$ that is needed
+ * for evaluating $(id-I_h)z$ for e.g. the dual solution $z$.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
- * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat;
- * 2000, 2003, 2004, 2005, 2006
+ * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat; 2000, 2003, 2004,
+ * 2005, 2006
  */
 namespace FETools
 {
@@ -134,9 +132,9 @@ namespace FETools
    * @warning In most cases, you will probably want to use
    * compute_base_renumbering().
    *
-   * Compute the vector required to renumber the dofs of a cell by
-   * component. Furthermore, compute the vector storing the start indices of
-   * each component in the local block vector.
+   * Compute the vector required to renumber the dofs of a cell by component.
+   * Furthermore, compute the vector storing the start indices of each
+   * component in the local block vector.
    *
    * The second vector is organized such that there is a vector for each base
    * element containing the start index for each component served by this base
@@ -152,20 +150,19 @@ namespace FETools
     std::vector<std::vector<unsigned int> > &start_indices);
 
   /**
-   * Compute the vector required to renumber the dofs of a cell by
-   * block. Furthermore, compute the vector storing either the start indices
-   * or the size of each local block vector.
+   * Compute the vector required to renumber the dofs of a cell by block.
+   * Furthermore, compute the vector storing either the start indices or the
+   * size of each local block vector.
    *
    * If the @p bool parameter is true, @p block_data is filled with the start
    * indices of each local block. If it is false, then the block sizes are
    * returned.
    *
-   * The vector <tt>renumbering</tt> will be indexed by the standard
-   * numbering of local degrees of freedom, namely first first vertex,
-   * then second vertex, after vertices lines, quads, and hexes. For
-   * each index, the entry indicates the index which this degree of
-   * freedom receives in a numbering scheme, where the first block is
-   * numbered completely before the second.
+   * The vector <tt>renumbering</tt> will be indexed by the standard numbering
+   * of local degrees of freedom, namely first first vertex, then second
+   * vertex, after vertices lines, quads, and hexes. For each index, the entry
+   * indicates the index which this degree of freedom receives in a numbering
+   * scheme, where the first block is numbered completely before the second.
    */
   template<int dim, int spacedim>
   void compute_block_renumbering (
@@ -217,8 +214,8 @@ namespace FETools
    *
    * This function gives the matrix that transforms a @p fe1 function $z$ to
    * $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1
-   * space to the @p fe2 space. This matrix hence is useful to evaluate
-   * error-representations where $z$ denotes the dual solution.
+   * space to the @p fe2 space. This matrix hence is useful to evaluate error-
+   * representations where $z$ denotes the dual solution.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -269,8 +266,8 @@ namespace FETools
    * For all possible (isotropic and anisotropic) refinement cases compute the
    * embedding matrices from a coarse cell to the child cells. Each column of
    * the resulting matrices contains the representation of a coarse grid basis
-   * function by the fine grid basis; the matrices are split such that there is
-   * one matrix for every child.
+   * function by the fine grid basis; the matrices are split such that there
+   * is one matrix for every child.
    *
    * This function computes the coarse grid function in a sufficiently large
    * number of quadrature points and fits the fine grid functions using least
@@ -371,9 +368,9 @@ namespace FETools
    * data <tt>u<sub>q</sub>, 0 <= q < Q:=quadrature.size()</tt> defined at the
    * quadrature points of a cell, with the points defined by the given
    * <tt>rhs_quadrature</tt> object. We may then want to ask for that finite
-   * element function (on a single cell) <tt>v<sub>h</sub></tt> in the
-   * finite-dimensional space defined by the given FE object that is the
-   * projection of <tt>u</tt> in the following sense:
+   * element function (on a single cell) <tt>v<sub>h</sub></tt> in the finite-
+   * dimensional space defined by the given FE object that is the projection
+   * of <tt>u</tt> in the following sense:
    *
    * Usually, the projection <tt>v<sub>h</sub></tt> is that function that
    * satisfies <tt>(v<sub>h</sub>,w)=(u,w)</tt> for all discrete test
@@ -424,14 +421,14 @@ namespace FETools
    * triangulation. In effect, it therefore doesn't matter if you use a
    * continuous or discontinuous version of the finite element.
    *
-   * It is worth noting that there are a few confusing cases of this
-   * function. The first one is that it really only makes sense to project
-   * onto a finite element that has at most as many degrees of freedom per
-   * cell as there are quadrature points; the projection of N quadrature point
-   * data into a space with M>N unknowns is well-defined, but often yields
-   * funny and non-intuitive results. Secondly, one would think that if the
-   * quadrature point data is defined in the support points of the finite
-   * element, i.e. the quadrature points of <tt>ths_quadrature</tt> equal
+   * It is worth noting that there are a few confusing cases of this function.
+   * The first one is that it really only makes sense to project onto a finite
+   * element that has at most as many degrees of freedom per cell as there are
+   * quadrature points; the projection of N quadrature point data into a space
+   * with M>N unknowns is well-defined, but often yields funny and non-
+   * intuitive results. Secondly, one would think that if the quadrature point
+   * data is defined in the support points of the finite element, i.e. the
+   * quadrature points of <tt>ths_quadrature</tt> equal
    * <tt>fe.get_unit_support_points()</tt>, then the projection should be the
    * identity, i.e. each degree of freedom of the finite element equals the
    * value of the given data in the support point of the corresponding shape
@@ -534,16 +531,16 @@ namespace FETools
    * the same triangulation.
    *
    * If the elements @p fe1 and @p fe2 are either both continuous or both
-   * discontinuous then this interpolation is the usual point
-   * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
-   * discontinuous finite element. For the case that @p fe1 is a discontinuous
-   * and @p fe2 is a continuous finite element there is no point interpolation
-   * defined at the discontinuities.  Therefore the meanvalue is taken at the
-   * DoF values on the discontinuities.
-   *
-   * Note that for continuous elements on grids with hanging nodes
-   * (i.e. locally refined grids) this function does not give the expected
-   * output.  Indeed, the resulting output vector does not necessarily respect
+   * discontinuous then this interpolation is the usual point interpolation.
+   * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
+   * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
+   * a continuous finite element there is no point interpolation defined at
+   * the discontinuities.  Therefore the meanvalue is taken at the DoF values
+   * on the discontinuities.
+   *
+   * Note that for continuous elements on grids with hanging nodes (i.e.
+   * locally refined grids) this function does not give the expected output.
+   * Indeed, the resulting output vector does not necessarily respect
    * continuity requirements at hanging nodes: if, for example, you are
    * interpolating a Q2 field to a Q1 field, then at hanging nodes the output
    * field will have the function value of the input field, which however is
@@ -575,12 +572,12 @@ namespace FETools
    * with hanging nodes (locally refined grids).
    *
    * If the elements @p fe1 and @p fe2 are either both continuous or both
-   * discontinuous then this interpolation is the usual point
-   * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
-   * discontinuous finite element. For the case that @p fe1 is a discontinuous
-   * and @p fe2 is a continuous finite element there is no point interpolation
-   * defined at the discontinuities.  Therefore the mean value is taken at the
-   * DoF values at the discontinuities.
+   * discontinuous then this interpolation is the usual point interpolation.
+   * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
+   * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
+   * a continuous finite element there is no point interpolation defined at
+   * the discontinuities.  Therefore the mean value is taken at the DoF values
+   * at the discontinuities.
    */
   template <int dim, int spacedim,
             template <int, int> class DH1,
@@ -627,10 +624,9 @@ namespace FETools
    * Gives the interpolation of the @p dof1-function @p u1 to a @p
    * dof2-function, and interpolates this to a second @p dof1-function named
    * @p u1_interpolated.  @p constraints1 and @p constraints2 are the hanging
-   * node constraints corresponding to @p dof1 and @p dof2,
-   * respectively. These objects are particular important when continuous
-   * elements on grids with hanging nodes (locally refined grids) are
-   * involved.
+   * node constraints corresponding to @p dof1 and @p dof2, respectively.
+   * These objects are particular important when continuous elements on grids
+   * with hanging nodes (locally refined grids) are involved.
    *
    * Furthermore note, that for the specific case when the finite element
    * space corresponding to @p dof1 is a subset of the finite element space
@@ -707,55 +703,51 @@ namespace FETools
    * other:
    *
    * - It interpolates directly from every cell of @p dof1 to the
-   *   corresponding cell of `dof2` using the interpolation matrix of the
-   *   finite element spaces used on these cells and provided by
-   *   the finite element objects involved. This step is done using the
-   *   FETools::interpolate() function.
-   * - It then performs a loop over all non-active cells of `dof2`. If
-   *   such a non-active cell has at least one active child, then we
-   *   call the children of this cell a "patch". We then interpolate
-   *   from the children of this patch to the patch, using the finite
-   *   element space associated with `dof2` and immediately interpolate
-   *   back to the children. In essence, this information throws away
-   *   all information in the solution vector that lives on a scale
-   *   smaller than the patch cell.
-   * - Since we traverse non-active cells from the coarsest to the
-   *   finest levels, we may find patches that correspond to child
-   *   cells of previously treated patches if the mesh had been
-   *   refined adaptively (this cannot happen if the mesh has been
-   *   refined globally because there the children of a patch are
-   *   all active). We also perform the operation described above
-   *   on these patches, but it is easy to see that on patches that
-   *   are children of previously treated patches, the operation is
-   *   now the identity operation (since it interpolates from the
-   *   children of the current patch a function that had previously
-   *   been interpolated to these children from an even coarser patch).
-   *   Consequently, this does not alter the solution vector any more.
-   *
-   * The name of the function originates from the fact that it can be
-   * used to construct a representation of a function of higher polynomial
-   * degree on a once coarser mesh. For example, if you imagine that you
-   * start with a $Q_1$ function on globally refined mesh, and that @p dof2
-   * is associated with a $Q_2$ element, then this function computes the
-   * equivalent of the operator $I_{2h}^{(2)}$ interpolating the original
-   * piecewise linear function onto a quadratic function on a once coarser
-   * mesh with mesh size $2h$ (but representing this function on the original
-   * mesh with size $h$). If the exact solution is sufficiently smooth,
-   * then $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to
-   * the exact solution $u$ of the PDE than $u_h$ is. In other words, this
-   * function provides a postprocessing step that improves the solution in
-   * a similar way one often obtains by extrapolating a sequence of solutions,
+   * corresponding cell of `dof2` using the interpolation matrix of the finite
+   * element spaces used on these cells and provided by the finite element
+   * objects involved. This step is done using the FETools::interpolate()
+   * function. - It then performs a loop over all non-active cells of `dof2`.
+   * If such a non-active cell has at least one active child, then we call the
+   * children of this cell a "patch". We then interpolate from the children of
+   * this patch to the patch, using the finite element space associated with
+   * `dof2` and immediately interpolate back to the children. In essence, this
+   * information throws away all information in the solution vector that lives
+   * on a scale smaller than the patch cell. - Since we traverse non-active
+   * cells from the coarsest to the finest levels, we may find patches that
+   * correspond to child cells of previously treated patches if the mesh had
+   * been refined adaptively (this cannot happen if the mesh has been refined
+   * globally because there the children of a patch are all active). We also
+   * perform the operation described above on these patches, but it is easy to
+   * see that on patches that are children of previously treated patches, the
+   * operation is now the identity operation (since it interpolates from the
+   * children of the current patch a function that had previously been
+   * interpolated to these children from an even coarser patch). Consequently,
+   * this does not alter the solution vector any more.
+   *
+   * The name of the function originates from the fact that it can be used to
+   * construct a representation of a function of higher polynomial degree on a
+   * once coarser mesh. For example, if you imagine that you start with a
+   * $Q_1$ function on globally refined mesh, and that @p dof2 is associated
+   * with a $Q_2$ element, then this function computes the equivalent of the
+   * operator $I_{2h}^{(2)}$ interpolating the original piecewise linear
+   * function onto a quadratic function on a once coarser mesh with mesh size
+   * $2h$ (but representing this function on the original mesh with size $h$).
+   * If the exact solution is sufficiently smooth, then
+   * $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to the exact
+   * solution $u$ of the PDE than $u_h$ is. In other words, this function
+   * provides a postprocessing step that improves the solution in a similar
+   * way one often obtains by extrapolating a sequence of solutions,
    * explaining the origin of the function's name.
    *
-   * @note The resulting field does not satisfy continuity requirements of
-   * the given finite elements if the algorithm outlined above is used.
-   * When you use continuous elements on grids with hanging nodes, please use
-   * the @p extrapolate function with an additional ConstraintMatrix argument,
-   * see below.
+   * @note The resulting field does not satisfy continuity requirements of the
+   * given finite elements if the algorithm outlined above is used. When you
+   * use continuous elements on grids with hanging nodes, please use the @p
+   * extrapolate function with an additional ConstraintMatrix argument, see
+   * below.
    *
    * @note Since this function operates on patches of cells, it requires that
-   * the underlying grid is refined at least once for every coarse grid cell. If
-   * this is not the case, an exception will be raised.
+   * the underlying grid is refined at least once for every coarse grid cell.
+   * If this is not the case, an exception will be raised.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void extrapolate (const DoFHandler<dim,spacedim> &dof1,
@@ -765,10 +757,10 @@ namespace FETools
 
   /**
    * Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p
-   * dof2 function @p z2.  @p dof1 and @p dof2 need to be DoFHandler objects based on
-   * the same triangulation.  @p constraints is a hanging node constraints
-   * object corresponding to @p dof2. This object is necessary when
-   * interpolating onto continuous elements on grids with hanging nodes
+   * dof2 function @p z2.  @p dof1 and @p dof2 need to be DoFHandler objects
+   * based on the same triangulation.  @p constraints is a hanging node
+   * constraints object corresponding to @p dof2. This object is necessary
+   * when interpolating onto continuous elements on grids with hanging nodes
    * (locally refined grids).
    *
    * Otherwise, the function does the same as the other @p extrapolate
@@ -848,14 +840,15 @@ namespace FETools
    * accordingly.
    *
    * The name must be in the form which is returned by the
-   * FiniteElement::get_name function, where dimension template parameters &lt;2&gt; etc. can be
-   * omitted. Alternatively, the explicit number can be replaced by
-   * <tt>dim</tt> or <tt>d</tt>. If a number is given, it <b>must</b> match
-   * the template parameter of this function.
+   * FiniteElement::get_name function, where dimension template parameters
+   * &lt;2&gt; etc. can be omitted. Alternatively, the explicit number can be
+   * replaced by <tt>dim</tt> or <tt>d</tt>. If a number is given, it
+   * <b>must</b> match the template parameter of this function.
    *
-   * The names of FESystem elements follow the pattern <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code>
-   * The powers <code>p1</code> etc. may either be numbers or can be
-   * replaced by <tt>dim</tt> or <tt>d</tt>.
+   * The names of FESystem elements follow the pattern
+   * <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code> The powers <code>p1</code>
+   * etc. may either be numbers or can be replaced by <tt>dim</tt> or
+   * <tt>d</tt>.
    *
    *
    * If no finite element can be reconstructed from this string, an exception
@@ -897,12 +890,12 @@ namespace FETools
    * The format of the @p name parameter should include the name of a finite
    * element. However, it is safe to use either the class name alone or to use
    * the result of FiniteElement::get_name (which includes the space dimension
-   * as well as the polynomial degree), since everything after the first
-   * non-name character will be ignored.
+   * as well as the polynomial degree), since everything after the first non-
+   * name character will be ignored.
    *
-   * The FEFactory object should be an object newly created with
-   * <tt>new</tt>. FETools will take ownership of this object and delete it
-   * once it is not used anymore.
+   * The FEFactory object should be an object newly created with <tt>new</tt>.
+   * FETools will take ownership of this object and delete it once it is not
+   * used anymore.
    *
    * In most cases, if you want objects of type <code>MyFE</code> be created
    * whenever the name <code>my_fe</code> is given to get_fe_from_name, you
@@ -914,9 +907,8 @@ namespace FETools
    * argument, i.e. you should never attempt to destroy it later on. The
    * object will be deleted at the end of the program's lifetime.
    *
-   * If the name of the element is already in use, an exception is
-   * thrown. Thus, functionality of get_fe_from_name() can only be added, not
-   * changed.
+   * If the name of the element is already in use, an exception is thrown.
+   * Thus, functionality of get_fe_from_name() can only be added, not changed.
    *
    * @note This function manipulates a global table (one table for each space
    * dimension). It is thread safe in the sense that every access to this
index 52af72d2fcf9ef1df5a4200f7ca6ba51dce80a96..fec632520f02b7788bbf0712b25a9f3c913de42b 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * A finite element, which is the trace of FE_Q elements, that is
- * a tensor product of polynomials on the faces,
- * undefined in the interior of the cells and continuous. The basis functions on
- * the faces are from Polynomials::LagrangeEquidistant
+ * A finite element, which is the trace of FE_Q elements, that is a tensor
+ * product of polynomials on the faces, undefined in the interior of the cells
+ * and continuous. The basis functions on the faces are from
+ * Polynomials::LagrangeEquidistant
  *
- * This finite element is the trace space of FE_Q on the
- * faces.
+ * This finite element is the trace space of FE_Q on the faces.
  *
- * @note Since these are only finite elements on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, FEValues objects will not fail using this finite
- * element space, but all shape function values extracted will equal
- * to zero.
+ * @note Since these are only finite elements on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, FEValues objects
+ * will not fail using this finite element space, but all shape function
+ * values extracted will equal to zero.
  *
- * @todo Polynomials::LagrangeEquidistant should be and will be
- * replaced by Polynomials::LagrangeGaussLobatto as soon as such a
- * polynomial set exists.
+ * @todo Polynomials::LagrangeEquidistant should be and will be replaced by
+ * Polynomials::LagrangeGaussLobatto as soon as such a polynomial set exists.
  * @todo so far, hanging nodes are not implemented
  *
  */
@@ -50,26 +47,18 @@ class FE_TraceQ : public FE_PolyFace<TensorProductPolynomials<dim-1>, dim, space
 {
 public:
   /**
-   * Constructor for tensor product
-   * polynomials of degree
-   * <tt>p</tt>. The shape
-   * functions created using this
-   * constructor correspond to
-   * Legendre polynomials in each
-   * coordinate direction.
+   * Constructor for tensor product polynomials of degree <tt>p</tt>. The
+   * shape functions created using this constructor correspond to Legendre
+   * polynomials in each coordinate direction.
    */
   FE_TraceQ(unsigned int p);
 
   virtual FiniteElement<dim,spacedim> *clone() const;
 
   /**
-   * Return a string that uniquely
-   * identifies a finite
-   * element. This class returns
-   * <tt>FE_DGQ<dim>(degree)</tt>, with
-   * <tt>dim</tt> and <tt>degree</tt>
-   * replaced by appropriate
-   * values.
+   * Return a string that uniquely identifies a finite element. This class
+   * returns <tt>FE_DGQ<dim>(degree)</tt>, with <tt>dim</tt> and
+   * <tt>degree</tt> replaced by appropriate values.
    */
   virtual std::string get_name () const;
 
@@ -89,8 +78,7 @@ public:
 
 private:
   /**
-   * Return vector with dofs per
-   * vertex, line, quad, hex.
+   * Return vector with dofs per vertex, line, quad, hex.
    */
   static std::vector<unsigned int> get_dpo_vector (const unsigned int deg);
 };
index 1150fa877f3e658f80735a3eab646fdf79e9c913..f438a71a64a612f79452cb44fd80180923994c93 100644 (file)
@@ -25,59 +25,55 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * The enum type given to the constructors of FEValues, FEFaceValues
- * and FESubfaceValues, telling those objects which data will be
- * needed on each mesh cell.
+ * The enum type given to the constructors of FEValues, FEFaceValues and
+ * FESubfaceValues, telling those objects which data will be needed on each
+ * mesh cell.
  *
- * Selecting these flags in a restrictive way is crucial for the
- * efficiency of FEValues::reinit(), FEFaceValues::reinit() and
- * FESubfaceValues::reinit(). Therefore, only the flags actually
- * needed should be selected. It is the responsibility of the involved
- * Mapping and FiniteElement to add additional flags according to
- * their own requirements. For instance, most finite elements will
- * add #update_covariant_transformation if #update_gradients is
- * selected.
-
- * By default, all flags are off, i.e. no reinitialization will be
+ * Selecting these flags in a restrictive way is crucial for the efficiency of
+ * FEValues::reinit(), FEFaceValues::reinit() and FESubfaceValues::reinit().
+ * Therefore, only the flags actually needed should be selected. It is the
+ * responsibility of the involved Mapping and FiniteElement to add additional
+ * flags according to their own requirements. For instance, most finite
+ * elements will add #update_covariant_transformation if #update_gradients is
+ * selected.  By default, all flags are off, i.e. no reinitialization will be
  * done.
  *
- * You can select more than one flag by concatenation
- * using the bitwise or operator|(UpdateFlags,UpdateFlags).
+ * You can select more than one flag by concatenation using the bitwise or
+ * operator|(UpdateFlags,UpdateFlags).
  *
  * <h3>Generating the actual flags</h3>
  *
  * When given a set of UpdateFlags @p flags, the FEValues object must
  * determine, which values will have to be computed once only for the
- * reference cell and which values will have to be updated for each
- * cell. Here, it is important to note that in many cases, the
- * FiniteElement will require additional updates from the Mapping. To
- * this end, several auxiliary functions have been implemented:
+ * reference cell and which values will have to be updated for each cell.
+ * Here, it is important to note that in many cases, the FiniteElement will
+ * require additional updates from the Mapping. To this end, several auxiliary
+ * functions have been implemented:
  *
- * FiniteElement::update_once(flags) and
- * FiniteElement::update_each(flags) determine the values required by
- * the FiniteElement once or on each cell. The same functions exist in Mapping.
+ * FiniteElement::update_once(flags) and FiniteElement::update_each(flags)
+ * determine the values required by the FiniteElement once or on each cell.
+ * The same functions exist in Mapping.
  *
- * Since the FiniteElement does not know if a value required from
- * Mapping should be computed once or for each cell,
- * FEValuesBase::compute_update_flags() is used to compute the union
- * of all values to be computed ever. It does this by first adding to
- * the flags set by the user all flags (once and each) added by the
- * FiniteElement. This new set of flags is then given to the Mapping
- * and all flags required there are added, again once and each.
+ * Since the FiniteElement does not know if a value required from Mapping
+ * should be computed once or for each cell,
+ * FEValuesBase::compute_update_flags() is used to compute the union of all
+ * values to be computed ever. It does this by first adding to the flags set
+ * by the user all flags (once and each) added by the FiniteElement. This new
+ * set of flags is then given to the Mapping and all flags required there are
+ * added, again once and each.
  *
  * This union of all flags is given to Mapping::fill_fe_values() and
- * FiniteElement::fill_fe_values, where it is split again into the
- * information generated only once and the information that must be
- * updated on each cell.
+ * FiniteElement::fill_fe_values, where it is split again into the information
+ * generated only once and the information that must be updated on each cell.
  *
- * The flags finally stored in FEValues then are the union of all the
- * flags required by the user, by FiniteElement and by Mapping, for
- * computation once or on each cell. Subsequent calls to the functions
- * @p update_once and @p update_each should just select among these
- * flags, but should not add new flags.
+ * The flags finally stored in FEValues then are the union of all the flags
+ * required by the user, by FiniteElement and by Mapping, for computation once
+ * or on each cell. Subsequent calls to the functions @p update_once and @p
+ * update_each should just select among these flags, but should not add new
+ * flags.
  *
- * The mechanism by which all this is accomplished is also discussed
- * on the page on @ref UpdateFlagsEssay.
+ * The mechanism by which all this is accomplished is also discussed on the
+ * page on @ref UpdateFlagsEssay.
  */
 enum UpdateFlags
 {
@@ -85,30 +81,30 @@ enum UpdateFlags
   update_default = 0,
   //! Shape function values
   /**
-   * Compute the values of the shape functions at the quadrature points on
-   * the real space cell. For the usual Lagrange elements, these values are
-   * equal to the values of the shape functions at the quadrature points on
-   * the unit cell, but they are different for more complicated elements,
-   * such as FE_RaviartThomas elements.
+   * Compute the values of the shape functions at the quadrature points on the
+   * real space cell. For the usual Lagrange elements, these values are equal
+   * to the values of the shape functions at the quadrature points on the unit
+   * cell, but they are different for more complicated elements, such as
+   * FE_RaviartThomas elements.
    */
   update_values = 0x0001,
   //! Shape function gradients
   /**
-   * Compute the gradients of the shape functions in coordinates of the
-   * real cell.
+   * Compute the gradients of the shape functions in coordinates of the real
+   * cell.
    */
   update_gradients = 0x0002,
   //! Second derivatives of shape functions
   /**
-   * Compute the second derivatives of the shape functions in coordinates
-   * of the real cell.
+   * Compute the second derivatives of the shape functions in coordinates of
+   * the real cell.
    */
   update_hessians = 0x0004,
   //! Outer normal vector, not normalized
   /**
-   * Vector product of tangential vectors, yielding a normal vector with
-   * a length corresponding to the surface element; may be more efficient
-   * than computing both.
+   * Vector product of tangential vectors, yielding a normal vector with a
+   * length corresponding to the surface element; may be more efficient than
+   * computing both.
    */
   update_boundary_forms = 0x0008,
   //! Transformed quadrature points
@@ -118,16 +114,16 @@ enum UpdateFlags
   update_quadrature_points = 0x0010,
   //! Transformed quadrature weights
   /**
-   * Compute the quadrature weights on the real cell, i.e. the weights
-   * of the quadrature rule multiplied with the determinant of the Jacoian
-   * of the transformation from reference to realcell.
+   * Compute the quadrature weights on the real cell, i.e. the weights of the
+   * quadrature rule multiplied with the determinant of the Jacoian of the
+   * transformation from reference to realcell.
    */
   update_JxW_values = 0x0020,
   //! Normal vectors
   /**
    * Compute the normal vectors, either for a face or for a cell of
-   * codimension one. Setting this flag for any other object will raise
-   * an error.
+   * codimension one. Setting this flag for any other object will raise an
+   * error.
    */
   update_normal_vectors = 0x0040,
   /**
@@ -140,8 +136,8 @@ enum UpdateFlags
   update_cell_normal_vectors = update_normal_vectors,
   //! Volume element
   /**
-   * Compute the Jacobian of the transformation from the reference cell
-   * to the real cell.
+   * Compute the Jacobian of the transformation from the reference cell to the
+   * real cell.
    */
   update_jacobians = 0x0080,
   //! Gradient of volume element
@@ -171,14 +167,14 @@ enum UpdateFlags
   update_contravariant_transformation = 0x0800,
   //! Shape function values of transformation
   /**
-   * Compute the shape function values of the transformation defined by
-   * the Mapping.
+   * Compute the shape function values of the transformation defined by the
+   * Mapping.
    */
   update_transformation_values = 0x1000,
   //! Shape function gradients of transformation
   /**
-   * Compute the shape function gradients of the transformation defined
-   * by the Mapping.
+   * Compute the shape function gradients of the transformation defined by the
+   * Mapping.
    */
   update_transformation_gradients = 0x2000,
   //! Determinant of the Jacobian
@@ -195,8 +191,7 @@ enum UpdateFlags
    */
   update_support_jacobians = 0x20000,
   /**
-   * Update the inverse Jacobian of the mapping in generalized support
-   * points.
+   * Update the inverse Jacobian of the mapping in generalized support points.
    */
   update_support_inverse_jacobians = 0x40000,
   /**
@@ -248,12 +243,11 @@ STREAM &operator << (STREAM &s, UpdateFlags u)
 
 
 /**
- * Global operator which returns an object in which all bits are set
- * which are either set in the first or the second argument. This
- * operator exists since if it did not then the result of the bit-or
- * <tt>operator |</tt> would be an integer which would in turn trigger
- * a compiler warning when we tried to assign it to an object of type
- * UpdateFlags.
+ * Global operator which returns an object in which all bits are set which are
+ * either set in the first or the second argument. This operator exists since
+ * if it did not then the result of the bit-or <tt>operator |</tt> would be an
+ * integer which would in turn trigger a compiler warning when we tried to
+ * assign it to an object of type UpdateFlags.
  *
  * @ref UpdateFlags
  */
@@ -270,8 +264,8 @@ operator | (UpdateFlags f1, UpdateFlags f2)
 
 
 /**
- * Global operator which sets the bits from the second argument also
- * in the first one.
+ * Global operator which sets the bits from the second argument also in the
+ * first one.
  *
  * @ref UpdateFlags
  */
@@ -285,12 +279,11 @@ operator |= (UpdateFlags &f1, UpdateFlags f2)
 
 
 /**
- * Global operator which returns an object in which all bits are set
- * which are set in the first as well as the second argument. This
- * operator exists since if it did not then the result of the bit-and
- * <tt>operator &</tt> would be an integer which would in turn trigger
- * a compiler warning when we tried to assign it to an object of type
- * UpdateFlags.
+ * Global operator which returns an object in which all bits are set which are
+ * set in the first as well as the second argument. This operator exists since
+ * if it did not then the result of the bit-and <tt>operator &</tt> would be
+ * an integer which would in turn trigger a compiler warning when we tried to
+ * assign it to an object of type UpdateFlags.
  *
  * @ref UpdateFlags
  */
@@ -305,8 +298,8 @@ operator & (UpdateFlags f1, UpdateFlags f2)
 
 
 /**
- * Global operator which clears all the bits in the first argument if
- * they are not also set in the second argument.
+ * Global operator which clears all the bits in the first argument if they are
+ * not also set in the second argument.
  *
  * @ref UpdateFlags
  */
@@ -323,12 +316,12 @@ operator &= (UpdateFlags &f1, UpdateFlags f2)
 /**
  * This enum definition is used for storing similarities of the current cell
  * to the previously visited cell. This information is used for reusing data
- * when calling the method FEValues::reinit() (like derivatives, which do
- * not change if one cell is just a translation of the previous). Currently,
- * this variable does only recognize a translation and an inverted translation
- * (if dim<spacedim). However, this concept
- * makes it easy to add additional staties to be detected in
- * FEValues/FEFaceValues for making use of these similarities as well.
+ * when calling the method FEValues::reinit() (like derivatives, which do not
+ * change if one cell is just a translation of the previous). Currently, this
+ * variable does only recognize a translation and an inverted translation (if
+ * dim<spacedim). However, this concept makes it easy to add additional
+ * staties to be detected in FEValues/FEFaceValues for making use of these
+ * similarities as well.
  */
 namespace CellSimilarity
 {
index 8493c301b965443f661821b28276f4f15a3e152a..5a040749dabed0586184da4413a033b5554021a2 100644 (file)
@@ -149,9 +149,9 @@ namespace FEValuesViews
     typedef double        value_type;
 
     /**
-     * A typedef for the type of gradients of the view this class
-     * represents. Here, for a scalar component of the finite element, the
-     * gradient is a <code>Tensor@<1,dim@></code>.
+     * A typedef for the type of gradients of the view this class represents.
+     * Here, for a scalar component of the finite element, the gradient is a
+     * <code>Tensor@<1,dim@></code>.
      */
     typedef dealii::Tensor<1,spacedim> gradient_type;
 
@@ -212,9 +212,9 @@ namespace FEValuesViews
      * Return the value of the vector component selected by this view, for the
      * shape function and quadrature point selected by the arguments.
      *
-     * @param shape_function Number of the shape function to be
-     * evaluated. Note that this number runs from zero to dofs_per_cell, even
-     * in the case of an FEFaceValues or FESubfaceValues object.
+     * @param shape_function Number of the shape function to be evaluated.
+     * Note that this number runs from zero to dofs_per_cell, even in the case
+     * of an FEFaceValues or FESubfaceValues object.
      *
      * @param q_point Number of the quadrature point at which function is to
      * be evaluated.
@@ -377,9 +377,9 @@ namespace FEValuesViews
     typedef dealii::Tensor<1,spacedim>          value_type;
 
     /**
-     * A typedef for the type of gradients of the view this class
-     * represents. Here, for a set of <code>dim</code> components of the
-     * finite element, the gradient is a <code>Tensor@<2,spacedim@></code>.
+     * A typedef for the type of gradients of the view this class represents.
+     * Here, for a set of <code>dim</code> components of the finite element,
+     * the gradient is a <code>Tensor@<2,spacedim@></code>.
      *
      * See the general documentation of this class for how exactly the
      * gradient of a vector is defined.
@@ -406,9 +406,9 @@ namespace FEValuesViews
     typedef double                 divergence_type;
 
     /**
-     * A typedef for the type of the curl of the view this class
-     * represents. Here, for a set of <code>spacedim=2</code> components of
-     * the finite element, the curl is a <code>Tensor@<1, 1@></code>. For
+     * A typedef for the type of the curl of the view this class represents.
+     * Here, for a set of <code>spacedim=2</code> components of the finite
+     * element, the curl is a <code>Tensor@<1, 1@></code>. For
      * <code>spacedim=3</code> it is a <code>Tensor@<1, dim@></code>.
      */
     typedef typename dealii::internal::CurlType<spacedim>::type   curl_type;
@@ -483,14 +483,14 @@ namespace FEValuesViews
 
     /**
      * Return the value of the vector components selected by this view, for
-     * the shape function and quadrature point selected by the
-     * arguments. Here, since the view represents a vector-valued part of the
-     * FEValues object with <code>dim</code> components, the return type is a
-     * tensor of rank 1 with <code>dim</code> components.
+     * the shape function and quadrature point selected by the arguments.
+     * Here, since the view represents a vector-valued part of the FEValues
+     * object with <code>dim</code> components, the return type is a tensor of
+     * rank 1 with <code>dim</code> components.
      *
-     * @param shape_function Number of the shape function to be
-     * evaluated. Note that this number runs from zero to dofs_per_cell, even
-     * in the case of an FEFaceValues or FESubfaceValues object.
+     * @param shape_function Number of the shape function to be evaluated.
+     * Note that this number runs from zero to dofs_per_cell, even in the case
+     * of an FEFaceValues or FESubfaceValues object.
      *
      * @param q_point Number of the quadrature point at which function is to
      * be evaluated.
@@ -553,8 +553,8 @@ namespace FEValuesViews
 
     /**
      * Return the vector curl of the vector components selected by this view,
-     * for the shape function and quadrature point selected by the
-     * arguments. For 1d this function does not make any sense. Thus it is not
+     * for the shape function and quadrature point selected by the arguments.
+     * For 1d this function does not make any sense. Thus it is not
      * implemented for <code>spacedim=1</code>.  In 2d the curl is defined as
      * @f{equation*} \operatorname{curl}(u):=\frac{du_2}{dx} -\frac{du_1}{dy},
      * @f} whereas in 3d it is given by @f{equation*}
@@ -837,15 +837,15 @@ namespace FEValuesViews
 
     /**
      * Return the value of the vector components selected by this view, for
-     * the shape function and quadrature point selected by the
-     * arguments. Here, since the view represents a vector-valued part of the
-     * FEValues object with <code>(dim*dim + dim)/2</code> components (the
-     * unique components of a symmetric second-order tensor), the return type
-     * is a symmetric tensor of rank 2.
+     * the shape function and quadrature point selected by the arguments.
+     * Here, since the view represents a vector-valued part of the FEValues
+     * object with <code>(dim*dim + dim)/2</code> components (the unique
+     * components of a symmetric second-order tensor), the return type is a
+     * symmetric tensor of rank 2.
      *
-     * @param shape_function Number of the shape function to be
-     * evaluated. Note that this number runs from zero to dofs_per_cell, even
-     * in the case of an FEFaceValues or FESubfaceValues object.
+     * @param shape_function Number of the shape function to be evaluated.
+     * Note that this number runs from zero to dofs_per_cell, even in the case
+     * of an FEFaceValues or FESubfaceValues object.
      *
      * @param q_point Number of the quadrature point at which function is to
      * be evaluated.
@@ -1031,15 +1031,14 @@ namespace FEValuesViews
 
     /**
      * Return the value of the vector components selected by this view, for
-     * the shape function and quadrature point selected by the
-     * arguments. Here, since the view represents a vector-valued part of the
-     * FEValues object with <code>(dim*dim)</code> components (the unique
-     * components of a second-order tensor), the return type is a tensor of
-     * rank 2.
+     * the shape function and quadrature point selected by the arguments.
+     * Here, since the view represents a vector-valued part of the FEValues
+     * object with <code>(dim*dim)</code> components (the unique components of
+     * a second-order tensor), the return type is a tensor of rank 2.
      *
-     * @param shape_function Number of the shape function to be
-     * evaluated. Note that this number runs from zero to dofs_per_cell, even
-     * in the case of an FEFaceValues or FESubfaceValues object.
+     * @param shape_function Number of the shape function to be evaluated.
+     * Note that this number runs from zero to dofs_per_cell, even in the case
+     * of an FEFaceValues or FESubfaceValues object.
      *
      * @param q_point Number of the quadrature point at which function is to
      * be evaluated.
@@ -1290,39 +1289,31 @@ public:
   std::vector<Tensor<1,spacedim> >  boundary_forms;
 
   /**
-  * When asked for the value (or gradient, or Hessian) of shape function i's
-  * c-th vector component, we need to look it up in the #shape_values,
-  * #shape_gradients and #shape_hessians arrays.  The question is where in
-  * this array does the data for shape function i, component c reside. This is
-  * what this table answers.
-  *
-  * The format of the table is as
-  * follows:
-  * - It has dofs_per_cell times
-  *   n_components entries.
-  * - The entry that corresponds to
-  *   shape function i, component c
-  *   is <code>i * n_components + c</code>.
-  * - The value stored at this
-  *   position indicates the row
-  *   in #shape_values and the
-  *   other tables where the
-  *   corresponding datum is stored
-  *   for all the quadrature points.
-  *
-  * In the general, vector-valued context, the number of components is larger
-  * than one, but for a given shape function, not all vector components may be
-  * nonzero (e.g., if a shape function is primitive, then exactly one vector
-  * component is non-zero, while the others are all zero). For such zero
-  * components, #shape_values and friends do not have a row. Consequently, for
-  * vector components for which shape function i is zero, the entry in the
-  * current table is numbers::invalid_unsigned_int.
-  *
-  * On the other hand, the table is guaranteed to have at least one valid
-  * index for each shape function. In particular, for a primitive finite
-  * element, each shape function has exactly one nonzero component and so for
-  * each i, there is exactly one valid index within the range
-  * <code>[i*n_components, (i+1)*n_components)</code>.
+   * When asked for the value (or gradient, or Hessian) of shape function i's
+   * c-th vector component, we need to look it up in the #shape_values,
+   * #shape_gradients and #shape_hessians arrays.  The question is where in
+   * this array does the data for shape function i, component c reside. This
+   * is what this table answers.
+   *
+   * The format of the table is as follows: - It has dofs_per_cell times
+   * n_components entries. - The entry that corresponds to shape function i,
+   * component c is <code>i * n_components + c</code>. - The value stored at
+   * this position indicates the row in #shape_values and the other tables
+   * where the corresponding datum is stored for all the quadrature points.
+   *
+   * In the general, vector-valued context, the number of components is larger
+   * than one, but for a given shape function, not all vector components may
+   * be nonzero (e.g., if a shape function is primitive, then exactly one
+   * vector component is non-zero, while the others are all zero). For such
+   * zero components, #shape_values and friends do not have a row.
+   * Consequently, for vector components for which shape function i is zero,
+   * the entry in the current table is numbers::invalid_unsigned_int.
+   *
+   * On the other hand, the table is guaranteed to have at least one valid
+   * index for each shape function. In particular, for a primitive finite
+   * element, each shape function has exactly one nonzero component and so for
+   * each i, there is exactly one valid index within the range
+   * <code>[i*n_components, (i+1)*n_components)</code>.
    */
   std::vector<unsigned int> shape_function_to_row_table;
 
@@ -1393,37 +1384,34 @@ public:
  * the same as defined by the quadrature formula passed to the constructor of
  * the FEValues object above.
  *
- *  <h3>Member functions</h3>
+ * <h3>Member functions</h3>
  *
- *  The functions of this class fall into different cathegories:
- *  <ul>
- *  <li> shape_value(), shape_grad(), etc: return one of the values
- *    of this object at a time. These functions are inlined, so this
- *    is the suggested access to all finite element values. There
- *    should be no loss in performance with an optimizing compiler. If
- *    the finite element is vector valued, then these functions return
- *    the only non-zero component of the requested shape
- *    function. However, some finite elements have shape functions
- *    that have more than one non-zero component (we call them
- *    non-"primitive"), and in this case this set of functions will
- *    throw an exception since they cannot generate a useful
- *    result. Rather, use the next set of functions.
+ * The functions of this class fall into different cathegories:
+ * <ul>
+ * <li> shape_value(), shape_grad(), etc: return one of the values of this
+ * object at a time. These functions are inlined, so this is the suggested
+ * access to all finite element values. There should be no loss in performance
+ * with an optimizing compiler. If the finite element is vector valued, then
+ * these functions return the only non-zero component of the requested shape
+ * function. However, some finite elements have shape functions that have more
+ * than one non-zero component (we call them non-"primitive"), and in this
+ * case this set of functions will throw an exception since they cannot
+ * generate a useful result. Rather, use the next set of functions.
  *
- *  <li> shape_value_component(), shape_grad_component(), etc:
- *    This is the same set of functions as above, except that for vector
- *    valued finite elements they return only one vector component. This
- *    is useful for elements of which shape functions have more than one
- *    non-zero component, since then the above functions cannot be used,
- *    and you have to walk over all (or only the non-zero) components of
- *    the shape function using this set of functions.
+ * <li> shape_value_component(), shape_grad_component(), etc: This is the same
+ * set of functions as above, except that for vector valued finite elements
+ * they return only one vector component. This is useful for elements of which
+ * shape functions have more than one non-zero component, since then the above
+ * functions cannot be used, and you have to walk over all (or only the non-
+ * zero) components of the shape function using this set of functions.
  *
- *  <li> get_function_values(), get_function_gradients(), etc.: Compute a
- *    finite element function or its derivative in quadrature points.
+ * <li> get_function_values(), get_function_gradients(), etc.: Compute a
+ * finite element function or its derivative in quadrature points.
  *
- *  <li> reinit: initialize the FEValues object for a certain cell.
- *    This function is not in the present class but only in the derived
- *    classes and has a variable call syntax.
- *    See the docs for the derived classes for more information.
+ * <li> reinit: initialize the FEValues object for a certain cell. This
+ * function is not in the present class but only in the derived classes and
+ * has a variable call syntax. See the docs for the derived classes for more
+ * information.
  * </ul>
  *
  *
@@ -1499,8 +1487,8 @@ public:
    * subface selected the last time the <tt>reinit</tt> function of the
    * derived class was called.
    *
-   * If the shape function is vector-valued, then this returns the only
-   * non-zero component. If the shape function has more than one non-zero
+   * If the shape function is vector-valued, then this returns the only non-
+   * zero component. If the shape function has more than one non-zero
    * component (i.e. it is not primitive), then throw an exception of type
    * ExcShapeFunctionNotPrimitive. In that case, use the
    * shape_value_component() function.
@@ -1550,8 +1538,8 @@ public:
    * reference to the gradient's value is returned, there should be no major
    * performance drawback.
    *
-   * If the shape function is vector-valued, then this returns the only
-   * non-zero component. If the shape function has more than one non-zero
+   * If the shape function is vector-valued, then this returns the only non-
+   * zero component. If the shape function has more than one non-zero
    * component (i.e. it is not primitive), then it will throw an exception of
    * type ExcShapeFunctionNotPrimitive. In that case, use the
    * shape_grad_component() function.
@@ -1594,8 +1582,8 @@ public:
    * one component. Since only a reference to the derivative values is
    * returned, there should be no major performance drawback.
    *
-   * If the shape function is vector-valued, then this returns the only
-   * non-zero component. If the shape function has more than one non-zero
+   * If the shape function is vector-valued, then this returns the only non-
+   * zero component. If the shape function has more than one non-zero
    * component (i.e. it is not primitive), then throw an exception of type
    * ExcShapeFunctionNotPrimitive. In that case, use the
    * shape_grad_grad_component() function.
@@ -1660,8 +1648,8 @@ public:
    * current cell and point values are computed from that.
    *
    * This function may only be used if the finite element in use is a scalar
-   * one, i.e. has only one vector component.  To get values of
-   * multi-component elements, there is another get_function_values() below,
+   * one, i.e. has only one vector component.  To get values of multi-
+   * component elements, there is another get_function_values() below,
    * returning a vector of vectors of results.
    *
    * @param[in] fe_function A vector of values that describes (globally) the
@@ -1816,9 +1804,9 @@ public:
    * is assume to already have the correct size.
    *
    * @post <code>gradients[q]</code> will contain the gradient of the field
-   * described by fe_function at the $q$th quadrature
-   * point. <code>gradients[q][d]</code> represents the derivative in
-   * coordinate direction $d$ at quadrature point $q$.
+   * described by fe_function at the $q$th quadrature point.
+   * <code>gradients[q][d]</code> represents the derivative in coordinate
+   * direction $d$ at quadrature point $q$.
    *
    * @note The actual data type of the input vector may be either a
    * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the sequential PETSc or
@@ -1933,9 +1921,9 @@ public:
    * is assume to already have the correct size.
    *
    * @post <code>hessians[q]</code> will contain the Hessian of the field
-   * described by fe_function at the $q$th quadrature
-   * point. <code>hessians[q][i][j]</code> represents the $(i,j)$th component
-   * of the matrix of second derivatives at quadrature point $q$.
+   * described by fe_function at the $q$th quadrature point.
+   * <code>hessians[q][i][j]</code> represents the $(i,j)$th component of the
+   * matrix of second derivatives at quadrature point $q$.
    *
    * @note The actual data type of the input vector may be either a
    * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the sequential PETSc or
@@ -2036,9 +2024,9 @@ public:
    * is assume to already have the correct size.
    *
    * @post <code>laplacians[q]</code> will contain the Laplacian of the field
-   * described by fe_function at the $q$th quadrature
-   * point. <code>gradients[q][i][j]</code> represents the $(i,j)$th component
-   * of the matrix of second derivatives at quadrature point $q$.
+   * described by fe_function at the $q$th quadrature point.
+   * <code>gradients[q][i][j]</code> represents the $(i,j)$th component of the
+   * matrix of second derivatives at quadrature point $q$.
    *
    * @post For each component of the output vector, there holds
    * <code>laplacians[q]=trace(hessians[q])</code>, where <tt>hessians</tt>
@@ -2170,7 +2158,8 @@ public:
   const DerivativeForm<1,dim,spacedim> &jacobian (const unsigned int quadrature_point) const;
 
   /**
-   * Return a reference to the array holding the values returned by jacobian().
+   * Return a reference to the array holding the values returned by
+   * jacobian().
    *
    * @dealiiRequiresUpdateFlags{update_jacobians}
    */
@@ -2186,7 +2175,8 @@ public:
   const DerivativeForm<2,dim,spacedim> &jacobian_grad (const unsigned int quadrature_point) const;
 
   /**
-   * Return a reference to the array holding the values returned by jacobian_grads().
+   * Return a reference to the array holding the values returned by
+   * jacobian_grads().
    *
    * @dealiiRequiresUpdateFlags{update_jacobian_grads}
    */
@@ -2201,7 +2191,8 @@ public:
   const DerivativeForm<1,spacedim,dim> &inverse_jacobian (const unsigned int quadrature_point) const;
 
   /**
-   * Return a reference to the array holding the values returned by inverse_jacobian().
+   * Return a reference to the array holding the values returned by
+   * inverse_jacobian().
    *
    * @dealiiRequiresUpdateFlags{update_inverse_jacobians}
    */
@@ -2654,7 +2645,7 @@ private:
  * See FEValuesBase
  *
  * @ingroup feaccess
- *  @author Wolfgang Bangerth, 1998, Guido Kanschat, 2000, 2001
+ * @author Wolfgang Bangerth, 1998, Guido Kanschat, 2000, 2001
  */
 template <int dim, int spacedim=dim>
 class FEFaceValuesBase : public FEValuesBase<dim,spacedim>
@@ -3340,10 +3331,8 @@ namespace FEValuesViews
   namespace
   {
     /**
-     * Return the symmetrized version of a
-     * tensor whose n'th row equals the
-     * second argument, with all other rows
-     * equal to zero.
+     * Return the symmetrized version of a tensor whose n'th row equals the
+     * second argument, with all other rows equal to zero.
      */
     inline
     dealii::SymmetricTensor<2,1>
index e8d1ec285846b9bbe116a0e740ed5a612df53ac4..813e8f315e6987c3be65a91c69abbe6683e0e27c 100644 (file)
@@ -40,137 +40,96 @@ DEAL_II_NAMESPACE_OPEN
 namespace FEValuesExtractors
 {
   /**
-   * Extractor for a single scalar component
-   * of a vector-valued element. The result
-   * of applying an object of this type to an
-   * FEValues, FEFaceValues or
-   * FESubfaceValues object is of type
-   * FEValuesViews::Scalar. The concept of
-   * extractors is defined in the
-   * documentation of the namespace
-   * FEValuesExtractors and in the @ref
-   * vector_valued module.
+   * Extractor for a single scalar component of a vector-valued element. The
+   * result of applying an object of this type to an FEValues, FEFaceValues or
+   * FESubfaceValues object is of type FEValuesViews::Scalar. The concept of
+   * extractors is defined in the documentation of the namespace
+   * FEValuesExtractors and in the @ref vector_valued module.
    *
    * @ingroup feaccess vector_valued
    */
   struct Scalar
   {
     /**
-     * The selected scalar component of the
-     * vector.
+     * The selected scalar component of the vector.
      */
     unsigned int component;
 
     /**
-     * Default constructor. Initialize the
-     * object with an invalid component. This leads to
-     * an object that can not be used, but it allows
-     * objects of this kind to be put into arrays that
-     * require a default constructor upon resizing the
-     * array, and then later assigning a suitable
-     * object to each element of the array.
+     * Default constructor. Initialize the object with an invalid component.
+     * This leads to an object that can not be used, but it allows objects of
+     * this kind to be put into arrays that require a default constructor upon
+     * resizing the array, and then later assigning a suitable object to each
+     * element of the array.
      */
     Scalar ();
 
     /**
-     * Constructor. Take the selected
-     * vector component as argument.
+     * Constructor. Take the selected vector component as argument.
      */
     Scalar (const unsigned int component);
   };
 
 
   /**
-   * Extractor for a vector of
-   * <code>spacedim</code> components of a
-   * vector-valued element. The value of
-   * <code>spacedim</code> is defined by the
-   * FEValues object the extractor is applied
-   * to. The result of applying an object of
-   * this type to an FEValues, FEFaceValues
-   * or FESubfaceValues object is of type
-   * FEValuesViews::Vector.
+   * Extractor for a vector of <code>spacedim</code> components of a vector-
+   * valued element. The value of <code>spacedim</code> is defined by the
+   * FEValues object the extractor is applied to. The result of applying an
+   * object of this type to an FEValues, FEFaceValues or FESubfaceValues
+   * object is of type FEValuesViews::Vector.
    *
-   * The concept of
-   * extractors is defined in the
-   * documentation of the namespace
-   * FEValuesExtractors and in the @ref
-   * vector_valued module.
+   * The concept of extractors is defined in the documentation of the
+   * namespace FEValuesExtractors and in the @ref vector_valued module.
    *
-   * Note that in the current context, a
-   * vector is meant in the sense physics
-   * uses it: it has <code>spacedim</code>
-   * components that behave in specific ways
-   * under coordinate system
-   * transformations. Examples include
-   * velocity or displacement fields. This is
-   * opposed to how mathematics uses the word
-   * "vector" (and how we use this word in
-   * other contexts in the library, for
-   * example in the Vector class), where it
-   * really stands for a collection of
-   * numbers. An example of this latter use
-   * of the word could be the set of
-   * concentrations of chemical species in a
-   * flame; however, these are really just a
-   * collection of scalar variables, since
-   * they do not change if the coordinate
-   * system is rotated, unlike the components
-   * of a velocity vector, and consequently,
-   * this class should not be used for this
-   * context.
+   * Note that in the current context, a vector is meant in the sense physics
+   * uses it: it has <code>spacedim</code> components that behave in specific
+   * ways under coordinate system transformations. Examples include velocity
+   * or displacement fields. This is opposed to how mathematics uses the word
+   * "vector" (and how we use this word in other contexts in the library, for
+   * example in the Vector class), where it really stands for a collection of
+   * numbers. An example of this latter use of the word could be the set of
+   * concentrations of chemical species in a flame; however, these are really
+   * just a collection of scalar variables, since they do not change if the
+   * coordinate system is rotated, unlike the components of a velocity vector,
+   * and consequently, this class should not be used for this context.
    *
    * @ingroup feaccess vector_valued
    */
   struct Vector
   {
     /**
-     * The first component of the vector
-     * view.
+     * The first component of the vector view.
      */
     unsigned int first_vector_component;
 
     /**
-     * Default constructor. Initialize the
-     * object with an invalid component. This leads to
-     * an object that can not be used, but it allows
-     * objects of this kind to be put into arrays that
-     * require a default constructor upon resizing the
-     * array, and then later assigning a suitable
-     * object to each element of the array.
+     * Default constructor. Initialize the object with an invalid component.
+     * This leads to an object that can not be used, but it allows objects of
+     * this kind to be put into arrays that require a default constructor upon
+     * resizing the array, and then later assigning a suitable object to each
+     * element of the array.
      */
     Vector ();
 
     /**
-     * Constructor. Take the first
-     * component of the selected vector
-     * inside the FEValues object as
-     * argument.
+     * Constructor. Take the first component of the selected vector inside the
+     * FEValues object as argument.
      */
     Vector (const unsigned int first_vector_component);
   };
 
 
   /**
-   * Extractor for a symmetric tensor of a
-   * rank specified by the template
-   * argument. For a second order symmetric
-   * tensor, this represents a collection of
-   * <code>(dim*dim + dim)/2</code>
-   * components of a vector-valued
-   * element. The value of <code>dim</code>
-   * is defined by the FEValues object the
-   * extractor is applied to. The result of
-   * applying an object of this type to an
-   * FEValues, FEFaceValues or
-   * FESubfaceValues object is of type
-   * FEValuesViews::SymmetricTensor.
+   * Extractor for a symmetric tensor of a rank specified by the template
+   * argument. For a second order symmetric tensor, this represents a
+   * collection of <code>(dim*dim + dim)/2</code> components of a vector-
+   * valued element. The value of <code>dim</code> is defined by the FEValues
+   * object the extractor is applied to. The result of applying an object of
+   * this type to an FEValues, FEFaceValues or FESubfaceValues object is of
+   * type FEValuesViews::SymmetricTensor.
    *
-   * The concept of
-   * extractors is defined in the
-   * documentation of the namespace
-   * FEValuesExtractors and in the @ref
-   * vector_valued module.
+   * The concept of extractors is defined in the documentation of the
+   * namespace FEValuesExtractors and in the @ref vector_valued module.
    *
    * @ingroup feaccess vector_valued
    *
@@ -180,52 +139,38 @@ namespace FEValuesExtractors
   struct SymmetricTensor
   {
     /**
-     * The first component of the tensor
-     * view.
+     * The first component of the tensor view.
      */
     unsigned int first_tensor_component;
 
     /**
-     * Default constructor. Initialize the
-     * object with an invalid component. This leads to
-     * an object that can not be used, but it allows
-     * objects of this kind to be put into arrays that
-     * require a default constructor upon resizing the
-     * array, and then later assigning a suitable
-     * object to each element of the array.
+     * Default constructor. Initialize the object with an invalid component.
+     * This leads to an object that can not be used, but it allows objects of
+     * this kind to be put into arrays that require a default constructor upon
+     * resizing the array, and then later assigning a suitable object to each
+     * element of the array.
      */
     SymmetricTensor ();
 
     /**
-     * Constructor. Take the first
-     * component of the selected tensor
-     * inside the FEValues object as
-     * argument.
+     * Constructor. Take the first component of the selected tensor inside the
+     * FEValues object as argument.
      */
     SymmetricTensor (const unsigned int first_tensor_component);
   };
 
 
   /**
-   * Extractor for a (possible non-)symmetric tensor of a
-   * rank specified by the template
-   * argument. For a second order
-   * tensor, this represents a collection of
-   * <code>(dim*dim)</code>
-   * components of a vector-valued
-   * element. The value of <code>dim</code>
-   * is defined by the FEValues object the
-   * extractor is applied to. The result of
-   * applying an object of this type to an
-   * FEValues, FEFaceValues or
-   * FESubfaceValues object is of type
+   * Extractor for a (possible non-)symmetric tensor of a rank specified by
+   * the template argument. For a second order tensor, this represents a
+   * collection of <code>(dim*dim)</code> components of a vector-valued
+   * element. The value of <code>dim</code> is defined by the FEValues object
+   * the extractor is applied to. The result of applying an object of this
+   * type to an FEValues, FEFaceValues or FESubfaceValues object is of type
    * FEValuesViews::Tensor.
    *
-   * The concept of
-   * extractors is defined in the
-   * documentation of the namespace
-   * FEValuesExtractors and in the @ref
-   * vector_valued module.
+   * The concept of extractors is defined in the documentation of the
+   * namespace FEValuesExtractors and in the @ref vector_valued module.
    *
    * @ingroup feaccess vector_valued
    *
@@ -235,27 +180,22 @@ namespace FEValuesExtractors
   struct Tensor
   {
     /**
-     * The first component of the tensor
-     * view.
+     * The first component of the tensor view.
      */
     unsigned int first_tensor_component;
 
     /**
-     * Default constructor. Initialize the
-     * object with an invalid component. This leads to
-     * an object that can not be used, but it allows
-     * objects of this kind to be put into arrays that
-     * require a default constructor upon resizing the
-     * array, and then later assigning a suitable
-     * object to each element of the array.
+     * Default constructor. Initialize the object with an invalid component.
+     * This leads to an object that can not be used, but it allows objects of
+     * this kind to be put into arrays that require a default constructor upon
+     * resizing the array, and then later assigning a suitable object to each
+     * element of the array.
      */
     Tensor ();
 
     /**
-     * Constructor. Take the first
-     * component of the selected tensor
-     * inside the FEValues object as
-     * argument.
+     * Constructor. Take the first component of the selected tensor inside the
+     * FEValues object as argument.
      */
     Tensor (const unsigned int first_tensor_component);
   };
index 0eaac1d720442e58dfb16f97e4edcc804205ab6d..a6279429c2b5c68328c12d5f939b6405d5929abb 100644 (file)
@@ -35,21 +35,13 @@ template <int dim, int spacedim> class FEFaceValues;
 template <int dim, int spacedim> class FESubfaceValues;
 
 /**
- * The transformation type used
- * for the Mapping::transform() functions.
+ * The transformation type used for the Mapping::transform() functions.
  *
- * Special finite elements may
- * need special Mapping from the
- * reference cell to the actual
- * mesh cell. In order to be most
- * flexible, this enum provides
- * an extensible interface for
- * arbitrary
- * transformations. Nevertheless,
- * these must be implemented in
- * the transform() functions of
- * inheriting classes in order to
- * work.
+ * Special finite elements may need special Mapping from the reference cell to
+ * the actual mesh cell. In order to be most flexible, this enum provides an
+ * extensible interface for arbitrary transformations. Nevertheless, these
+ * must be implemented in the transform() functions of inheriting classes in
+ * order to work.
  *
  * @ingroup mapping
  */
@@ -66,32 +58,23 @@ enum MappingType
 /// Mapping of the gradient of a contravariant vector field (see Mapping::transform() for details)
   mapping_contravariant_gradient = 0x0004,
   /**
-   * The Piola transform usually used for Hdiv elements.
-   * Piola transform is the
-   * standard transformation of
-   * vector valued elements in
-   * H<sup>div</sup>. It amounts
-   * to a contravariant
-   * transformation scaled by the
-   * inverse of the volume
-   * element.
+   * The Piola transform usually used for Hdiv elements. Piola transform is
+   * the standard transformation of vector valued elements in H<sup>div</sup>.
+   * It amounts to a contravariant transformation scaled by the inverse of the
+   * volume element.
    */
   mapping_piola = 0x0100,
   /**
-     transformation for the gradient of a vector field corresponding to a
-     mapping_piola transformation (see Mapping::transform() for details).
-  */
+   * transformation for the gradient of a vector field corresponding to a
+   * mapping_piola transformation (see Mapping::transform() for details).
+   */
 
   mapping_piola_gradient = 0x0101,
 /// The mapping used for Nedelec elements
   /**
-   * curl-conforming elements are
-   * mapped as covariant
-   * vectors. Nevertheless, we
-   * introduce a separate mapping
-   * type, such that we can use
-   * the same flag for the vector
-   * and its gradient (see Mapping::transform() for details).
+   * curl-conforming elements are mapped as covariant vectors. Nevertheless,
+   * we introduce a separate mapping type, such that we can use the same flag
+   * for the vector and its gradient (see Mapping::transform() for details).
    */
   mapping_nedelec = 0x0200,
 /// The mapping used for Raviart-Thomas elements
@@ -104,29 +87,26 @@ enum MappingType
 /**
  * Abstract base class for mapping classes.
  *
- * The interface for filling the tables of FEValues is provided.
- * Everything else has to happen in derived classes.
+ * The interface for filling the tables of FEValues is provided. Everything
+ * else has to happen in derived classes.
  *
- * The following paragraph applies to the implementation of
- * FEValues. Usage of the class is as follows: first, call the
- * functions @p update_once and @p update_each with the update
- * flags you need. This includes the flags needed by the
- * FiniteElement. Then call <tt>get_*_data</tt> and with the or'd
- * results.  This will initialize and return some internal data
- * structures.  On the first cell, call <tt>fill_fe_*_values</tt> with the
- * result of @p update_once. Finally, on each cell, use
- * <tt>fill_fe_*_values</tt> with the result of @p update_each to compute
- * values for a special cell.
+ * The following paragraph applies to the implementation of FEValues. Usage of
+ * the class is as follows: first, call the functions @p update_once and @p
+ * update_each with the update flags you need. This includes the flags needed
+ * by the FiniteElement. Then call <tt>get_*_data</tt> and with the or'd
+ * results.  This will initialize and return some internal data structures.
+ * On the first cell, call <tt>fill_fe_*_values</tt> with the result of @p
+ * update_once. Finally, on each cell, use <tt>fill_fe_*_values</tt> with the
+ * result of @p update_each to compute values for a special cell.
  *
  * <h3>Mathematics of the mapping</h3>
  *
- * The mapping is a transformation $\mathbf x = \Phi(\mathbf{\hat x})$
- * which maps the reference cell [0,1]<sup>dim</sup> to the actual
- * grid cell in R<sup>spacedim</sup>.
- * In order to describe the application of the mapping to
- * different objects, we introduce the notation for the Jacobian
- * $J(\mathbf{\hat x}) = \nabla\Phi(\mathbf{\hat x})$. For instance,
- * if dim=spacedim=2, we have
+ * The mapping is a transformation $\mathbf x = \Phi(\mathbf{\hat x})$ which
+ * maps the reference cell [0,1]<sup>dim</sup> to the actual grid cell in
+ * R<sup>spacedim</sup>. In order to describe the application of the mapping
+ * to different objects, we introduce the notation for the Jacobian
+ * $J(\mathbf{\hat x}) = \nabla\Phi(\mathbf{\hat x})$. For instance, if
+ * dim=spacedim=2, we have
  * @f[
  * J(\mathbf{\hat x}) = \left(\begin{matrix}
  * \frac{\partial x}{\partial \hat x} & \frac{\partial x}{\partial \hat y}
@@ -142,12 +122,12 @@ enum MappingType
  * u(\mathbf x) = u\bigl(\Phi(\mathbf{\hat x})\bigr)
  * = \hat u(\mathbf{\hat x}).
  * @f]
- * Since finite element shape functions are usually defined on the
- * reference cell, nothing needs to be done for them. For a function
- * defined on the computational domain, the quadrature points need to
- * be mapped, which is done in fill_fe_values() if
- * @p update_quadrature_points is set in the update flags. The mapped
- * quadrature points are then accessed through FEValuesBase::quadrature_point().
+ * Since finite element shape functions are usually defined on the reference
+ * cell, nothing needs to be done for them. For a function defined on the
+ * computational domain, the quadrature points need to be mapped, which is
+ * done in fill_fe_values() if @p update_quadrature_points is set in the
+ * update flags. The mapped quadrature points are then accessed through
+ * FEValuesBase::quadrature_point().
  *
  * @todo Add a function <tt>transform_quadrature_points</tt> for this.
  *
@@ -161,20 +141,19 @@ enum MappingType
  * @f]
  *
  * The transformed quadrature weights $\left|\text{det}J(\mathbf{\hat
- * x})\right|$ are accessed through FEValuesBase::JxW() and
- * computed in fill_fe_values(), if @p update_JxW_values is set in the
- * update flags.
+ * x})\right|$ are accessed through FEValuesBase::JxW() and computed in
+ * fill_fe_values(), if @p update_JxW_values is set in the update flags.
  *
- * @todo Add a function <tt>transform_quadrature_weights</tt> for
- * this.
+ * @todo Add a function <tt>transform_quadrature_weights</tt> for this.
  *
  * @todo Add documentation on the codimension-one case
  *
- * <h4>Mapping of vector fields, differential forms and gradients of vector fields</h4>
+ * <h4>Mapping of vector fields, differential forms and gradients of vector
+ * fields</h4>
  *
- * The transfomation of vector fields, differential forms (gradients/jacobians) and
- * gradients of vector fields between the reference cell and the actual grid cell
- * follows the general form
+ * The transfomation of vector fields, differential forms
+ * (gradients/jacobians) and gradients of vector fields between the reference
+ * cell and the actual grid cell follows the general form
  *
  * @f[
  * \mathbf v(\mathbf x) = \mathbf A(\mathbf{\hat x})
@@ -184,39 +163,35 @@ enum MappingType
  * \mathbf{\hat T}(\mathbf{\hat x}) \mathbf B(\mathbf{\hat x}),
  * @f]
  *
- * where <b>v</b> is a vector field or a differential form and
- * and <b>T</b> a tensor field of gradients.
- * The differential forms <b>A</b> and <b>B</b> are
- * determined by the MappingType enumerator.
- * These transformations are performed through the functions
- * transform(). See the documentation there for possible
- * choices.
+ * where <b>v</b> is a vector field or a differential form and and <b>T</b> a
+ * tensor field of gradients. The differential forms <b>A</b> and <b>B</b> are
+ * determined by the MappingType enumerator. These transformations are
+ * performed through the functions transform(). See the documentation there
+ * for possible choices.
  *
  * <h3>Technical notes</h3>
  *
- * A hint to implementators: no function except the two functions
- * @p update_once and @p update_each may add any flags.
+ * A hint to implementators: no function except the two functions @p
+ * update_once and @p update_each may add any flags.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * <h3>References</h3>
  *
- * A general publication on differential geometry and finite elements
- * is the survey
+ * A general publication on differential geometry and finite elements is the
+ * survey
  * <ul>
- * <li>Douglas N. Arnold, Richard S. Falk, and
- * Ragnar Winther. <i>Finite element exterior calculus: from
- * Hodge theory to numerical stability.</i>
+ * <li>Douglas N. Arnold, Richard S. Falk, and Ragnar Winther. <i>Finite
+ * element exterior calculus: from Hodge theory to numerical stability.</i>
  * Bull. Amer. Math. Soc. (N.S.), 47:281-354, 2010. <a
  * href="http://dx.doi.org/10.1090/S0273-0979-10-01278-4">DOI:
  * 10.1090/S0273-0979-10-01278-4</a>.
  * </ul>
  *
  * The description of the Piola transform has been taken from the <a
- * href="http://www.math.uh.edu/~rohop/spring_05/downloads/">lecture
- * notes</a> by Ronald H. W. Hoppe, University of Houston, Chapter 7.
+ * href="http://www.math.uh.edu/~rohop/spring_05/downloads/">lecture notes</a>
+ * by Ronald H. W. Hoppe, University of Houston, Chapter 7.
  *
  * @ingroup mapping
  * @author Guido Kanschat, Ralf Hartmann 2000, 2001
@@ -232,10 +207,8 @@ public:
   virtual ~Mapping ();
 
   /**
-   * Transforms the point @p p on
-   * the unit cell to the point
-   * @p p_real on the real cell
-   * @p cell and returns @p p_real.
+   * Transforms the point @p p on the unit cell to the point @p p_real on the
+   * real cell @p cell and returns @p p_real.
    */
   virtual Point<spacedim>
   transform_unit_to_real_cell (
@@ -243,42 +216,23 @@ public:
     const Point<dim>                                 &p) const = 0;
 
   /**
-   * Transforms the point @p p on
-   * the real @p cell to the corresponding
-   * point on the unit cell, and
-   * return its coordinates.
+   * Transforms the point @p p on the real @p cell to the corresponding point
+   * on the unit cell, and return its coordinates.
    *
-   * In the codimension one case,
-   * this function returns the
-   * normal projection of the real
-   * point @p p on the curve or
-   * surface identified by the @p
-   * cell.
+   * In the codimension one case, this function returns the normal projection
+   * of the real point @p p on the curve or surface identified by the @p cell.
    *
-   * @note Polynomial mappings from
-   * the reference (unit) cell coordinates
-   * to the coordinate system of a real
-   * cell are not always invertible if
-   * the point for which the inverse
-   * mapping is to be computed lies
-   * outside the cell's boundaries.
-   * In such cases, the current function
-   * may fail to compute a point on
-   * the reference cell whose image
-   * under the mapping equals the given
-   * point @p p.  If this is the case
-   * then this function throws an
-   * exception of type
-   * Mapping::ExcTransformationFailed .
-   * Whether the given point @p p lies
-   * outside the cell can therefore be
-   * determined by checking whether the
-   * return reference coordinates lie
-   * inside of outside the reference
-   * cell (e.g., using
-   * GeometryInfo::is_inside_unit_cell)
-   * or whether the exception mentioned
-   * above has been thrown.
+   * @note Polynomial mappings from the reference (unit) cell coordinates to
+   * the coordinate system of a real cell are not always invertible if the
+   * point for which the inverse mapping is to be computed lies outside the
+   * cell's boundaries. In such cases, the current function may fail to
+   * compute a point on the reference cell whose image under the mapping
+   * equals the given point @p p.  If this is the case then this function
+   * throws an exception of type Mapping::ExcTransformationFailed . Whether
+   * the given point @p p lies outside the cell can therefore be determined by
+   * checking whether the return reference coordinates lie inside of outside
+   * the reference cell (e.g., using GeometryInfo::is_inside_unit_cell) or
+   * whether the exception mentioned above has been thrown.
    */
   virtual Point<dim>
   transform_real_to_unit_cell (
@@ -286,40 +240,19 @@ public:
     const Point<spacedim>                            &p) const = 0;
 
   /**
-   * Base class for internal data
-   * of finite element and mapping
-   * objects. The internal
-   * mechanism is that upon
-   * construction of a @p FEValues
-   * objects, it asks the mapping
-   * and finite element classes
-   * that are to be used to
-   * allocate memory for their own
-   * purpose in which they may
-   * store data that only needs to
-   * be computed once. For example,
-   * most finite elements will
-   * store the values of the shape
-   * functions at the quadrature
-   * points in this object, since
-   * they do not change from cell
-   * to cell and only need to be
-   * computed once. Since different
-   * @p FEValues objects using
-   * different quadrature rules
-   * might access the same finite
-   * element object at the same
-   * time, it is necessary to
-   * create one such object per
-   * @p FEValues object. Ownership
-   * of this object is then
-   * transferred to the
-   * @p FEValues object, but a
-   * pointer to this object is
-   * passed to the finite element
-   * object every time it shall
-   * compute some data so that it
-   * has access to the precomputed
+   * Base class for internal data of finite element and mapping objects. The
+   * internal mechanism is that upon construction of a @p FEValues objects, it
+   * asks the mapping and finite element classes that are to be used to
+   * allocate memory for their own purpose in which they may store data that
+   * only needs to be computed once. For example, most finite elements will
+   * store the values of the shape functions at the quadrature points in this
+   * object, since they do not change from cell to cell and only need to be
+   * computed once. Since different @p FEValues objects using different
+   * quadrature rules might access the same finite element object at the same
+   * time, it is necessary to create one such object per @p FEValues object.
+   * Ownership of this object is then transferred to the @p FEValues object,
+   * but a pointer to this object is passed to the finite element object every
+   * time it shall compute some data so that it has access to the precomputed
    * values stored there.
    */
   class InternalDataBase: public Subscriptor
@@ -332,100 +265,69 @@ public:
 
   public:
     /**
-     * Constructor. Sets
-     * @p UpdateFlags to
-     * @p update_default and
-     * @p first_cell to @p true.
+     * Constructor. Sets @p UpdateFlags to @p update_default and @p first_cell
+     * to @p true.
      */
     InternalDataBase ();
 
     /**
-     * Virtual destructor for
-     * derived classes
+     * Virtual destructor for derived classes
      */
     virtual ~InternalDataBase ();
 
     /**
-     * Values updated by the constructor or
-     * by reinit.
+     * Values updated by the constructor or by reinit.
      */
     UpdateFlags          update_flags;
 
     /**
-     * Values computed by
-     * constructor.
+     * Values computed by constructor.
      */
     UpdateFlags          update_once;
 
     /**
-     * Values updated on each
-     * cell by reinit.
+     * Values updated on each cell by reinit.
      */
     UpdateFlags          update_each;
 
     /**
-     * If <tt>first_cell==true</tt>
-     * this function returns
-     * @p update_flags,
-     * i.e. <tt>update_once|update_each</tt>.
-     * If <tt>first_cell==false</tt>
-     * it returns
-     * @p update_each.
+     * If <tt>first_cell==true</tt> this function returns @p update_flags,
+     * i.e. <tt>update_once|update_each</tt>. If <tt>first_cell==false</tt> it
+     * returns @p update_each.
      */
     UpdateFlags  current_update_flags() const;
 
     /**
-     * Return whether we are
-     * presently initializing
-     * data for the first
-     * cell. The value of the
-     * field this function is
-     * returning is set to
-     * @p true in the
-     * constructor, and cleared
-     * by the @p FEValues class
-     * after the first cell has
-     * been initialized.
+     * Return whether we are presently initializing data for the first cell.
+     * The value of the field this function is returning is set to @p true in
+     * the constructor, and cleared by the @p FEValues class after the first
+     * cell has been initialized.
      *
-     * This function is used to
-     * determine whether we need
-     * to use the @p update_once
-     * flags for computing data,
-     * or whether we can use the
-     * @p update_each flags.
+     * This function is used to determine whether we need to use the @p
+     * update_once flags for computing data, or whether we can use the @p
+     * update_each flags.
      */
     bool is_first_cell () const;
 
     /**
-     * Set the @p first_cell
-     * flag to @p false. Used by
-     * the @p FEValues class to
-     * indicate that we have
-     * already done the work on
-     * the first cell.
+     * Set the @p first_cell flag to @p false. Used by the @p FEValues class
+     * to indicate that we have already done the work on the first cell.
      */
     virtual void clear_first_cell ();
 
     /**
-     * Return an estimate (in
-     * bytes) or the memory
-     * consumption of this
-     * object.
+     * Return an estimate (in bytes) or the memory consumption of this object.
      */
     virtual std::size_t memory_consumption () const;
 
     /**
-     * The determinant of the
-     * Jacobian in each
-     * quadrature point. Filled
-     * if #update_volume_elements.
+     * The determinant of the Jacobian in each quadrature point. Filled if
+     * #update_volume_elements.
      */
     std::vector<double> volume_elements;
 
     /**
-     * The positions of the
-     * mapped (generalized)
-     * support points.
+     * The positions of the mapped (generalized) support points.
      */
     std::vector<Point<spacedim> > support_point_values;
 
@@ -449,20 +351,19 @@ public:
 
   private:
     /**
-     * The value returned by
-     * @p is_first_cell.
+     * The value returned by @p is_first_cell.
      */
     bool first_cell;
   };
 
   /**
-   * Transform a field of vectors or 1-differential forms according to the selected
-   * MappingType.
+   * Transform a field of vectors or 1-differential forms according to the
+   * selected MappingType.
    *
-   * @note Normally, this function is called by a finite element,
-   * filling FEValues objects. For this finite element, there should be
-   * an alias MappingType like @p mapping_bdm, @p mapping_nedelec, etc. This
-   * alias should be preferred to using the types below.
+   * @note Normally, this function is called by a finite element, filling
+   * FEValues objects. For this finite element, there should be an alias
+   * MappingType like @p mapping_bdm, @p mapping_nedelec, etc. This alias
+   * should be preferred to using the types below.
    *
    * The mapping types currently implemented by derived classes are:
    * <ul>
@@ -472,14 +373,13 @@ public:
    * \mathbf u(\mathbf x) = J(\mathbf{\hat x})\mathbf{\hat u}(\mathbf{\hat x}).
    * @f]
    * In physics, this is usually referred to as the contravariant
-   * transformation. Mathematically, it is the push forward of a
-   * vector field.
+   * transformation. Mathematically, it is the push forward of a vector field.
    *
-   * <li> @p mapping_covariant: maps a field of one-forms on the reference cell
-   * to a field of one-forms on the physical cell.
-   * (theoretically this would refer to a DerivativeForm<1, dim, 1> but it
-   * canonically identified with a Tensor<1,dim>).
-   * Mathematically, it is the pull back of the differential form
+   * <li> @p mapping_covariant: maps a field of one-forms on the reference
+   * cell to a field of one-forms on the physical cell. (theoretically this
+   * would refer to a DerivativeForm<1, dim, 1> but it canonically identified
+   * with a Tensor<1,dim>). Mathematically, it is the pull back of the
+   * differential form
    * @f[
    * \mathbf u(\mathbf x) = J(J^{T} J)^{-1}(\mathbf{\hat x})\mathbf{\hat
    * u}(\mathbf{\hat x}).
@@ -491,8 +391,8 @@ public:
    * @f]
    * Gradients of scalar differentiable functions are transformed this way.
    *
-   * <li> @p mapping_piola: A field of <i>n-1</i>-forms on the reference cell is also
-   * represented by a vector field, but again transforms differently,
+   * <li> @p mapping_piola: A field of <i>n-1</i>-forms on the reference cell
+   * is also represented by a vector field, but again transforms differently,
    * namely by the Piola transform
    * @f[
    *  \mathbf u(\mathbf x) = \frac{1}{\text{det}J(\mathbf x)}
@@ -512,34 +412,33 @@ public:
 
 
   /**
-     Transform a field of differential forms from the reference cell to the physical cell.
-
-     It is useful to think of $\mathbf{T} = D \mathbf u$ and
-     $\mathbf{\hat T} = \hat D \mathbf{\hat u}$, with $\mathbf u$ a vector field.
-
-     The mapping types currently implemented by derived classes are:
-     <ul>
-     <li> @p mapping_covariant: maps a field of forms on the reference cell
-     to a field of forms on the physical cell.
-     Mathematically, it is the pull back of the differential form
-     @f[
-     \mathbf T(\mathbf x) = \mathbf{\hat T}(\mathbf{\hat x})
-                            J*(J^{T} J)^{-1}(\mathbf{\hat x}).
-     @f]
-     n the case when dim=spacedim the previous formula reduces to
-     @f[
-     \mathbf T(\mathbf x) = \mathbf{\hat u}(\mathbf{\hat x})
-                            J^{-1}(\mathbf{\hat x}).
-     @f]
-    Jacobians of spacedim-vector valued differentiable functions are transformed this way.
-     </ul>
-
-     @note It would have been more reasonable to make this transform a template function
-     with the rank in <code>DerivativeForm@<1, dim, rank@></code>. Unfortunately C++ does not
-     allow templatized virtual functions. This is why we identify
-     <code>DerivativeForm@<1, dim, 1@></code> with a <code>Tensor@<1,dim@></code>
-     when using  mapping_covariant() in the function transform above this one.
-  */
+   * Transform a field of differential forms from the reference cell to the
+   * physical cell.  It is useful to think of $\mathbf{T} = D \mathbf u$ and
+   * $\mathbf{\hat T} = \hat D \mathbf{\hat u}$, with $\mathbf u$ a vector
+   * field.  The mapping types currently implemented by derived classes are:
+   * <ul>
+   * <li> @p mapping_covariant: maps a field of forms on the reference cell to
+   * a field of forms on the physical cell. Mathematically, it is the pull
+   * back of the differential form
+   * @f[
+   * \mathbf T(\mathbf x) = \mathbf{\hat T}(\mathbf{\hat x})
+   *                        J*(J^{T} J)^{-1}(\mathbf{\hat x}).
+   * @f]
+   * n the case when dim=spacedim the previous formula reduces to
+   * @f[
+   * \mathbf T(\mathbf x) = \mathbf{\hat u}(\mathbf{\hat x})
+   *                        J^{-1}(\mathbf{\hat x}).
+   * @f]
+   * Jacobians of spacedim-vector valued differentiable functions are
+   * transformed this way.
+   * </ul>
+   *  @note It would have been more reasonable to make this transform a
+   * template function with the rank in <code>DerivativeForm@<1, dim,
+   * rank@></code>. Unfortunately C++ does not allow templatized virtual
+   * functions. This is why we identify <code>DerivativeForm@<1, dim,
+   * 1@></code> with a <code>Tensor@<1,dim@></code> when using
+   * mapping_covariant() in the function transform above this one.
+   */
 
   virtual
   void
@@ -551,47 +450,41 @@ public:
 
 
   /**
-     Transform a tensor field from the reference cell to the physical cell.
-     This tensors are most of times the jacobians in the reference cell of
-     vector fields that have been pulled back from the physical cell.
-
-     The mapping types currently implemented by derived classes are:
-     <ul>
-
-     <li> @p mapping_contravariant_gradient, it
-     assumes $\mathbf u(\mathbf x) = J \mathbf{\hat u}$ so that
-     @f[
-     \mathbf T(\mathbf x) =
-     J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
-     J^{-1}(\mathbf{\hat x}).
-     @f]
-
-     <li> @p mapping_covariant_gradient, it
-     assumes $\mathbf u(\mathbf x) = J^{-T} \mathbf{\hat u}$ so that
-     @f[
-     \mathbf T(\mathbf x) =
-     J^{-T}(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
-     J^{-1}(\mathbf{\hat x}).
-     @f]
-
-     <li> @p mapping_piola_gradient, it
-     assumes $\mathbf u(\mathbf x) = \frac{1}{\text{det}J(\mathbf x)}
-     J(\mathbf x) \mathbf{\hat u}(\mathbf x)$
-     so that
-     @f[
-     \mathbf T(\mathbf x) =
-     \frac{1}{\text{det}J(\mathbf x)}
-     J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
-     J^{-1}(\mathbf{\hat x}).
-     @f]
-     </ul>
-
-     @todo The formulas for mapping_covariant_gradient(),
-     mapping_contravariant_gradient() and mapping_piola_gradient()
-     are only true as stated for linear mappings.
-     If, for example, the mapping is bilinear then there is a missing
-     term associated with the derivative of J.
-  */
+   * Transform a tensor field from the reference cell to the physical cell.
+   * This tensors are most of times the jacobians in the reference cell of
+   * vector fields that have been pulled back from the physical cell.  The
+   * mapping types currently implemented by derived classes are:
+   * <ul>
+   * <li> @p mapping_contravariant_gradient, it assumes $\mathbf u(\mathbf x)
+   * = J \mathbf{\hat u}$ so that
+   * @f[
+   * \mathbf T(\mathbf x) =
+   * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+   * J^{-1}(\mathbf{\hat x}).
+   * @f]
+   * <li> @p mapping_covariant_gradient, it assumes $\mathbf u(\mathbf x) =
+   * J^{-T} \mathbf{\hat u}$ so that
+   * @f[
+   * \mathbf T(\mathbf x) =
+   * J^{-T}(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+   * J^{-1}(\mathbf{\hat x}).
+   * @f]
+   * <li> @p mapping_piola_gradient, it assumes $\mathbf u(\mathbf x) =
+   * \frac{1}{\text{det}J(\mathbf x)} J(\mathbf x) \mathbf{\hat u}(\mathbf x)$
+   * so that
+   * @f[
+   * \mathbf T(\mathbf x) =
+   * \frac{1}{\text{det}J(\mathbf x)}
+   * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+   * J^{-1}(\mathbf{\hat x}).
+   * @f]
+   * </ul>
+   *  @todo The formulas for mapping_covariant_gradient(),
+   * mapping_contravariant_gradient() and mapping_piola_gradient() are only
+   * true as stated for linear mappings. If, for example, the mapping is
+   * bilinear then there is a missing term associated with the derivative of
+   * J.
+   */
   virtual
   void
   transform (const VectorSlice<const std::vector<Tensor<2, dim> > >     input,
@@ -637,17 +530,14 @@ public:
                            const typename Mapping<dim,spacedim>::InternalDataBase &internal) const DEAL_II_DEPRECATED;
 
   /**
-   * The transformed (generalized)
-   * support point.
+   * The transformed (generalized) support point.
    */
   const Point<spacedim> &support_point_value(
     const unsigned int index,
     const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
 
   /**
-   * The Jacobian
-   * matrix of the transformation
-   * in the (generalized) support
+   * The Jacobian matrix of the transformation in the (generalized) support
    * point.
    */
   const Tensor<2,spacedim> &support_point_gradient(
@@ -655,44 +545,33 @@ public:
     const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
 
   /**
-   * The inverse Jacobian
-   * matrix of the transformation
-   * in the (generalized) support
-   * point.
+   * The inverse Jacobian matrix of the transformation in the (generalized)
+   * support point.
    */
   const Tensor<2,spacedim> &support_point_inverse_gradient(
     const unsigned int index,
     const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
 
   /**
-   * Return a pointer to a copy of the
-   * present object. The caller of this
-   * copy then assumes ownership of it.
+   * Return a pointer to a copy of the present object. The caller of this copy
+   * then assumes ownership of it.
    *
-   * Since one can't create
-   * objects of class Mapping, this
-   * function of course has to be
-   * implemented by derived classes.
+   * Since one can't create objects of class Mapping, this function of course
+   * has to be implemented by derived classes.
    *
-   * This function is mainly used by the
-   * hp::MappingCollection class.
+   * This function is mainly used by the hp::MappingCollection class.
    */
   virtual
   Mapping<dim,spacedim> *clone () const = 0;
 
   /**
-   * Returns whether the mapping preserves
-   * vertex locations, i.e. whether the
-   * mapped location of the reference cell
-   * vertices (given by
-   * GeometryInfo::unit_cell_vertex())
-   * equals the result of
+   * Returns whether the mapping preserves vertex locations, i.e. whether the
+   * mapped location of the reference cell vertices (given by
+   * GeometryInfo::unit_cell_vertex()) equals the result of
    * <code>cell-@>vertex()</code>.
    *
-   * For example, implementations in
-   * derived classes return @p true for
-   * MappingQ, MappingQ1, MappingCartesian,
-   * but @p false for MappingQEulerian,
+   * For example, implementations in derived classes return @p true for
+   * MappingQ, MappingQ1, MappingCartesian, but @p false for MappingQEulerian,
    * MappingQ1Eulerian.
    */
   virtual
@@ -705,11 +584,9 @@ public:
 
 
   /**
-   * Computing the mapping between a
-   * real space point and a point
-   * in reference space failed, typically because the given point
-   * lies outside the cell where the inverse mapping is not
-   * unique.
+   * Computing the mapping between a real space point and a point in reference
+   * space failed, typically because the given point lies outside the cell
+   * where the inverse mapping is not unique.
    *
    * @ingroup Exceptions
    */
@@ -733,52 +610,41 @@ public:
 private:
 
   /**
-   * Indicate fields to be updated
-   * in the constructor of
-   * FEValues. Especially,
-   * fields not asked for by
-   * FEValues, but computed
-   * for efficiency reasons will be
-   * notified here.
+   * Indicate fields to be updated in the constructor of FEValues. Especially,
+   * fields not asked for by FEValues, but computed for efficiency reasons
+   * will be notified here.
    *
    * See @ref UpdateFlagsEssay.
    */
   virtual UpdateFlags update_once (const UpdateFlags) const = 0;
 
   /**
-   * The same as update_once(),
-   * but for the flags to be updated for
-   * each grid cell.
+   * The same as update_once(), but for the flags to be updated for each grid
+   * cell.
    *
    * See @ref UpdateFlagsEssay.
    */
   virtual UpdateFlags update_each (const UpdateFlags) const = 0;
 
   /**
-   * Prepare internal data
-   * structures and fill in values
-   * independent of the cell.
+   * Prepare internal data structures and fill in values independent of the
+   * cell.
    */
   virtual InternalDataBase *
   get_data (const UpdateFlags,
             const Quadrature<dim> &quadrature) const = 0;
 
   /**
-   * Prepare internal data
-   * structure for transformation
-   * of faces and fill in values
-   * independent of the cell.
+   * Prepare internal data structure for transformation of faces and fill in
+   * values independent of the cell.
    */
   virtual InternalDataBase *
   get_face_data (const UpdateFlags flags,
                  const Quadrature<dim-1>& quadrature) const = 0;
 
   /**
-   * Prepare internal data
-   * structure for transformation
-   * of children of faces and fill
-   * in values independent of the
-   * cell.
+   * Prepare internal data structure for transformation of children of faces
+   * and fill in values independent of the cell.
    */
   virtual InternalDataBase *
   get_subface_data (const UpdateFlags flags,
@@ -786,32 +652,17 @@ private:
 
 
   /**
-   * Fill the transformation fields
-   * of @p FEValues.  Given a grid
-   * cell and the quadrature points
-   * on the unit cell, it computes
-   * all values specified by
-   * @p flags. The arrays to be
-   * filled have to have the
-   * correct size.
+   * Fill the transformation fields of @p FEValues.  Given a grid cell and the
+   * quadrature points on the unit cell, it computes all values specified by
+   * @p flags. The arrays to be filled have to have the correct size.
    *
-   * Values are split into two
-   * groups: first,
-   * @p quadrature_points and
-   * @p JxW_values are
-   * filled with the quadrature
-   * rule transformed to the
-   * cell in physical space.
+   * Values are split into two groups: first, @p quadrature_points and @p
+   * JxW_values are filled with the quadrature rule transformed to the cell in
+   * physical space.
    *
-   * The second group contains the
-   * matrices needed to transform
-   * vector-valued functions,
-   * namely
-   * @p jacobians,
-   * the derivatives
-   * @p jacobian_grads,
-   * and the inverse operations in
-   * @p inverse_jacobians.
+   * The second group contains the matrices needed to transform vector-valued
+   * functions, namely @p jacobians, the derivatives @p jacobian_grads, and
+   * the inverse operations in @p inverse_jacobians.
    */
   /*     virtual void */
   /*     fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell, */
@@ -820,9 +671,8 @@ private:
   /*                  std::vector<Point<spacedim> >                 &quadrature_points, */
   /*                  std::vector<double>                           &JxW_values) const = 0; */
 
-  /** The function above adjusted
-   * with the variable
-   * cell_normal_vectors for the
+  /**
+   * The function above adjusted with the variable cell_normal_vectors for the
    * case of codimension 1
    */
   virtual void
@@ -841,21 +691,12 @@ private:
 
 
   /**
-   * Performs the same as @p
-   * fill_fe_values on a face.
-   * Additionally, @p boundary_form
-   * (see @ref GlossBoundaryForm)
-   * and @p normal_vectors can be
-   * computed on surfaces. Since
-   * the boundary form already
-   * contains the determinant of
-   * the Jacobian of the
-   * transformation, it is
-   * sometimes more economic to use
-   * the boundary form instead of
-   * the product of the unit normal
-   * and the transformed quadrature
-   * weight.
+   * Performs the same as @p fill_fe_values on a face. Additionally, @p
+   * boundary_form (see @ref GlossBoundaryForm) and @p normal_vectors can be
+   * computed on surfaces. Since the boundary form already contains the
+   * determinant of the Jacobian of the transformation, it is sometimes more
+   * economic to use the boundary form instead of the product of the unit
+   * normal and the transformed quadrature weight.
    */
   virtual void
   fill_fe_face_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -882,10 +723,8 @@ private:
                           std::vector<Point<spacedim> >        &normal_vectors) const = 0;
 
   /**
-   * Give class @p FEValues access
-   * to the private <tt>get_...data</tt>
-   * and <tt>fill_fe_...values</tt>
-   * functions.
+   * Give class @p FEValues access to the private <tt>get_...data</tt> and
+   * <tt>fill_fe_...values</tt> functions.
    */
   friend class FEValuesBase<dim,spacedim>;
   friend class FEValues<dim,spacedim>;
index c8647c83875509a2ca67d59aee2f8d8d9a395a30..fb71695e973c6b24c8b17b5d874fbe19204df534 100644 (file)
@@ -26,21 +26,18 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Mapping class that uses C1 (continuously differentiable) cubic
- * mappings of the boundary. This class is built atop of
- * MappingQ by simply determining the interpolation points for a
- * cubic mapping of the boundary differently: MappingQ chooses
- * them such that they interpolate the boundary, while this class
- * chooses them such that the discretized boundary is globally
+ * Mapping class that uses C1 (continuously differentiable) cubic mappings of
+ * the boundary. This class is built atop of MappingQ by simply determining
+ * the interpolation points for a cubic mapping of the boundary differently:
+ * MappingQ chooses them such that they interpolate the boundary, while this
+ * class chooses them such that the discretized boundary is globally
  * continuously differentiable.
  *
- * To use this class, make sure that the
- * Boundary::@p get_normals_at_vertices function is implemented
- * for the user's boundary object.
+ * To use this class, make sure that the Boundary::@p get_normals_at_vertices
+ * function is implemented for the user's boundary object.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * @author Wolfgang Bangerth, 2001
  */
@@ -67,8 +64,8 @@ protected:
    * located on bounding lines to the vector @p a. Points located on the line
    * but on vertices are not included.
    *
-   * Needed by the <tt>compute_support_points_simple(laplace)</tt>
-   * functions. For <tt>dim=1</tt> this function is empty.
+   * Needed by the <tt>compute_support_points_simple(laplace)</tt> functions.
+   * For <tt>dim=1</tt> this function is empty.
    *
    * This function chooses the respective points not such that they are
    * interpolating the boundary (as does the base class), but rather such that
index fb9c3d27dca76f5297dbc2eae35e1f8d5dff1ca1..f4178027ad3e6c68fc177b9002eebc32dbef7d90 100644 (file)
@@ -28,34 +28,25 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * A class providing a mapping from the reference cell to cells that are axiparallel.
+ * A class providing a mapping from the reference cell to cells that are
+ * axiparallel.
  *
- * This class maps the unit cell to a grid cell with surfaces parallel
- * to the coordinate lines/planes. It is specifically developed for
- * Cartesian meshes. In other words, the mapping is meant for cells for which the
- * mapping from the reference to the real cell is a scaling
- * along the coordinate directions: The transformation from reference coordinates
- * $\hat {\mathbf x}$ to real coordinates $\mathbf x$ on each cell is of the
- * form
- * @f{align*}
- *   {\mathbf x}(\hat {\mathbf x})
- *   =
- *   \begin{pmatrix} h_x & 0 \\ 0 & h_y \end{pmatrix}
- *   \hat{\mathbf x} + {\mathbf v}_0
- * @f}
- * in 2d, and
- * @f{align*}
- *   {\mathbf x}(\hat {\mathbf x})
- *   =
- *   \begin{pmatrix} h_x & 0 & 0 \\ 0 & h_y & 0 \\ 0 & 0 & h_z \end{pmatrix}
- *   \hat{\mathbf x} + {\mathbf v}_0
- * @f}
- * in 3d, where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$ are
- * the extents of the cell along the axes.
+ * This class maps the unit cell to a grid cell with surfaces parallel to the
+ * coordinate lines/planes. It is specifically developed for Cartesian meshes.
+ * In other words, the mapping is meant for cells for which the mapping from
+ * the reference to the real cell is a scaling along the coordinate
+ * directions: The transformation from reference coordinates $\hat {\mathbf
+ * x}$ to real coordinates $\mathbf x$ on each cell is of the form @f{align*}
+ * {\mathbf x}(\hat {\mathbf x}) = \begin{pmatrix} h_x & 0 \\ 0 & h_y
+ * \end{pmatrix} \hat{\mathbf x} + {\mathbf v}_0 @f} in 2d, and @f{align*}
+ * {\mathbf x}(\hat {\mathbf x}) = \begin{pmatrix} h_x & 0 & 0 \\ 0 & h_y & 0
+ * \\ 0 & 0 & h_z \end{pmatrix} \hat{\mathbf x} + {\mathbf v}_0 @f} in 3d,
+ * where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$ are the
+ * extents of the cell along the axes.
  *
  * The class is intended for efficiency, and it does not do a whole lot of
- * error checking. If you apply this mapping to a cell that does not conform to
- * the requirements above, you will get strange results.
+ * error checking. If you apply this mapping to a cell that does not conform
+ * to the requirements above, you will get strange results.
  *
  * @author Guido Kanschat, 2001; Ralf Hartmann, 2005
  */
@@ -137,14 +128,10 @@ public:
     const Point<dim>                                 &p) const;
 
   /**
-   * Transforms the point @p p on
-   * the real cell to the point
-   * @p p_unit on the unit cell
-   * @p cell and returns @p p_unit.
+   * Transforms the point @p p on the real cell to the point @p p_unit on the
+   * unit cell @p cell and returns @p p_unit.
    *
-   * Uses Newton iteration and the
-   * @p transform_unit_to_real_cell
-   * function.
+   * Uses Newton iteration and the @p transform_unit_to_real_cell function.
    */
   virtual Point<dim>
   transform_real_to_unit_cell (
@@ -153,24 +140,21 @@ public:
 
 
   /**
-   * Return a pointer to a copy of the
-   * present object. The caller of this
-   * copy then assumes ownership of it.
+   * Return a pointer to a copy of the present object. The caller of this copy
+   * then assumes ownership of it.
    */
   virtual
   Mapping<dim, spacedim> *clone () const;
 
   /**
-   * Always returns @p true because
-   * MappingCartesian preserves vertex
+   * Always returns @p true because MappingCartesian preserves vertex
    * locations.
    */
   bool preserves_vertex_locations () const;
 
 protected:
   /**
-   * Storage for internal data of
-   * the scaling.
+   * Storage for internal data of the scaling.
    */
   class InternalData : public Mapping<dim, spacedim>::InternalDataBase
   {
@@ -181,18 +165,13 @@ protected:
     InternalData (const Quadrature<dim> &quadrature);
 
     /**
-     * Return an estimate (in
-     * bytes) or the memory
-     * consumption of this
-     * object.
+     * Return an estimate (in bytes) or the memory consumption of this object.
      */
     virtual std::size_t memory_consumption () const;
 
     /**
-     * Length of the cell in
-     * different coordinate
-     * directions, <i>h<sub>x</sub></i>,
-     * <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
+     * Length of the cell in different coordinate directions,
+     * <i>h<sub>x</sub></i>, <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
      */
     Tensor<1,dim> length;
 
@@ -202,16 +181,13 @@ protected:
     double volume_element;
 
     /**
-     * Vector of all quadrature
-     * points. Especially, all
-     * points on all faces.
+     * Vector of all quadrature points. Especially, all points on all faces.
      */
     std::vector<Point<dim> > quadrature_points;
   };
 
   /**
-   * Do the computation for the
-   * <tt>fill_*</tt> functions.
+   * Do the computation for the <tt>fill_*</tt> functions.
    */
   void compute_fill (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
                      const unsigned int face_no,
@@ -226,9 +202,7 @@ private:
   virtual UpdateFlags update_each (const UpdateFlags) const;
 
   /**
-   * Value to indicate that a given
-   * face or subface number is
-   * invalid.
+   * Value to indicate that a given face or subface number is invalid.
    */
   static const unsigned int invalid_face_number = numbers::invalid_unsigned_int;
 };
index fe9e6e4990bae1fba1109ea7eef44866687d88e4..a16cd5d43e2e404deaa1aaf661306988a1e65dea 100644 (file)
@@ -39,16 +39,15 @@ template <int dim, typename POLY> class TensorProductPolynomials;
  * are therefore preferred over equidistant support points.
  *
  * For more details about Qp-mappings, see the `mapping' report at
- * <tt>deal.II/doc/reports/mapping_q/index.html</tt> in the `Reports'
- * section of `Documentation'.
+ * <tt>deal.II/doc/reports/mapping_q/index.html</tt> in the `Reports' section
+ * of `Documentation'.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * @note Since the boundary description is closely tied to the unit cell
- * support points, new boundary descriptions need to explicitly use the
- * Gauss-Lobatto points.
+ * support points, new boundary descriptions need to explicitly use the Gauss-
+ * Lobatto points.
  *
  * @author Ralf Hartmann, 2000, 2001, 2005; Guido Kanschat 2000, 2001
  */
@@ -268,13 +267,12 @@ protected:
 
 private:
   /**
-   * Ask the manifold descriptor to return intermediate points on
-   * lines or faces. The function needs to return one or multiple
-   * points (depending on the number of elements in the output vector
-   * @p points that lie inside a line, quad or hex). Whether it is a
-   * line, quad or hex doesn't really matter to this function but it
-   * can be inferred from the number of input points in the @p
-   * surrounding_points vector.
+   * Ask the manifold descriptor to return intermediate points on lines or
+   * faces. The function needs to return one or multiple points (depending on
+   * the number of elements in the output vector @p points that lie inside a
+   * line, quad or hex). Whether it is a line, quad or hex doesn't really
+   * matter to this function but it can be inferred from the number of input
+   * points in the @p surrounding_points vector.
    */
   void get_intermediate_points(const Manifold<dim, spacedim> &manifold,
                                const std::vector<Point<spacedim> > &surrounding_points,
@@ -282,12 +280,12 @@ private:
 
 
   /**
-   * Ask the manifold descriptor to return intermediate points on the
-   * object pointed to by the TriaIterator @p iter. This function
-   * tries to be backward compatible with respect to the differences
-   * between Boundary<dim,spacedim> and Manifold<dim,spacedim>,
-   * querying the first whenever the passed @p manifold can be
-   * upgraded to a Boundary<dim,spacedim>.
+   * Ask the manifold descriptor to return intermediate points on the object
+   * pointed to by the TriaIterator @p iter. This function tries to be
+   * backward compatible with respect to the differences between
+   * Boundary<dim,spacedim> and Manifold<dim,spacedim>, querying the first
+   * whenever the passed @p manifold can be upgraded to a
+   * Boundary<dim,spacedim>.
    */
   template <class TriaIterator>
   void get_intermediate_points_on_object(const Manifold<dim, spacedim> &manifold,
@@ -388,10 +386,9 @@ private:
    * Needed by the @p laplace_on_quad function (for <tt>dim==2</tt>). Filled
    * by the constructor.
    *
-   * Sizes:
-   * laplace_on_quad_vector.size()= number of inner unit_support_points
+   * Sizes: laplace_on_quad_vector.size()= number of inner unit_support_points
    * laplace_on_quad_vector[i].size()= number of outer unit_support_points,
-   *   i.e.  unit_support_points on the boundary of the quad
+   * i.e.  unit_support_points on the boundary of the quad
    *
    * For the definition of this vector see equation (8) of the `mapping'
    * report.
index f3c11f02de51eb45f809e4ed63ebaa78ea480cac..edc1feb9e4e14cc1aa7e22569e78dd2dfd10c518 100644 (file)
@@ -34,21 +34,17 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Mapping of general quadrilateral/hexahedra by d-linear shape
- * functions.
+ * Mapping of general quadrilateral/hexahedra by d-linear shape functions.
  *
- * This function maps the unit cell to a general grid cell with
- * straight lines in $d$ dimensions (remark that in 3D the surfaces
- * may be curved, even if the edges are not). This is the well-known
- * mapping for polyhedral domains.
+ * This function maps the unit cell to a general grid cell with straight lines
+ * in $d$ dimensions (remark that in 3D the surfaces may be curved, even if
+ * the edges are not). This is the well-known mapping for polyhedral domains.
  *
- * Shape function for this mapping are the same as for the finite
- * element FE_Q of order 1. Therefore, coupling these two yields
- * an isoparametric element.
+ * Shape function for this mapping are the same as for the finite element FE_Q
+ * of order 1. Therefore, coupling these two yields an isoparametric element.
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * @author Guido Kanschat, 2000, 2001; Ralf Hartmann, 2000, 2001, 2005
  */
@@ -67,46 +63,25 @@ public:
     const Point<dim>                                 &p) const;
 
   /**
-   * Transforms the point @p p on
-   * the real cell to the point
-   * @p p_unit on the unit cell
-   * @p cell and returns @p p_unit.
+   * Transforms the point @p p on the real cell to the point @p p_unit on the
+   * unit cell @p cell and returns @p p_unit.
    *
-   * Uses Newton iteration and the
-   * @p transform_unit_to_real_cell
-   * function.
+   * Uses Newton iteration and the @p transform_unit_to_real_cell function.
    *
-   * In the codimension one case,
-   * this function returns the
-   * normal projection of the real
-   * point @p p on the curve or
-   * surface identified by the @p
-   * cell.
+   * In the codimension one case, this function returns the normal projection
+   * of the real point @p p on the curve or surface identified by the @p cell.
    *
-   * @note Polynomial mappings from
-   * the reference (unit) cell coordinates
-   * to the coordinate system of a real
-   * cell are not always invertible if
-   * the point for which the inverse
-   * mapping is to be computed lies
-   * outside the cell's boundaries.
-   * In such cases, the current function
-   * may fail to compute a point on
-   * the reference cell whose image
-   * under the mapping equals the given
-   * point @p p.  If this is the case
-   * then this function throws an
-   * exception of type
-   * Mapping::ExcTransformationFailed .
-   * Whether the given point @p p lies
-   * outside the cell can therefore be
-   * determined by checking whether the
-   * return reference coordinates lie
-   * inside of outside the reference
-   * cell (e.g., using
-   * GeometryInfo::is_inside_unit_cell)
-   * or whether the exception mentioned
-   * above has been thrown.
+   * @note Polynomial mappings from the reference (unit) cell coordinates to
+   * the coordinate system of a real cell are not always invertible if the
+   * point for which the inverse mapping is to be computed lies outside the
+   * cell's boundaries. In such cases, the current function may fail to
+   * compute a point on the reference cell whose image under the mapping
+   * equals the given point @p p.  If this is the case then this function
+   * throws an exception of type Mapping::ExcTransformationFailed . Whether
+   * the given point @p p lies outside the cell can therefore be determined by
+   * checking whether the return reference coordinates lie inside of outside
+   * the reference cell (e.g., using GeometryInfo::is_inside_unit_cell) or
+   * whether the exception mentioned above has been thrown.
    */
   virtual Point<dim>
   transform_real_to_unit_cell (
@@ -135,10 +110,10 @@ public:
 
 protected:
   /**
-     This function and the next allow to generate the transform require by
-     the virtual transform() in mapping, but unfortunately in C++ one cannot
-     declare a virtual template function.
-  */
+   * This function and the next allow to generate the transform require by the
+   * virtual transform() in mapping, but unfortunately in C++ one cannot
+   * declare a virtual template function.
+   */
   template < int rank >
   void
   transform_fields(const VectorSlice<const std::vector<Tensor<rank,dim>      > > input,
@@ -146,8 +121,8 @@ protected:
                    const typename Mapping<dim,spacedim>::InternalDataBase &internal,
                    const MappingType type) const;
   /**
-     see doc in transform_fields
-  */
+   * see doc in transform_fields
+   */
   template < int rank >
   void
   transform_gradients(const VectorSlice<const std::vector<Tensor<rank,dim>      > > input,
@@ -155,8 +130,8 @@ protected:
                       const typename Mapping<dim,spacedim>::InternalDataBase &internal,
                       const MappingType type) const;
   /**
-     see doc in transform_fields
-  */
+   * see doc in transform_fields
+   */
   template < int rank >
   void
   transform_differential_forms(
@@ -171,139 +146,101 @@ public:
 
 
   /**
-   * Return a pointer to a copy of the
-   * present object. The caller of this
-   * copy then assumes ownership of it.
+   * Return a pointer to a copy of the present object. The caller of this copy
+   * then assumes ownership of it.
    */
   virtual
   Mapping<dim,spacedim> *clone () const;
 
   /**
-   * Storage for internal data of
-   * d-linear transformation.
+   * Storage for internal data of d-linear transformation.
    */
   class InternalData : public Mapping<dim,spacedim>::InternalDataBase
   {
   public:
     /**
-     * Constructor. Pass the
-     * number of shape functions.
+     * Constructor. Pass the number of shape functions.
      */
     InternalData(const unsigned int n_shape_functions);
 
     /**
-     * Shape function at quadrature
-     * point. Shape functions are
-     * in tensor product order, so
-     * vertices must be reordered
-     * to obtain transformation.
+     * Shape function at quadrature point. Shape functions are in tensor
+     * product order, so vertices must be reordered to obtain transformation.
      */
     double shape (const unsigned int qpoint,
                   const unsigned int shape_nr) const;
 
     /**
-     * Shape function at quadrature
-     * point. See above.
+     * Shape function at quadrature point. See above.
      */
     double &shape (const unsigned int qpoint,
                    const unsigned int shape_nr);
 
     /**
-     * Gradient of shape function
-     * in quadrature point. See
-     * above.
+     * Gradient of shape function in quadrature point. See above.
      */
     Tensor<1,dim> derivative (const unsigned int qpoint,
                               const unsigned int shape_nr) const;
 
     /**
-     * Gradient of shape function
-     * in quadrature point. See
-     * above.
+     * Gradient of shape function in quadrature point. See above.
      */
     Tensor<1,dim> &derivative (const unsigned int qpoint,
                                const unsigned int shape_nr);
 
     /**
-     * Second derivative of shape
-     * function in quadrature
-     * point. See above.
+     * Second derivative of shape function in quadrature point. See above.
      */
     Tensor<2,dim> second_derivative (const unsigned int qpoint,
                                      const unsigned int shape_nr) const;
 
     /**
-     * Second derivative of shape
-     * function in quadrature
-     * point. See above.
+     * Second derivative of shape function in quadrature point. See above.
      */
     Tensor<2,dim> &second_derivative (const unsigned int qpoint,
                                       const unsigned int shape_nr);
 
     /**
-     * Return an estimate (in
-     * bytes) or the memory
-     * consumption of this
-     * object.
+     * Return an estimate (in bytes) or the memory consumption of this object.
      */
     virtual std::size_t memory_consumption () const;
 
     /**
-     * Values of shape
-     * functions. Access by
-     * function @p shape.
+     * Values of shape functions. Access by function @p shape.
      *
      * Computed once.
      */
     std::vector<double> shape_values;
 
     /**
-     * Values of shape function
-     * derivatives. Access by
-     * function @p derivative.
+     * Values of shape function derivatives. Access by function @p derivative.
      *
      * Computed once.
      */
     std::vector<Tensor<1,dim> > shape_derivatives;
 
     /**
-     * Values of shape function
-     * second derivatives. Access
-     * by function
-     * @p second_derivative.
+     * Values of shape function second derivatives. Access by function @p
+     * second_derivative.
      *
      * Computed once.
      */
     std::vector<Tensor<2,dim> > shape_second_derivatives;
 
     /**
-     * Tensors of covariant
-     * transformation at each of
-     * the quadrature points. The
-     * matrix stored is the
-     * Jacobian * G^{-1},
-     * where G = Jacobian^{t} * Jacobian,
-     * is the first fundamental
-     * form of the map;
-     * if dim=spacedim then
-     * it reduces to the transpose of the
-     * inverse of the Jacobian
-     * matrix, which itself is
-     * stored in the
-     * @p contravariant field of
-     * this structure.
+     * Tensors of covariant transformation at each of the quadrature points.
+     * The matrix stored is the Jacobian * G^{-1}, where G = Jacobian^{t} *
+     * Jacobian, is the first fundamental form of the map; if dim=spacedim
+     * then it reduces to the transpose of the inverse of the Jacobian matrix,
+     * which itself is stored in the @p contravariant field of this structure.
      *
      * Computed on each cell.
      */
     std::vector<DerivativeForm<1,dim, spacedim > >  covariant;
 
     /**
-     * Tensors of contravariant
-     * transformation at each of
-     * the quadrature points. The
-     * contravariant matrix is
-     * the Jacobian of the
-     * transformation,
+     * Tensors of contravariant transformation at each of the quadrature
+     * points. The contravariant matrix is the Jacobian of the transformation,
      * i.e. $J_{ij}=dx_i/d\hat x_j$.
      *
      * Computed on each cell.
@@ -311,24 +248,15 @@ public:
     std::vector< DerivativeForm<1,dim,spacedim> > contravariant;
 
     /**
-     * Unit tangential vectors. Used
-     * for the computation of
-     * boundary forms and normal
-     * vectors.
+     * Unit tangential vectors. Used for the computation of boundary forms and
+     * normal vectors.
      *
-     * This vector has
-     * (dim-1)GeometryInfo::faces_per_cell
-     * entries. The first
-     * GeometryInfo::faces_per_cell
-     * contain the vectors in the first
-     * tangential direction for each
-     * face; the second set of
-     * GeometryInfo::faces_per_cell
-     * entries contain the vectors in the
-     * second tangential direction (only
-     * in 3d, since there we have 2
-     * tangential directions per face),
-     * etc.
+     * This vector has (dim-1)GeometryInfo::faces_per_cell entries. The first
+     * GeometryInfo::faces_per_cell contain the vectors in the first
+     * tangential direction for each face; the second set of
+     * GeometryInfo::faces_per_cell entries contain the vectors in the second
+     * tangential direction (only in 3d, since there we have 2 tangential
+     * directions per face), etc.
      *
      * Filled once.
      */
@@ -340,58 +268,41 @@ public:
     std::vector<std::vector<Tensor<1,spacedim> > > aux;
 
     /**
-     * Stores the support points of
-     * the mapping shape functions on
-     * the @p cell_of_current_support_points.
+     * Stores the support points of the mapping shape functions on the @p
+     * cell_of_current_support_points.
      */
     std::vector<Point<spacedim> > mapping_support_points;
 
     /**
-     * Stores the cell of which the
-     * @p mapping_support_points are
-     * stored.
+     * Stores the cell of which the @p mapping_support_points are stored.
      */
     typename Triangulation<dim,spacedim>::cell_iterator cell_of_current_support_points;
 
     /**
-     * Default value of this flag
-     * is @p true. If <tt>*this</tt>
-     * is an object of a derived
-     * class, this flag is set to
-     * @p false.
+     * Default value of this flag is @p true. If <tt>*this</tt> is an object
+     * of a derived class, this flag is set to @p false.
      */
     bool is_mapping_q1_data;
 
     /**
-     * Number of shape
-     * functions. If this is a Q1
-     * mapping, then it is simply
-     * the number of vertices per
-     * cell. However, since also
-     * derived classes use this
-     * class (e.g. the
-     * Mapping_Q() class),
-     * the number of shape
-     * functions may also be
-     * different.
+     * Number of shape functions. If this is a Q1 mapping, then it is simply
+     * the number of vertices per cell. However, since also derived classes
+     * use this class (e.g. the Mapping_Q() class), the number of shape
+     * functions may also be different.
      */
     unsigned int n_shape_functions;
   };
 
   /**
-   * Declare a convenience typedef
-   * for the class that describes
-   * offsets into quadrature
-   * formulas projected onto faces
-   * and subfaces.
+   * Declare a convenience typedef for the class that describes offsets into
+   * quadrature formulas projected onto faces and subfaces.
    */
   typedef
   typename QProjector<dim>::DataSetDescriptor
   DataSetDescriptor;
 
   /**
-   * Implementation of the interface in
-   * Mapping.
+   * Implementation of the interface in Mapping.
    */
   virtual void
   fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -406,8 +317,7 @@ public:
                   CellSimilarity::Similarity                           &cell_similarity) const;
 
   /**
-   * Implementation of the interface in
-   * Mapping.
+   * Implementation of the interface in Mapping.
    */
   virtual void
   fill_fe_face_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -420,8 +330,7 @@ public:
                        typename std::vector<Point<spacedim> >           &normal_vectors) const ;
 
   /**
-   * Implementation of the interface in
-   * Mapping.
+   * Implementation of the interface in Mapping.
    */
   virtual void
   fill_fe_subface_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -435,27 +344,19 @@ public:
                           typename std::vector<Point<spacedim> >        &normal_vectors) const ;
 
   /**
-   * Compute shape values and/or
-   * derivatives.
+   * Compute shape values and/or derivatives.
    *
-   * Calls either the
-   * @p compute_shapes_virtual of
-   * this class or that of the
-   * derived class, depending on
-   * whether
-   * <tt>data.is_mapping_q1_data</tt>
+   * Calls either the @p compute_shapes_virtual of this class or that of the
+   * derived class, depending on whether <tt>data.is_mapping_q1_data</tt>
    * equals @p true or @p false.
    */
   void compute_shapes (const std::vector<Point<dim> > &unit_points,
                        InternalData &data) const;
 
   /**
-   * Do the computations for the
-   * @p get_data functions. Here,
-   * the data vectors of
-   * @p InternalData are
-   * reinitialized to proper size
-   * and shape values are computed.
+   * Do the computations for the @p get_data functions. Here, the data vectors
+   * of @p InternalData are reinitialized to proper size and shape values are
+   * computed.
    */
   void compute_data (const UpdateFlags flags,
                      const Quadrature<dim> &quadrature,
@@ -463,16 +364,10 @@ public:
                      InternalData &data) const;
 
   /**
-   * Do the computations for the
-   * @p get_face_data
-   * functions. Here, the data
-   * vectors of @p InternalData
-   * are reinitialized to proper
-   * size and shape values and
-   * derivatives are
-   * computed. Furthermore
-   * @p unit_tangential vectors of
-   * the face are computed.
+   * Do the computations for the @p get_face_data functions. Here, the data
+   * vectors of @p InternalData are reinitialized to proper size and shape
+   * values and derivatives are computed. Furthermore @p unit_tangential
+   * vectors of the face are computed.
    */
   void compute_face_data (const UpdateFlags flags,
                           const Quadrature<dim> &quadrature,
@@ -480,8 +375,7 @@ public:
                           InternalData &data) const;
 
   /**
-   * Do the computation for the
-   * <tt>fill_*</tt> functions.
+   * Do the computation for the <tt>fill_*</tt> functions.
    */
   void compute_fill (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
                      const unsigned int      npts,
@@ -491,8 +385,7 @@ public:
                      std::vector<Point<spacedim> > &quadrature_points) const;
 
   /**
-   * Do the computation for the
-   * <tt>fill_*</tt> functions.
+   * Do the computation for the <tt>fill_*</tt> functions.
    */
   void compute_fill_face (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
                           const unsigned int      face_no,
@@ -507,70 +400,42 @@ public:
                           std::vector<Point<spacedim> > &normal_vectors) const;
 
   /**
-   * Compute shape values and/or
-   * derivatives.
+   * Compute shape values and/or derivatives.
    */
   virtual void compute_shapes_virtual (const std::vector<Point<dim> > &unit_points,
                                        InternalData &data) const;
 
   /**
-   * Transforms a point @p p on
-   * the unit cell to the point
-   * @p p_real on the real cell
-   * @p cell and returns @p p_real.
+   * Transforms a point @p p on the unit cell to the point @p p_real on the
+   * real cell @p cell and returns @p p_real.
    *
-   * This function is called by
-   * @p transform_unit_to_real_cell
-   * and multiple times (through the
-   * Newton iteration) by
-   * @p transform_real_to_unit_cell_internal.
+   * This function is called by @p transform_unit_to_real_cell and multiple
+   * times (through the Newton iteration) by @p
+   * transform_real_to_unit_cell_internal.
    *
-   * Takes a reference to an
-   * @p InternalData that must
-   * already include the shape
-   * values at point @p p and the
-   * mapping support points of the
-   * cell.
+   * Takes a reference to an @p InternalData that must already include the
+   * shape values at point @p p and the mapping support points of the cell.
    *
-   * This @p InternalData argument
-   * avoids multiple computations
-   * of the shape values at point
-   * @p p and especially multiple
-   * computations of the mapping
+   * This @p InternalData argument avoids multiple computations of the shape
+   * values at point @p p and especially multiple computations of the mapping
    * support points.
    */
   Point<spacedim>
   transform_unit_to_real_cell_internal (const InternalData &mdata) const;
 
   /**
-   * Transforms the point @p p on
-   * the real cell to the corresponding
-   * point on the unit cell
-   * @p cell by a Newton
-   * iteration.
+   * Transforms the point @p p on the real cell to the corresponding point on
+   * the unit cell @p cell by a Newton iteration.
    *
-   * Takes a reference to an
-   * @p InternalData that is
-   * assumed to be previously
-   * created by the @p get_data
-   * function with @p UpdateFlags
-   * including
-   * @p update_transformation_values
-   * and
-   * @p update_transformation_gradients
-   * and a one point Quadrature
-   * that includes the given
-   * initial guess for the
-   * transformation
-   * @p initial_p_unit.  Hence this
-   * function assumes that
-   * @p mdata already includes the
-   * transformation shape values
-   * and gradients computed at
-   * @p initial_p_unit.
+   * Takes a reference to an @p InternalData that is assumed to be previously
+   * created by the @p get_data function with @p UpdateFlags including @p
+   * update_transformation_values and @p update_transformation_gradients and a
+   * one point Quadrature that includes the given initial guess for the
+   * transformation @p initial_p_unit.  Hence this function assumes that @p
+   * mdata already includes the transformation shape values and gradients
+   * computed at @p initial_p_unit.
    *
-   * @p mdata will be changed by
-   * this function.
+   * @p mdata will be changed by this function.
    */
   Point<dim>
   transform_real_to_unit_cell_internal (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -579,8 +444,7 @@ public:
                                         InternalData &mdata) const;
 
   /**
-   * Always returns @p true because
-   * MappingQ1 preserves vertex locations.
+   * Always returns @p true because MappingQ1 preserves vertex locations.
    */
   virtual
   bool preserves_vertex_locations () const;
@@ -596,44 +460,27 @@ protected:
    InternalData        &mdata) const;
 
   /**
-     Compute an initial guess to pass to the Newton method in
-     transform_real_to_unit_cell.
-
-     For the initial guess we proceed in the following way:
-     <ul>
-     <li> find the least square dim-dimensional plane
-          approximating the cell vertices, i.e. we find and affine
-          map A x_hat + b from the reference cell to the real space.
-     <li> Solve the equation A x_hat + b = p for x_hat
-     <li> This x_hat is the initial solution used for the Newton Method.
-     </ul>
-
-     @note if dim<spacedim we first project p onto the plane.
-     @note if dim==1 (for any spacedim) the initial guess is the exact solution
-     and no Newton iteration is needed.
-
-
-     Some details about how we compute the least square plane.
-     We look for a  spacedim x (dim + 1) matrix  X such that
-
-     X * M = Y
-
-     where M is a (dim+1) x n_vertices  matrix and Y a spacedim x n_vertices.
-
-     And:
-     The i-th column of M is unit_vertex[i] and the last row all 1's.
-     The i-th column of Y is real_vertex[i].
-
-     If we split X=[A|b], the least square approx is A x_hat+b
-
-     Classically  X = Y * (M^t (M M^t)^{-1})
-
-     Let K = M^t * (M M^t)^{-1} = [KA Kb]
-     this can be precomputed, and that is exactely
-     what we do.
-
-     Finally A = Y*KA  and  b = Y*Kb.
-  */
+   * Compute an initial guess to pass to the Newton method in
+   * transform_real_to_unit_cell.  For the initial guess we proceed in the
+   * following way:
+   * <ul>
+   * <li> find the least square dim-dimensional plane approximating the cell
+   * vertices, i.e. we find and affine map A x_hat + b from the reference cell
+   * to the real space.
+   * <li> Solve the equation A x_hat + b = p for x_hat
+   * <li> This x_hat is the initial solution used for the Newton Method.
+   * </ul>
+   *  @note if dim<spacedim we first project p onto the plane. @note if dim==1
+   * (for any spacedim) the initial guess is the exact solution and no Newton
+   * iteration is needed.   Some details about how we compute the least square
+   * plane. We look for a  spacedim x (dim + 1) matrix  X such that  X * M = Y
+   * where M is a (dim+1) x n_vertices  matrix and Y a spacedim x n_vertices.
+   * And: The i-th column of M is unit_vertex[i] and the last row all 1's. The
+   * i-th column of Y is real_vertex[i].  If we split X=[A|b], the least
+   * square approx is A x_hat+b  Classically  X = Y * (M^t (M M^t)^{-1})  Let
+   * K = M^t * (M M^t)^{-1} = [KA Kb] this can be precomputed, and that is
+   * exactely what we do.  Finally A = Y*KA  and  b = Y*Kb.
+   */
   Point<dim>
   transform_real_to_unit_cell_initial_guess (const std::vector<Point<spacedim> > &vertex,
                                              const Point<spacedim>                            &p) const;
@@ -641,77 +488,45 @@ protected:
 
 private:
   /**
-   * Implementation of the interface in
-   * Mapping.
+   * Implementation of the interface in Mapping.
    *
    * Description of effects:
    * <ul>
-   * <li> if @p update_quadrature_points
-   * is required, the output will
-   * contain
-   * @p update_transformation_values. This
-   * computes the values of the
-   * transformation basis
-   * polynomials at the unit cell
-   * quadrature points.
-   * <li> if any of
-   * @p update_covariant_transformation,
-   * @p update_contravariant_transformation,
-   * @p update_JxW_values,
-   * @p update_boundary_forms,
-   * @p update_normal_vectors is
-   * required, the output will
-   * contain
-   * @p update_transformation_gradients
-   * to compute derivatives of the
-   * transformation basis
-   * polynomials.
+   * <li> if @p update_quadrature_points is required, the output will contain
+   * @p update_transformation_values. This computes the values of the
+   * transformation basis polynomials at the unit cell quadrature points.
+   * <li> if any of @p update_covariant_transformation, @p
+   * update_contravariant_transformation, @p update_JxW_values, @p
+   * update_boundary_forms, @p update_normal_vectors is required, the output
+   * will contain @p update_transformation_gradients to compute derivatives of
+   * the transformation basis polynomials.
    * </ul>
    */
   virtual UpdateFlags update_once (const UpdateFlags flags) const;
 
   /**
-   * Implementation of the interface in
-   * Mapping.
+   * Implementation of the interface in Mapping.
    *
-   * Description of effects if
-   * @p flags contains:
+   * Description of effects if @p flags contains:
    * <ul>
-   * <li> <code>update_quadrature_points</code> is
-   * copied to the output to
-   * compute the quadrature points
-   * on the real cell.
-   * <li> <code>update_JxW_values</code> is
-   * copied and requires
-   * @p update_boundary_forms on
-   * faces. The latter, because the
-   * surface element is just the
-   * norm of the boundary form.
-   * <li> <code>update_normal_vectors</code>
-   * is copied and requires
-   * @p update_boundary_forms. The
-   * latter, because the normal
-   * vector is the normalized
-   * boundary form.
-   * <li>
-   * <code>update_covariant_transformation</code>
-   * is copied and requires
-   * @p update_contravariant_transformation,
-   * since it is computed as the
+   * <li> <code>update_quadrature_points</code> is copied to the output to
+   * compute the quadrature points on the real cell.
+   * <li> <code>update_JxW_values</code> is copied and requires @p
+   * update_boundary_forms on faces. The latter, because the surface element
+   * is just the norm of the boundary form.
+   * <li> <code>update_normal_vectors</code> is copied and requires @p
+   * update_boundary_forms. The latter, because the normal vector is the
+   * normalized boundary form.
+   * <li> <code>update_covariant_transformation</code> is copied and requires
+   * @p update_contravariant_transformation, since it is computed as the
    * inverse of the latter.
-   * <li> <code>update_JxW_values</code> is
-   * copied and requires
-   * <code>update_contravariant_transformation</code>,
-   * since it is computed as one
-   * over determinant of the
-   * latter.
-   * <li> <code>update_boundary_forms</code>
-   * is copied and requires
-   * <code>update_contravariant_transformation</code>,
-   * since the boundary form is
-   * computed as the contravariant
-   * image of the normal vector to
-   * the unit cell.
+   * <li> <code>update_JxW_values</code> is copied and requires
+   * <code>update_contravariant_transformation</code>, since it is computed as
+   * one over determinant of the latter.
+   * <li> <code>update_boundary_forms</code> is copied and requires
+   * <code>update_contravariant_transformation</code>, since the boundary form
+   * is computed as the contravariant image of the normal vector to the unit
+   * cell.
    * </ul>
    */
   virtual UpdateFlags update_each (const UpdateFlags flags) const;
@@ -732,29 +547,20 @@ private:
                     const Quadrature<dim-1>& quadrature) const;
 
   /**
-   * Computes the support points of
-   * the mapping. For @p MappingQ1
-   * these are the
-   * vertices. However, other
-   * classes may override this
-   * function. In particular, the
-   * MappingQ1Eulerian class does
-   * exactly this by not computing
-   * the support points from the
-   * geometry of the current cell
-   * but instead evaluating an
-   * externally given displacement
-   * field in addition to the
-   * geometry of the cell.
+   * Computes the support points of the mapping. For @p MappingQ1 these are
+   * the vertices. However, other classes may override this function. In
+   * particular, the MappingQ1Eulerian class does exactly this by not
+   * computing the support points from the geometry of the current cell but
+   * instead evaluating an externally given displacement field in addition to
+   * the geometry of the cell.
    */
   virtual void compute_mapping_support_points(
     const typename Triangulation<dim,spacedim>::cell_iterator &cell,
     std::vector<Point<spacedim> > &a) const;
 
   /**
-   * Number of shape functions. Is
-   * simply the number of vertices
-   * per cell for the Q1 mapping.
+   * Number of shape functions. Is simply the number of vertices per cell for
+   * the Q1 mapping.
    */
   static const unsigned int n_shape_functions = GeometryInfo<dim>::vertices_per_cell;
 };
@@ -791,10 +597,9 @@ transform_real_to_unit_cell_internal
 
 
 /**
- * In order to avoid creation of static MappingQ1 objects at several
- * places in the library (in particular in backward compatibility
- * functions), we define a static MappingQ1 objects once and for all
- * places where it is needed.
+ * In order to avoid creation of static MappingQ1 objects at several places in
+ * the library (in particular in backward compatibility functions), we define
+ * a static MappingQ1 objects once and for all places where it is needed.
  */
 template <int dim, int spacedim=dim>
 struct StaticMappingQ1
index 893003b8fb978e7a78e80b4714207c17ce4d1797..c10a03941940b4bd14acac7cbdf53b55ab7f1f64 100644 (file)
@@ -26,39 +26,35 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Eulerian mapping of general unit cells by d-linear shape
- * functions. Each cell is thus shifted in space by values given to
- * the mapping through a finite element field.
+ * Eulerian mapping of general unit cells by d-linear shape functions. Each
+ * cell is thus shifted in space by values given to the mapping through a
+ * finite element field.
  *
  * <h3>Usage</h3>
  *
- * The constructor of this class takes two arguments: a reference to
- * the vector that defines the mapping from the reference
- * configuration to the current configuration and a reference to the
- * DoFHandler. The vector should then represent a (flattened out
- * version of a) vector valued field defined at nodes defined by the
- * the DoFHandler, where the number of components of the vector
- * field equals the number of space dimensions. Thus, the
- * DoFHandler shall operate on a finite element that has as many
- * components as space dimensions. As an additional requirement, we
- * impose that it have as many degree of freedom per vertex as there
- * are space dimensions; since this object only evaluates the finite
- * element field at the vertices, the values
- * of all other degrees of freedom (not associated to vertices) are
- * ignored. These requirements are met if the finite element which the
- * given DoFHandler operates on is constructed as a system
- * element (FESystem) from @p dim continuous FE_Q()
- * objects.
+ * The constructor of this class takes two arguments: a reference to the
+ * vector that defines the mapping from the reference configuration to the
+ * current configuration and a reference to the DoFHandler. The vector should
+ * then represent a (flattened out version of a) vector valued field defined
+ * at nodes defined by the the DoFHandler, where the number of components of
+ * the vector field equals the number of space dimensions. Thus, the
+ * DoFHandler shall operate on a finite element that has as many components as
+ * space dimensions. As an additional requirement, we impose that it have as
+ * many degree of freedom per vertex as there are space dimensions; since this
+ * object only evaluates the finite element field at the vertices, the values
+ * of all other degrees of freedom (not associated to vertices) are ignored.
+ * These requirements are met if the finite element which the given DoFHandler
+ * operates on is constructed as a system element (FESystem) from @p dim
+ * continuous FE_Q() objects.
  *
- * In many cases, the shift vector will also be the solution vector of
- * the problem under investigation. If this is not the case (i.e. the
- * number of components of the solution variable is not equal to the
- * space dimension, e.g. for scalar problems in <tt>dim>1</tt> where the
- * Eulerian coordinates only give a background field) or for coupled
- * problems where more variables are computed than just the flow
- * field), then a different DoFHandler has to be set up on the
- * given triangulation, and the shift vector has then to be associated
- * to it.
+ * In many cases, the shift vector will also be the solution vector of the
+ * problem under investigation. If this is not the case (i.e. the number of
+ * components of the solution variable is not equal to the space dimension,
+ * e.g. for scalar problems in <tt>dim>1</tt> where the Eulerian coordinates
+ * only give a background field) or for coupled problems where more variables
+ * are computed than just the flow field), then a different DoFHandler has to
+ * be set up on the given triangulation, and the shift vector has then to be
+ * associated to it.
  *
  * An example is shown below:
  * @code
@@ -69,21 +65,19 @@ DEAL_II_NAMESPACE_OPEN
  *    MappingQ1Eulerian<dim> mymapping(map_points, flowfield_dof_handler);
  * @endcode
  *
- * Note that since the vector of shift values and the dof handler are
- * only associated to this object at construction time, you have to
- * make sure that whenever you use this object, the given objects
- * still represent valid data.
+ * Note that since the vector of shift values and the dof handler are only
+ * associated to this object at construction time, you have to make sure that
+ * whenever you use this object, the given objects still represent valid data.
  *
- * To enable the use of the MappingQ1Eulerian class also in the context
- * of parallel codes using the PETSc wrapper classes, the type of
- * the vector can be specified as template parameter <tt>EulerVectorType</tt>
- * Not specifying this template argument in applications using the PETSc
- * vector classes leads to the construction of a copy of the vector
- * which is not acccessible afterwards!
+ * To enable the use of the MappingQ1Eulerian class also in the context of
+ * parallel codes using the PETSc wrapper classes, the type of the vector can
+ * be specified as template parameter <tt>EulerVectorType</tt> Not specifying
+ * this template argument in applications using the PETSc vector classes leads
+ * to the construction of a copy of the vector which is not acccessible
+ * afterwards!
  *
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
  *
  * @author Michael Stadler, 2001
  */
@@ -93,44 +87,29 @@ class MappingQ1Eulerian : public MappingQ1<dim,spacedim>
 public:
 
   /**
-   * Constructor. It takes a
-   * <tt>Vector<double> &</tt> as its
-   * first argument to specify the
-   * transformation of the whole
-   * problem from the reference to
-   * the current configuration.
-   * The organization of the
-   * elements in the @p Vector
-   * must follow the concept how
-   * deal.II stores solutions that
-   * are associated to a
-   * triangulation.  This is
-   * automatically the case if the
-   * @p Vector represents the
-   * solution of the previous step
-   * of a nonlinear problem.
-   * Alternatively, the @p Vector
-   * can be initialized by
+   * Constructor. It takes a <tt>Vector<double> &</tt> as its first argument
+   * to specify the transformation of the whole problem from the reference to
+   * the current configuration. The organization of the elements in the @p
+   * Vector must follow the concept how deal.II stores solutions that are
+   * associated to a triangulation.  This is automatically the case if the @p
+   * Vector represents the solution of the previous step of a nonlinear
+   * problem. Alternatively, the @p Vector can be initialized by
    * <tt>DoFAccessor::set_dof_values()</tt>.
    */
   MappingQ1Eulerian (const VECTOR  &euler_transform_vectors,
                      const DoFHandler<dim,spacedim> &shiftmap_dof_handler);
 
   /**
-   * Return a pointer to a copy of the
-   * present object. The caller of this
-   * copy then assumes ownership of it.
+   * Return a pointer to a copy of the present object. The caller of this copy
+   * then assumes ownership of it.
    */
   virtual
   Mapping<dim,spacedim> *clone () const;
 
   /**
-   * Always returns @p false because
-   * MappingQ1Eulerian does not in general
-   * preserve vertex locations (unless the
-   * translation vector happens to provide
-   * for zero displacements at vertex
-   * locations).
+   * Always returns @p false because MappingQ1Eulerian does not in general
+   * preserve vertex locations (unless the translation vector happens to
+   * provide for zero displacements at vertex locations).
    */
   bool preserves_vertex_locations () const;
 
@@ -143,10 +122,8 @@ public:
 
 protected:
   /**
-   * Implementation of the interface in
-   * MappingQ1. Overrides the function in
-   * the base class, since we cannot use
-   * any cell similarity for this class.
+   * Implementation of the interface in MappingQ1. Overrides the function in
+   * the base class, since we cannot use any cell similarity for this class.
    */
   virtual void
   fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
@@ -161,25 +138,20 @@ protected:
                   CellSimilarity::Similarity                           &cell_similarity) const;
 
   /**
-   * Reference to the vector of
-   * shifts.
+   * Reference to the vector of shifts.
    */
   SmartPointer<const VECTOR, MappingQ1Eulerian<dim,VECTOR,spacedim> > euler_transform_vectors;
 
   /**
-   * Pointer to the DoFHandler to
-   * which the mapping vector is
-   * associated.
+   * Pointer to the DoFHandler to which the mapping vector is associated.
    */
   SmartPointer<const DoFHandler<dim,spacedim>,MappingQ1Eulerian<dim,VECTOR,spacedim> > shiftmap_dof_handler;
 
 
 private:
   /**
-   * Computes the support points of
-   * the mapping. For
-   * @p MappingQ1Eulerian these
-   * are the vertices.
+   * Computes the support points of the mapping. For @p MappingQ1Eulerian
+   * these are the vertices.
    */
   virtual void compute_mapping_support_points(
     const typename Triangulation<dim,spacedim>::cell_iterator &cell,
index 80df4361fd416be1a1250ae1b9985e7b42a4a832..c389a81ec896a1befdceda2bb6133af8deced9e6 100644 (file)
@@ -34,32 +34,29 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * This class is an extension of the MappingQ1Eulerian
- * class to higher order Qp mappings.  It is useful
- * when one wants to calculate shape function information on
- * a domain that is deforming as the computation proceeds.
+ * This class is an extension of the MappingQ1Eulerian class to higher order
+ * Qp mappings.  It is useful when one wants to calculate shape function
+ * information on a domain that is deforming as the computation proceeds.
  *
  * <h3>Usage</h3>
  *
- * The constructor of this class takes three arguments: the polynomial
- * degree of the desire Qp mapping, a reference to
- * the vector that defines the mapping from the initial
- * configuration to the current configuration, and a reference to the
- * DoFHandler. The most common case is to use the solution
- * vector for the problem under consideration as the shift vector.
- * The key reqirement is that the number of components
- * of the given vector field be equal to (or possibly greater than) the
- * number of space dimensions. If there are more components than space
- * dimensions (for example, if one is working with a coupled problem
- * where there are additional solution variables), the
- * first <tt>dim</tt> components are assumed to represent the displacement
- * field, and the remaining components are ignored.  If this assumption
- * does not hold one may need to set up a separate DoFHandler on
+ * The constructor of this class takes three arguments: the polynomial degree
+ * of the desire Qp mapping, a reference to the vector that defines the
+ * mapping from the initial configuration to the current configuration, and a
+ * reference to the DoFHandler. The most common case is to use the solution
+ * vector for the problem under consideration as the shift vector. The key
+ * reqirement is that the number of components of the given vector field be
+ * equal to (or possibly greater than) the number of space dimensions. If
+ * there are more components than space dimensions (for example, if one is
+ * working with a coupled problem where there are additional solution
+ * variables), the first <tt>dim</tt> components are assumed to represent the
+ * displacement field, and the remaining components are ignored.  If this
+ * assumption does not hold one may need to set up a separate DoFHandler on
  * the triangulation and associate the desired shift vector to it.
  *
- * Typically, the DoFHandler operates on a finite element that
- * is constructed as a system element (FESystem) from continuous FE_Q()
- * objects. An example is shown below:
+ * Typically, the DoFHandler operates on a finite element that is constructed
+ * as a system element (FESystem) from continuous FE_Q() objects. An example
+ * is shown below:
  * @code
  *    FESystem<dim> fe(FE_Q<dim>(2), dim, FE_Q<dim>(1), 1);
  *    DoFHandler<dim> dof_handler(triangulation);
@@ -68,24 +65,24 @@ DEAL_II_NAMESPACE_OPEN
  *    MappingQEulerian<dim> q2_mapping(2,soln_vector,dof_handler);
  * @endcode
  *
- * In this example, our element consists of <tt>(dim+1)</tt> components.
- * Only the first <tt>dim</tt> components will be used, however, to define
- * the Q2 mapping.  The remaining components are ignored.
+ * In this example, our element consists of <tt>(dim+1)</tt> components. Only
+ * the first <tt>dim</tt> components will be used, however, to define the Q2
+ * mapping.  The remaining components are ignored.
  *
- * Note that it is essential to call the distribute_dofs(...) function
- * before constructing a mapping object.
+ * Note that it is essential to call the distribute_dofs(...) function before
+ * constructing a mapping object.
  *
  * Also note that since the vector of shift values and the dof handler are
- * only associated to this object at construction time, you have to
- * make sure that whenever you use this object, the given objects
- * still represent valid data.
+ * only associated to this object at construction time, you have to make sure
+ * that whenever you use this object, the given objects still represent valid
+ * data.
  *
- * To enable the use of the MappingQ1Eulerian class also in the context
- * of parallel codes using the PETSc wrapper classes, the type of
- * the vector can be specified as template parameter <tt>EulerVectorType</tt>
- * Not specifying this template argument in applications using the PETSc
- * vector classes leads to the construction of a copy of the vector
- * which is not acccessible afterwards!
+ * To enable the use of the MappingQ1Eulerian class also in the context of
+ * parallel codes using the PETSc wrapper classes, the type of the vector can
+ * be specified as template parameter <tt>EulerVectorType</tt> Not specifying
+ * this template argument in applications using the PETSc vector classes leads
+ * to the construction of a copy of the vector which is not acccessible
+ * afterwards!
  *
  * @author Joshua White, 2008
  */
index 73bc416bc0280da31be305c0b9fb5eb72de8c517..7a971bc5e9aaea3bcbc8a33ff840b3c6330fd147 100644 (file)
@@ -48,8 +48,8 @@ DEAL_II_NAMESPACE_OPEN
  * exposed on purpose).
  *
  * @todo Does it make sense to implement a more efficient representation
- * (internally and/or as a string)? If yes, something like a 64bit int
- * as in p4est would be a good option.
+ * (internally and/or as a string)? If yes, something like a 64bit int as in
+ * p4est would be a good option.
  */
 class CellId
 {
index e31b6ca379a632b7fd101befc9acf3894749d97e..ce81742879f01075a684655367880d4a35fdcafa 100644 (file)
@@ -25,17 +25,17 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * In this namespace a number of classes is declared that may be used
- * as filters in the FilteredIterator class. The filters either check
- * for binary information (for example, the IteratorFilters::Active
- * filter class checks whether the object pointed to is active), or
- * for valued information by comparison with prescribed values (for
- * example, the LevelEqualTo filter class checks whether the level of
- * the object pointed to by the iterator under consideration is equal
- * to a value that was given to the filter upon construction.
+ * In this namespace a number of classes is declared that may be used as
+ * filters in the FilteredIterator class. The filters either check for binary
+ * information (for example, the IteratorFilters::Active filter class checks
+ * whether the object pointed to is active), or for valued information by
+ * comparison with prescribed values (for example, the LevelEqualTo filter
+ * class checks whether the level of the object pointed to by the iterator
+ * under consideration is equal to a value that was given to the filter upon
+ * construction.
  *
- * For examples of use of these classes as well as requirements on
- * filters see the general description of the FilteredIterator class.
+ * For examples of use of these classes as well as requirements on filters see
+ * the general description of the FilteredIterator class.
  *
  * @ingroup Iterators
  * @author Wolfgang Bangerth, 2002
@@ -43,8 +43,8 @@ DEAL_II_NAMESPACE_OPEN
 namespace IteratorFilters
 {
   /**
-   * Filter that evaluates to true if either the iterator points to an
-   * active object or an iterator past the end.
+   * Filter that evaluates to true if either the iterator points to an active
+   * object or an iterator past the end.
    *
    * @ingroup Iterators
    */
@@ -52,17 +52,17 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Evaluate the iterator and return true if the object is active
-     * or past the end.
+     * Evaluate the iterator and return true if the object is active or past
+     * the end.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
   };
 
   /**
-   * Filter that evaluates to true if either the iterator points to an
-   * object for which the user flag is set or an iterator past the
-   * end. See @ref GlossUserFlags for information about user flags.
+   * Filter that evaluates to true if either the iterator points to an object
+   * for which the user flag is set or an iterator past the end. See @ref
+   * GlossUserFlags for information about user flags.
    *
    * @ingroup Iterators
    */
@@ -70,8 +70,8 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Evaluate the iterator and return true if the object has a set
-     * user flag or past the end.
+     * Evaluate the iterator and return true if the object has a set user flag
+     * or past the end.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
@@ -79,9 +79,9 @@ namespace IteratorFilters
 
 
   /**
-   * Filter that evaluates to true if either the iterator points to an
-   * object for which the user flag is not set or an iterator past the
-   * end. Inverse filter to the previous class.
+   * Filter that evaluates to true if either the iterator points to an object
+   * for which the user flag is not set or an iterator past the end. Inverse
+   * filter to the previous class.
    *
    * @ingroup Iterators
    */
@@ -89,8 +89,8 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Evaluate the iterator and return true if the object has an
-     * unset user flag or past the end.
+     * Evaluate the iterator and return true if the object has an unset user
+     * flag or past the end.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
@@ -98,9 +98,9 @@ namespace IteratorFilters
 
 
   /**
-   * Filter for iterators that evaluates to true if either the
-   * iterator is past the end or the level of the object pointed to is
-   * equal to a value given to the constructor.
+   * Filter for iterators that evaluates to true if either the iterator is
+   * past the end or the level of the object pointed to is equal to a value
+   * given to the constructor.
    *
    * @ingroup Iterators
    */
@@ -108,15 +108,15 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Constructor. Store the level which iterators shall have to be
-     * evaluated to true.
+     * Constructor. Store the level which iterators shall have to be evaluated
+     * to true.
      */
     LevelEqualTo (const unsigned int level);
 
     /**
-     * Evaluation operator. Returns true if either the level of the
-     * object pointed to is equal to the stored value or the iterator
-     * is past the end.
+     * Evaluation operator. Returns true if either the level of the object
+     * pointed to is equal to the stored value or the iterator is past the
+     * end.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
@@ -131,10 +131,10 @@ namespace IteratorFilters
 
 
   /**
-   * Filter for iterators that evaluates to true if either the
-   * iterator is past the end or the subdomain id of the object
-   * pointed to is equal to a value given to the constructor, assuming
-   * that the iterator allows querying for a subdomain id).
+   * Filter for iterators that evaluates to true if either the iterator is
+   * past the end or the subdomain id of the object pointed to is equal to a
+   * value given to the constructor, assuming that the iterator allows
+   * querying for a subdomain id).
    *
    * @ingroup Iterators
    */
@@ -142,15 +142,15 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Constructor. Store the subdomain which iterators shall have to
-     * be evaluated to true.
+     * Constructor. Store the subdomain which iterators shall have to be
+     * evaluated to true.
      */
     SubdomainEqualTo (const types::subdomain_id subdomain_id);
 
     /**
-     * Evaluation operator. Returns true if either the subdomain of
-     * the object pointed to is equal to the stored value or the
-     * iterator is past the end.
+     * Evaluation operator. Returns true if either the subdomain of the object
+     * pointed to is equal to the stored value or the iterator is past the
+     * end.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
@@ -165,12 +165,12 @@ namespace IteratorFilters
 
 
   /**
-   * Filter for iterators that evaluates to true if a cell is owned by
-   * the current processor, i.e., if it is a @ref
-   * GlossLocallyOwnedCell "locally owned cell".
+   * Filter for iterators that evaluates to true if a cell is owned by the
+   * current processor, i.e., if it is a @ref GlossLocallyOwnedCell "locally
+   * owned cell".
    *
-   * This class is used in step-32, in connection with the methods of
-   * the @ref distributed module.
+   * This class is used in step-32, in connection with the methods of the @ref
+   * distributed module.
    *
    * @ingroup Iterators
    */
@@ -187,8 +187,8 @@ namespace IteratorFilters
 
 
   /**
-   * Filter for iterators that evaluates to true if th level subdomain
-   * id of a cell is equal to the current processor id.
+   * Filter for iterators that evaluates to true if th level subdomain id of a
+   * cell is equal to the current processor id.
    *
    * @ingroup Iterators
    */
@@ -196,8 +196,8 @@ namespace IteratorFilters
   {
   public:
     /**
-     * Evaluation operator. Returns true if the level subdomain id of
-     * the cell is equal to the current processor id.
+     * Evaluation operator. Returns true if the level subdomain id of the cell
+     * is equal to the current processor id.
      */
     template <class Iterator>
     bool operator () (const Iterator &i) const;
@@ -207,31 +207,28 @@ namespace IteratorFilters
 
 /**
  * This class provides a certain view on a range of triangulation or
- * DoFHandler iterators by only iterating over elements that satisfy a
- * given filter (called a <em>predicate</em>, following the notation
- * of the C++ standard library). Once initialized with a predicate and
- * a value for the iterator, a filtered iterator hops to the next or
- * previous element that satisfies the predicate if operators ++ or --
- * are invoked. Intermediate iterator values that lie in between but
- * do not satisfy the predicate are skipped. It is thus very simple to
- * write loops over a certain class of objects without the need to
- * explicitely write down the condition they have to satisfy in each
- * loop iteration. This in particular is helpful if functions are
- * called with a pair of iterators denoting a range on which they
- * shall act, by choosing a filtered iterator instead of usual ones.
+ * DoFHandler iterators by only iterating over elements that satisfy a given
+ * filter (called a <em>predicate</em>, following the notation of the C++
+ * standard library). Once initialized with a predicate and a value for the
+ * iterator, a filtered iterator hops to the next or previous element that
+ * satisfies the predicate if operators ++ or -- are invoked. Intermediate
+ * iterator values that lie in between but do not satisfy the predicate are
+ * skipped. It is thus very simple to write loops over a certain class of
+ * objects without the need to explicitely write down the condition they have
+ * to satisfy in each loop iteration. This in particular is helpful if
+ * functions are called with a pair of iterators denoting a range on which
+ * they shall act, by choosing a filtered iterator instead of usual ones.
  *
- * This class is used in step-18 and
- * step-32.
+ * This class is used in step-18 and step-32.
  *
  *
  * <h3>Predicates</h3>
  *
- * The object that represent the condition an iterator has to satisfy
- * only have to provide an interface that allows to call the
- * evaluation operator, i.e. <code>bool operator() (const
- * BaseIterator&)</code>. This includes function pointers as well as
- * classes that implement an <code>bool operator ()(const
- * BaseIterator&)</code>. Then, the FilteredIterator will skip all
+ * The object that represent the condition an iterator has to satisfy only
+ * have to provide an interface that allows to call the evaluation operator,
+ * i.e. <code>bool operator() (const BaseIterator&)</code>. This includes
+ * function pointers as well as classes that implement an <code>bool operator
+ * ()(const BaseIterator&)</code>. Then, the FilteredIterator will skip all
  * objects where the return value of this function is <code>false</code>.
  *
  *
@@ -262,10 +259,10 @@ namespace IteratorFilters
  * @code
  *   std::bind2nd (std::ptr_fun(&level_equal_to<active_cell_iterator>), 3)
  * @endcode
- * is another valid predicate (here: a function that returns true if
- * either the iterator is past the end or the level is equal to the
- * second argument; this second argument is bound to a fixed value
- * using the @p std::bind2nd function).
+ * is another valid predicate (here: a function that returns true if either
+ * the iterator is past the end or the level is equal to the second argument;
+ * this second argument is bound to a fixed value using the @p std::bind2nd
+ * function).
  *
  * Finally, classes can be predicates. The following class is one:
  * @code
@@ -278,8 +275,8 @@ namespace IteratorFilters
  *       }
  *   };
  * @endcode
- * and objects of this type can be used as predicates. Likewise, this
- * more complicated one can also be used:
+ * and objects of this type can be used as predicates. Likewise, this more
+ * complicated one can also be used:
  * @code
  *   class SubdomainEqualTo
  *   {
@@ -296,56 +293,54 @@ namespace IteratorFilters
  *       const types::subdomain_id subdomain_id;
  *   };
  * @endcode
- * Objects like <code>SubdomainEqualTo(3)</code> can then be used as predicates.
+ * Objects like <code>SubdomainEqualTo(3)</code> can then be used as
+ * predicates.
  *
- * Since whenever a predicate is evaluated it is checked that the
- * iterator checked is actually valid (i.e. not past the end), no
- * checks for this case have to be performed inside predicates.
+ * Since whenever a predicate is evaluated it is checked that the iterator
+ * checked is actually valid (i.e. not past the end), no checks for this case
+ * have to be performed inside predicates.
  *
- * A number of filter classes are already implemented in the
- * IteratorFilters namespace, but writing different ones is
- * simple following the examples above.
+ * A number of filter classes are already implemented in the IteratorFilters
+ * namespace, but writing different ones is simple following the examples
+ * above.
  *
  *
  * <h3>Initialization of filtered iterators</h3>
  *
- * Filtered iterators are given a predicate at construction time which
- * cannot be changed any more. This behaviour would be expected if the
- * predicate would have been given as a template parameter to the
- * class, but since that would make the declaration of filtered
- * iterators a nightmare, we rather give the predicate as an
- * unchangeable entity to the constructor. Note that one can assign a
- * filtered iterator with one predicate to another filtered iterator
- * with another type; yet, this does <em>not</em> change the predicate
- * of the assigned-to iterator, only the pointer indicating the
+ * Filtered iterators are given a predicate at construction time which cannot
+ * be changed any more. This behaviour would be expected if the predicate
+ * would have been given as a template parameter to the class, but since that
+ * would make the declaration of filtered iterators a nightmare, we rather
+ * give the predicate as an unchangeable entity to the constructor. Note that
+ * one can assign a filtered iterator with one predicate to another filtered
+ * iterator with another type; yet, this does <em>not</em> change the
+ * predicate of the assigned-to iterator, only the pointer indicating the
  * iterator is changed.
  *
  * If a filtered iterator is not assigned a value of the underlying
- * (unfiltered) iterator type, the default value is taken. If,
- * however, a value is given to the constructor, that value has either
- * to be past the end, or has to satisfy the predicate. For example,
- * if the predicate only evaluates to true if the level of an object
- * is equal to three, then <code>tria.begin_active(3)</code> would be a valid
- * choice while <code>tria.begin()</code> would not since the latter also
- * returns iterators to non-active cells which always start at level
- * 0.
+ * (unfiltered) iterator type, the default value is taken. If, however, a
+ * value is given to the constructor, that value has either to be past the
+ * end, or has to satisfy the predicate. For example, if the predicate only
+ * evaluates to true if the level of an object is equal to three, then
+ * <code>tria.begin_active(3)</code> would be a valid choice while
+ * <code>tria.begin()</code> would not since the latter also returns iterators
+ * to non-active cells which always start at level 0.
  *
- * Since one often only has some iterator and wants to set a filtered
- * iterator to the first one that satisfies a predicate (for example,
- * the first one for which the user flag is set, or the first one with
- * a given subdomain id), there are assignement functions
- * #set_to_next_positive and #set_to_previous_positive that
- * assign the next or last previous iterator that satisfies the
- * predicate, i.e. they follow the list of iterators in either
- * direction until they find a matching one (or the past-the-end
+ * Since one often only has some iterator and wants to set a filtered iterator
+ * to the first one that satisfies a predicate (for example, the first one for
+ * which the user flag is set, or the first one with a given subdomain id),
+ * there are assignement functions #set_to_next_positive and
+ * #set_to_previous_positive that assign the next or last previous iterator
+ * that satisfies the predicate, i.e. they follow the list of iterators in
+ * either direction until they find a matching one (or the past-the-end
  * iterator). Like the <code>operator=</code> they return the resulting value
  * of the filtered iterator.
  *
  *
  * <h3>Examples</h3>
  *
- * The following call counts the number of active cells that
- * have a set user flag:
+ * The following call counts the number of active cells that have a set user
+ * flag:
  * @code
  *   FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
  *      begin (IteratorFilters::UserFlagSet()),
@@ -354,10 +349,10 @@ namespace IteratorFilters
  *   end = tria.end();
  *   n_flagged_cells = std::distance (begin, end);
  * @endcode
- * Note that by the @p set_to_next_positive call the first cell with
- * a set user flag was assigned to the @p begin iterator. For the
- * end iterator, no such call was necessary, since the past-the-end
- * iterator always satisfies all predicates.
+ * Note that by the @p set_to_next_positive call the first cell with a set
+ * user flag was assigned to the @p begin iterator. For the end iterator, no
+ * such call was necessary, since the past-the-end iterator always satisfies
+ * all predicates.
  *
  * The same can be achieved by the following snippet, though harder to read:
  * @code
@@ -367,13 +362,12 @@ namespace IteratorFilters
  *                            .set_to_next_positive(tria.begin_active()),
  *                     FI(IteratorFilters::UserFlagSet(), tria.end()));
  * @endcode
- * It relies on the fact that if we create an unnamed filtered
- * iterator with a given predicate but no iterator value and assign it
- * the next positive value with respect to this predicate, it returns
- * itself which is then used as the first parameter to the
- * @p std::distance function. This procedure is not necessary for the
- * end element to this function here, since the past-the-end iterator
- * always satisfies the predicate so that we can assign this value to
+ * It relies on the fact that if we create an unnamed filtered iterator with a
+ * given predicate but no iterator value and assign it the next positive value
+ * with respect to this predicate, it returns itself which is then used as the
+ * first parameter to the @p std::distance function. This procedure is not
+ * necessary for the end element to this function here, since the past-the-end
+ * iterator always satisfies the predicate so that we can assign this value to
  * the filtered iterator directly in the constructor.
  *
  * Finally, the following loop only assembles the matrix on cells with
@@ -387,11 +381,10 @@ namespace IteratorFilters
  *   assemble_local_matrix (cell);
  * @endcode
  *
- * Since comparison between filtered and unfiltered iterators is
- * defined, we could as well have let the @p endc variable in the
- * last example be of type
- * Triangulation::active_cell_iterator since it is unchanged
- * and its value does not depend on the filter.
+ * Since comparison between filtered and unfiltered iterators is defined, we
+ * could as well have let the @p endc variable in the last example be of type
+ * Triangulation::active_cell_iterator since it is unchanged and its value
+ * does not depend on the filter.
  *
  * @ingroup grid
  * @ingroup Iterators
@@ -402,56 +395,41 @@ class FilteredIterator : public BaseIterator
 {
 public:
   /**
-   * Typedef to the accessor type
-   * of the underlying iterator.
+   * Typedef to the accessor type of the underlying iterator.
    */
   typedef typename BaseIterator::AccessorType AccessorType;
 
   /**
-   * Constructor. Set the iterator
-   * to the default state and use
-   * the given predicate for
-   * filtering subsequent
-   * assignement and iteration.
+   * Constructor. Set the iterator to the default state and use the given
+   * predicate for filtering subsequent assignement and iteration.
    */
   template <typename Predicate>
   FilteredIterator (Predicate p);
 
   /**
-   * Constructor. Use the given
-   * predicate for filtering and
-   * initialize the iterator with
-   * the given value.
+   * Constructor. Use the given predicate for filtering and initialize the
+   * iterator with the given value.
    *
-   * If the initial value @p bi does
-   * not satisfy the predicate @p p
-   * then it is advanced until we
-   * either hit the the
-   * past-the-end iterator, or the
-   * predicate is satisfied. This
-   * allows, for example, to write
-   * code like
+   * If the initial value @p bi does not satisfy the predicate @p p then it is
+   * advanced until we either hit the the past-the-end iterator, or the
+   * predicate is satisfied. This allows, for example, to write code like
    * @code
    *   FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
    *     cell (IteratorFilters::SubdomainEqualTo(13),
    *           triangulation.begin_active());
    * @endcode
    *
-   * If the cell
-   * <code>triangulation.begin_active()</code>
-   * does not have a subdomain_id
-   * equal to 13, then the iterator
-   * will automatically be advanced
-   * to the first cell that has.
+   * If the cell <code>triangulation.begin_active()</code> does not have a
+   * subdomain_id equal to 13, then the iterator will automatically be
+   * advanced to the first cell that has.
    */
   template <typename Predicate>
   FilteredIterator (Predicate           p,
                     const BaseIterator &bi);
 
   /**
-   * Copy constructor. Copy the
-   * predicate and iterator value
-   * of the given argument.
+   * Copy constructor. Copy the predicate and iterator value of the given
+   * argument.
    */
   FilteredIterator (const FilteredIterator &fi);
 
@@ -461,164 +439,111 @@ public:
   ~FilteredIterator ();
 
   /**
-   * Assignment operator. Copy the
-   * iterator value of the
-   * argument, but as discussed in
-   * the class documentation, the
-   * predicate of the argument is
-   * not copied. The iterator value
-   * underlying the argument has to
-   * satisfy the predicate of the
-   * object assigned to, as given
-   * at its construction time.
+   * Assignment operator. Copy the iterator value of the argument, but as
+   * discussed in the class documentation, the predicate of the argument is
+   * not copied. The iterator value underlying the argument has to satisfy the
+   * predicate of the object assigned to, as given at its construction time.
    */
   FilteredIterator &operator = (const FilteredIterator &fi);
 
   /**
-   * Assignment operator. Copy the
-   * iterator value of the
-   * argument, and keep the
-   * predicate of this object. The
-   * given iterator value has to
-   * satisfy the predicate of the
-   * object assigned to, as given
-   * at its construction time.
+   * Assignment operator. Copy the iterator value of the argument, and keep
+   * the predicate of this object. The given iterator value has to satisfy the
+   * predicate of the object assigned to, as given at its construction time.
    */
   FilteredIterator &operator = (const BaseIterator &fi);
 
   /**
-   * Search for the next iterator
-   * from @p bi onwards that
-   * satisfies the predicate of
-   * this object and assign it to
-   * this object.
+   * Search for the next iterator from @p bi onwards that satisfies the
+   * predicate of this object and assign it to this object.
    *
-   * Since filtered iterators are
-   * automatically converted to the
-   * underlying base iterator type,
-   * you can also give a filtered
-   * iterator as argument to this
-   * function.
+   * Since filtered iterators are automatically converted to the underlying
+   * base iterator type, you can also give a filtered iterator as argument to
+   * this function.
    */
   FilteredIterator &
   set_to_next_positive (const BaseIterator &bi);
 
   /**
-   * As above, but search for the
-   * previous iterator from @p bi
-   * backwards that satisfies the
-   * predicate of this object and
-   * assign it to this object.
+   * As above, but search for the previous iterator from @p bi backwards that
+   * satisfies the predicate of this object and assign it to this object.
    *
-   * Since filtered iterators are
-   * automatically converted to the
-   * underlying base iterator type,
-   * you can also give a filtered
-   * iterator as argument to this
-   * function.
+   * Since filtered iterators are automatically converted to the underlying
+   * base iterator type, you can also give a filtered iterator as argument to
+   * this function.
    */
   FilteredIterator &
   set_to_previous_positive (const BaseIterator &bi);
 
   /**
-   * Compare for equality of the
-   * underlying iterator values of
-   * this and the given object.
+   * Compare for equality of the underlying iterator values of this and the
+   * given object.
    *
-   * We do not compare for equality
-   * of the predicates.
+   * We do not compare for equality of the predicates.
    */
   bool operator == (const FilteredIterator &fi) const;
 
   /**
-   * Compare for equality of the
-   * underlying iterator value of
-   * this object with the given
-   * object.
+   * Compare for equality of the underlying iterator value of this object with
+   * the given object.
    *
-   * The predicate of this object
-   * is irrelevant for this
-   * operation.
+   * The predicate of this object is irrelevant for this operation.
    */
   bool operator == (const BaseIterator &fi) const;
 
   /**
-   * Compare for inequality of the
-   * underlying iterator values of
-   * this and the given object.
+   * Compare for inequality of the underlying iterator values of this and the
+   * given object.
    *
-   * We do not compare for equality
-   * of the predicates.
+   * We do not compare for equality of the predicates.
    */
   bool operator != (const FilteredIterator &fi) const;
 
   /**
-   * Compare for inequality of the
-   * underlying iterator value of
-   * this object with the given
-   * object.
+   * Compare for inequality of the underlying iterator value of this object
+   * with the given object.
    *
-   * The predicate of this object
-   * is irrelevant for this
-   * operation.
+   * The predicate of this object is irrelevant for this operation.
    */
   bool operator != (const BaseIterator &fi) const;
 
   /**
-   * Compare for ordering of the
-   * underlying iterator values of
-   * this and the given object.
+   * Compare for ordering of the underlying iterator values of this and the
+   * given object.
    *
-   * We do not compare the
-   * predicates.
+   * We do not compare the predicates.
    */
   bool operator <  (const FilteredIterator &fi) const;
 
   /**
-   * Compare for ordering of the
-   * underlying iterator value of
-   * this object with the given
-   * object.
+   * Compare for ordering of the underlying iterator value of this object with
+   * the given object.
    *
-   * The predicate of this object
-   * is irrelevant for this
-   * operation.
+   * The predicate of this object is irrelevant for this operation.
    */
   bool operator <  (const BaseIterator &fi) const;
 
   /**
-   * Prefix advancement operator:
-   * move to the next iterator
-   * value satisfying the predicate
-   * and return the new iterator
-   * value.
+   * Prefix advancement operator: move to the next iterator value satisfying
+   * the predicate and return the new iterator value.
    */
   FilteredIterator &operator ++ ();
 
   /**
-   * Postfix advancement operator:
-   * move to the next iterator
-   * value satisfying the predicate
-   * and return the old iterator
-   * value.
+   * Postfix advancement operator: move to the next iterator value satisfying
+   * the predicate and return the old iterator value.
    */
   FilteredIterator   operator ++ (int);
 
   /**
-   * Prefix decrement operator:
-   * move to the previous iterator
-   * value satisfying the predicate
-   * and return the new iterator
-   * value.
+   * Prefix decrement operator: move to the previous iterator value satisfying
+   * the predicate and return the new iterator value.
    */
   FilteredIterator &operator -- ();
 
   /**
-   * Postfix advancement operator:
-   * move to the previous iterator
-   * value satisfying the predicate
-   * and return the old iterator
-   * value.
+   * Postfix advancement operator: move to the previous iterator value
+   * satisfying the predicate and return the old iterator value.
    */
   FilteredIterator   operator -- (int);
 
@@ -634,19 +559,11 @@ public:
 private:
 
   /**
-   * Base class to encapsulate a
-   * predicate object. Since
-   * predicates can be of different
-   * types and we do not want to
-   * code these types into the
-   * template parameter list of the
-   * filtered iterator class, we
-   * use a base class with an
-   * abstract function and
-   * templatized derived classes
-   * that implement the use of
-   * actual predicate types through
-   * the virtual function.
+   * Base class to encapsulate a predicate object. Since predicates can be of
+   * different types and we do not want to code these types into the template
+   * parameter list of the filtered iterator class, we use a base class with
+   * an abstract function and templatized derived classes that implement the
+   * use of actual predicate types through the virtual function.
    *
    * @ingroup Iterators
    */
@@ -654,42 +571,30 @@ private:
   {
   public:
     /**
-     * Mark the destructor
-     * virtual to allow
-     * destruction through
-     * pointers to the base
-     * class.
+     * Mark the destructor virtual to allow destruction through pointers to
+     * the base class.
      */
     virtual ~PredicateBase () {}
 
     /**
-     * Abstract function which in
-     * derived classes denotes
-     * the evaluation of the
-     * predicate on the give
-     * iterator.
+     * Abstract function which in derived classes denotes the evaluation of
+     * the predicate on the give iterator.
      */
     virtual bool operator () (const BaseIterator &bi) const = 0;
 
     /**
-     * Generate a copy of this
-     * object, i.e. of the actual
-     * type of this pointer.
+     * Generate a copy of this object, i.e. of the actual type of this
+     * pointer.
      */
     virtual PredicateBase *clone () const = 0;
   };
 
 
   /**
-   * Actual implementation of the
-   * above abstract base class. Use
-   * a template parameter to denote
-   * the actual type of the
-   * predicate and store a copy of
-   * it. When the virtual function
-   * is called evaluate the given
-   * iterator with the stored copy
-   * of the predicate.
+   * Actual implementation of the above abstract base class. Use a template
+   * parameter to denote the actual type of the predicate and store a copy of
+   * it. When the virtual function is called evaluate the given iterator with
+   * the stored copy of the predicate.
    *
    * @ingroup Iterators
    */
@@ -698,23 +603,18 @@ private:
   {
   public:
     /**
-     * Constructor. Take a
-     * predicate and store a copy
-     * of it.
+     * Constructor. Take a predicate and store a copy of it.
      */
     PredicateTemplate (const Predicate &predicate);
 
     /**
-     * Evaluate the iterator with
-     * the stored copy of the
-     * predicate.
+     * Evaluate the iterator with the stored copy of the predicate.
      */
     virtual bool operator () (const BaseIterator &bi) const;
 
     /**
-     * Generate a copy of this
-     * object, i.e. of the actual
-     * type of this pointer.
+     * Generate a copy of this object, i.e. of the actual type of this
+     * pointer.
      */
     virtual PredicateBase *clone () const;
 
@@ -726,10 +626,8 @@ private:
   };
 
   /**
-   * Pointer to an object that
-   * encapsulated the actual data
-   * type of the predicate given to
-   * the constructor.
+   * Pointer to an object that encapsulated the actual data type of the
+   * predicate given to the constructor.
    */
   const PredicateBase *predicate;
 
@@ -738,14 +636,13 @@ private:
 
 
 /**
- * Create an object of type FilteredIterator given the base iterator
- * and predicate.  This function makes the creation of temporary
- * objects (for example as function arguments) a lot simpler because
- * one does not have to explicitly specify the type of the base
- * iterator by hand -- it is deduced automatically here.
+ * Create an object of type FilteredIterator given the base iterator and
+ * predicate.  This function makes the creation of temporary objects (for
+ * example as function arguments) a lot simpler because one does not have to
+ * explicitly specify the type of the base iterator by hand -- it is deduced
+ * automatically here.
  *
- * @author Wolfgang Bangerth
- * @relates FilteredIterator
+ * @author Wolfgang Bangerth @relates FilteredIterator
  */
 template <typename BaseIterator, typename Predicate>
 FilteredIterator<BaseIterator>
index ee15401d7ec25c5267943de7849beed2f42e5201..a73d556ebfe368b5d63f72119715cd8f65b618be 100644 (file)
@@ -36,17 +36,15 @@ template <typename number> class SparseMatrix;
  * This namespace provides a collection of functions for generating
  * triangulations for some basic geometries.
  *
- * Some of these functions receive a flag @p colorize. If this is
- * set, parts of the boundary receive different boundary indicators
- * (@ref GlossBoundaryIndicator),
- * allowing them to be distinguished for the purpose of attaching geometry
- * objects and evaluating different boundary conditions.
+ * Some of these functions receive a flag @p colorize. If this is set, parts
+ * of the boundary receive different boundary indicators (@ref
+ * GlossBoundaryIndicator), allowing them to be distinguished for the purpose
+ * of attaching geometry objects and evaluating different boundary conditions.
  *
  * This namespace also provides a function
  * GridGenerator::laplace_transformation that smoothly transforms a domain
- * into another one. This can be used to
- * transform basic geometries to more complicated ones, like a
- * shell to a grid of an airfoil, for example.
+ * into another one. This can be used to transform basic geometries to more
+ * complicated ones, like a shell to a grid of an airfoil, for example.
  *
  * @ingroup grid
  */
@@ -58,16 +56,15 @@ namespace GridGenerator
    */
 
   /**
-   * Initialize the given triangulation with a hypercube (line in 1D,
-   * square in 2D, etc) consisting of exactly one cell. The hypercube
-   * volume is the tensor product interval
-   * $[left,right]^{\text{dim}}$ in the present number of
-   * dimensions, where the limits are given as arguments. They default
-   * to zero and unity, then producing the unit hypercube. If the
-   * argument `colorize` is false, all boundary indicators are set to
-   * zero ("not colorized") for 2d and 3d. If it is true, the boundary
-   * is colorized as in hyper_rectangle(). In 1d the indicators are
-   * always colorized, see hyper_rectangle().
+   * Initialize the given triangulation with a hypercube (line in 1D, square
+   * in 2D, etc) consisting of exactly one cell. The hypercube volume is the
+   * tensor product interval $[left,right]^{\text{dim}}$ in the present number
+   * of dimensions, where the limits are given as arguments. They default to
+   * zero and unity, then producing the unit hypercube. If the argument
+   * `colorize` is false, all boundary indicators are set to zero ("not
+   * colorized") for 2d and 3d. If it is true, the boundary is colorized as in
+   * hyper_rectangle(). In 1d the indicators are always colorized, see
+   * hyper_rectangle().
    *
    * @image html hyper_cubes.png
    *
@@ -190,8 +187,8 @@ namespace GridGenerator
    * material_id argument is a dim-dimensional array that, for each cell,
    * indicates which material_id should be set. In addition, and this is the
    * major new functionality, if the material_id of a cell is <tt>(unsigned
-   * char)(-1)</tt>, then that cell is deleted from the triangulation,
-   * i.e. the domain will have a void there.
+   * char)(-1)</tt>, then that cell is deleted from the triangulation, i.e.
+   * the domain will have a void there.
    */
   template <int dim>
   void
@@ -227,21 +224,18 @@ namespace GridGenerator
                  const bool           colorize=false) DEAL_II_DEPRECATED;
 
   /**
-   * A parallelepiped. The first corner point is the origin. The
-   * <tt>dim</tt> adjacent points are vectors describing the edges of
-   * the parallelepiped with respect to the origin. Additional points
-   * are sums of these dim vectors. Colorizing is done according to
-   * hyper_rectangle().
+   * A parallelepiped. The first corner point is the origin. The <tt>dim</tt>
+   * adjacent points are vectors describing the edges of the parallelepiped
+   * with respect to the origin. Additional points are sums of these dim
+   * vectors. Colorizing is done according to hyper_rectangle().
    *
-   * @note This function silently reorders the vertices on the cells
-   * to lexiographic ordering (see
-   * <code>GridReordering::reorder_grid</code>). In other words, if
-   * reodering of the vertices does occur, the ordering of vertices in
-   * the array of <code>corners</code> will no longer refer to the
+   * @note This function silently reorders the vertices on the cells to
+   * lexiographic ordering (see <code>GridReordering::reorder_grid</code>). In
+   * other words, if reodering of the vertices does occur, the ordering of
+   * vertices in the array of <code>corners</code> will no longer refer to the
    * same triangulation.
    *
-   * @note The triangulation needs to be void upon calling this
-   * function.
+   * @note The triangulation needs to be void upon calling this function.
    */
   template <int dim>
   void
@@ -250,16 +244,14 @@ namespace GridGenerator
                   const bool          colorize = false);
 
   /**
-   * A subdivided parallelepiped. The first corner point is the
-   * origin. The <tt>dim</tt> adjacent points are vectors describing
-   * the edges of the parallelepiped with respect to the
-   * origin. Additional points are sums of these dim vectors. The
-   * variable @p n_subdivisions designates the number of subdivisions
-   * in each of the <tt>dim</tt> directions. Colorizing is done
-   * according to hyper_rectangle().
+   * A subdivided parallelepiped. The first corner point is the origin. The
+   * <tt>dim</tt> adjacent points are vectors describing the edges of the
+   * parallelepiped with respect to the origin. Additional points are sums of
+   * these dim vectors. The variable @p n_subdivisions designates the number
+   * of subdivisions in each of the <tt>dim</tt> directions. Colorizing is
+   * done according to hyper_rectangle().
    *
-   * @note The triangulation needs to be void upon calling this
-   * function.
+   * @note The triangulation needs to be void upon calling this function.
    */
   template <int dim>
   void
@@ -269,12 +261,11 @@ namespace GridGenerator
                              const bool           colorize = false);
 
   /**
-   * A subdivided parallelepiped, ie. the same as above, but where the
-   * number of subdivisions in each of the <tt>dim</tt> directions may
-   * vary. Colorizing is done according to hyper_rectangle().
+   * A subdivided parallelepiped, ie. the same as above, but where the number
+   * of subdivisions in each of the <tt>dim</tt> directions may vary.
+   * Colorizing is done according to hyper_rectangle().
    *
-   * @note The triangulation needs to be void upon calling this
-   * function.
+   * @note The triangulation needs to be void upon calling this function.
    */
   template <int dim>
   void
@@ -404,11 +395,10 @@ namespace GridGenerator
 
   /**
    * Initialize the given triangulation with a hyper-L (in 2d or 3d)
-   *  consisting of exactly
-   * <tt>2^dim-1</tt> cells. It produces the hypercube with the interval
-   * [<i>left,right</i>] without the hypercube made out of the interval
-   * [<i>(a+b)/2,b</i>]. This will result in the classical L-shape in 2d.
-   * The shape will look like the following in 3d:
+   * consisting of exactly <tt>2^dim-1</tt> cells. It produces the hypercube
+   * with the interval [<i>left,right</i>] without the hypercube made out of
+   * the interval [<i>(a+b)/2,b</i>]. This will result in the classical
+   * L-shape in 2d. The shape will look like the following in 3d:
    *
    * @image html hyper_l.png
    *
@@ -432,10 +422,9 @@ namespace GridGenerator
    * y=left</tt> to the center of the square at <tt>x=y=(left+right)/2</tt>.
    *
    * In 3d, the 2d domain is just extended in the <i>z</i>-direction, such
-   * that a plane cuts the lower half of a rectangle in two.
-
-   * This function is declared to exist for triangulations of all space
-   * dimensions, but throws an error if called in 1d.
+   * that a plane cuts the lower half of a rectangle in two.  This function is
+   * declared to exist for triangulations of all space dimensions, but throws
+   * an error if called in 1d.
    *
    * @note The triangulation needs to be void upon calling this function.
    */
@@ -461,13 +450,12 @@ namespace GridGenerator
    * is zero (as is the default), then it is computed adaptively such that the
    * resulting elements have the least aspect ratio.
    *
-   * In 3d, only certain numbers are allowed, 6 for a surface based
-   * on a hexahedron (i.e. 6 panels on the inner sphere extruded in radial
+   * In 3d, only certain numbers are allowed, 6 for a surface based on a
+   * hexahedron (i.e. 6 panels on the inner sphere extruded in radial
    * direction to form 6 cells), 12 for the rhombic dodecahedron, and 96 (see
    * below). These give rise to the following meshes upon one refinement:
    *
-   * @image html hypershell3d-6.png
-   * @image html hypershell3d-12.png
+   * @image html hypershell3d-6.png @image html hypershell3d-12.png
    *
    * Neither of these meshes is particularly good since one ends up with
    * poorly shaped cells at the inner edge upon refinement. For example, this
@@ -485,15 +473,14 @@ namespace GridGenerator
    * that the doubled radial lines on the cross section are artifacts of the
    * visualization):
    *
-   * @image html hyper_shell_12_cut.png
-   * @image html hyper_shell_96_cut.png
+   * @image html hyper_shell_12_cut.png @image html hyper_shell_96_cut.png
    *
-   * A different way to approach the problem with distorted cells
-   * is to attach appropriate manifold descriptions to the geometry created
-   * by this function. In the current context, this would involve the
+   * A different way to approach the problem with distorted cells is to attach
+   * appropriate manifold descriptions to the geometry created by this
+   * function. In the current context, this would involve the
    * SphericalManifold class. An example of how this works and what it leads
-   * to is shown in the documentation of the
-   * @ref manifold "documentation module on manifolds".
+   * to is shown in the documentation of the @ref manifold "documentation
+   * module on manifolds".
    *
    * @note This function is declared to exist for triangulations of all space
    * dimensions, but throws an error if called in 1d.
@@ -598,8 +585,7 @@ namespace GridGenerator
    * @param R The radius of the circle, which forms the middle line of the
    * torus containing the loop of cells. Must be greater than @p r.
    *
-   * @param r The inner radius of the
-   * torus.
+   * @param r The inner radius of the torus.
    */
   void torus (Triangulation<2,3> &tria,
               const double        R,
@@ -611,24 +597,18 @@ namespace GridGenerator
    * in the middle. Square and circle are centered at the origin. In 3d, this
    * geometry is extruded in $z$ direction to the interval $[0,L]$.
    *
-   *  @image html cubes_hole.png
+   * @image html cubes_hole.png
    *
    * It is implemented in 2d and 3d, and takes the following arguments:
    *
-   * @arg @p inner_radius: radius of the
-   *    internal hole
-   * @arg @p  outer_radius: half of the edge length of the square
-   * @arg @p L: extension in @p z-direction (only used in 3d)
-   * @arg @p repetitions: number of subdivisions
-   *      along the @p z-direction
-   * @arg @p colorize: whether to assign different
-   *     boundary indicators to different faces.
-   *    The colors are given in lexicographic
-   *    ordering for the flat faces (0 to 3 in 2d,
-   *    0 to 5 in 3d) plus the curved hole
-   *    (4 in 2d, and 6 in 3d).
-   *    If @p colorize is set to false, then flat faces
-   *    get the number 0 and the hole gets number 1.
+   * @arg @p inner_radius: radius of the internal hole @arg @p  outer_radius:
+   * half of the edge length of the square @arg @p L: extension in @p
+   * z-direction (only used in 3d) @arg @p repetitions: number of subdivisions
+   * along the @p z-direction @arg @p colorize: whether to assign different
+   * boundary indicators to different faces. The colors are given in
+   * lexicographic ordering for the flat faces (0 to 3 in 2d, 0 to 5 in 3d)
+   * plus the curved hole (4 in 2d, and 6 in 3d). If @p colorize is set to
+   * false, then flat faces get the number 0 and the hole gets number 1.
    */
   template<int dim>
   void hyper_cube_with_cylindrical_hole (
@@ -644,9 +624,12 @@ namespace GridGenerator
    * together again. This results in a kind of moebius-loop.
    *
    * @param tria        The triangulation to be worked on.
-   * @param n_cells     The number of cells in the loop. Must be greater than 4.
-   * @param n_rotations The number of rotations (Pi/2 each) to be performed before glueing the loop together.
-   * @param R           The radius of the circle, which forms the middle line of the torus containing the loop of cells. Must be greater than @p r.
+   * @param n_cells     The number of cells in the loop. Must be greater than
+   * 4.
+   * @param n_rotations The number of rotations (Pi/2 each) to be performed
+   * before glueing the loop together.
+   * @param R           The radius of the circle, which forms the middle line
+   * of the torus containing the loop of cells. Must be greater than @p r.
    * @param r           The radius of the cylinder bend together as loop.
    */
   void moebius (Triangulation<3,3> &tria,
@@ -701,53 +684,29 @@ namespace GridGenerator
                         Triangulation<dim, spacedim>       &result);
 
   /**
-   * Given the two triangulations
-   * specified as the first two
-   * arguments, create the
-   * triangulation that contains
-   * the finest cells of both
-   * triangulation and store it in
-   * the third parameter. Previous
-   * content of @p result will be
-   * deleted.
-   *
-   * @note This function is intended
-   * to create an adaptively refined
-   * triangulation that contains the
-   * <i>most refined cells</i> from
-   * two input triangulations that
-   * were derived from the <i>same</i>
-   * coarse grid by adaptive refinement.
-   * This is an operation sometimes
-   * needed when one solves for two
-   * variables of a coupled problem
-   * on separately refined meshes on
-   * the same domain (for example
-   * because these variables have
-   * boundary layers in different places)
-   * but then needs to compute something
-   * that involves both variables or
-   * wants to output the result into a
-   * single file. In both cases, in
-   * order not to lose information,
-   * the two solutions can not be
-   * interpolated onto the respectively
-   * other mesh because that may be
-   * coarser than the ones on which
-   * the variable was computed. Rather,
-   * one needs to have a mesh for the
-   * domain that is at least as fine
-   * as each of the two initial meshes.
-   * This function computes such a mesh.
-   *
-   * @note If you want to create
-   * a mesh that is the merger of
-   * two other coarse meshes, for
-   * example in order to compose a mesh
-   * for a complicated geometry from
-   * meshes for simpler geometries,
-   * then this is not the function for you. Instead, consider
-   * GridGenerator::merge_triangulations().
+   * Given the two triangulations specified as the first two arguments, create
+   * the triangulation that contains the finest cells of both triangulation
+   * and store it in the third parameter. Previous content of @p result will
+   * be deleted.
+   *
+   * @note This function is intended to create an adaptively refined
+   * triangulation that contains the <i>most refined cells</i> from two input
+   * triangulations that were derived from the <i>same</i> coarse grid by
+   * adaptive refinement. This is an operation sometimes needed when one
+   * solves for two variables of a coupled problem on separately refined
+   * meshes on the same domain (for example because these variables have
+   * boundary layers in different places) but then needs to compute something
+   * that involves both variables or wants to output the result into a single
+   * file. In both cases, in order not to lose information, the two solutions
+   * can not be interpolated onto the respectively other mesh because that may
+   * be coarser than the ones on which the variable was computed. Rather, one
+   * needs to have a mesh for the domain that is at least as fine as each of
+   * the two initial meshes. This function computes such a mesh.
+   *
+   * @note If you want to create a mesh that is the merger of two other coarse
+   * meshes, for example in order to compose a mesh for a complicated geometry
+   * from meshes for simpler geometries, then this is not the function for
+   * you. Instead, consider GridGenerator::merge_triangulations().
    */
   template <int dim, int spacedim>
   void
@@ -757,11 +716,11 @@ namespace GridGenerator
 
 
   /**
-   * Take a 2d Triangulation that is being extruded in z direction
-   * by the total height of @p height using @p n_slices slices (minimum is 2).
-   * The boundary indicators of the faces of @p input are going to be assigned
-   * to the corresponding side walls in z direction. The bottom and top
-   * get the next two free boundary indicators.
+   * Take a 2d Triangulation that is being extruded in z direction by the
+   * total height of @p height using @p n_slices slices (minimum is 2). The
+   * boundary indicators of the faces of @p input are going to be assigned to
+   * the corresponding side walls in z direction. The bottom and top get the
+   * next two free boundary indicators.
    */
   void
   extrude_triangulation (const Triangulation<2, 2> &input,
@@ -770,26 +729,24 @@ namespace GridGenerator
                          Triangulation<3,3>        &result);
 
   /**
-   * Given an input triangulation @p in_tria, this function makes a new
-   * flat triangulation @p out_tria which contains a single level with
-   * all active cells of the input triangulation. If spacedim1 and
-   * spacedim2 are different, only the smallest spacedim components of
-   * the vertices are copied over. This is useful to create a
-   * Triangulation<2,3> out of a Triangulation<2,2>, or to project a
-   * Triangulation<2,3> into a Triangulation<2,2>, by neglecting the z
-   * components of the vertices.
+   * Given an input triangulation @p in_tria, this function makes a new flat
+   * triangulation @p out_tria which contains a single level with all active
+   * cells of the input triangulation. If spacedim1 and spacedim2 are
+   * different, only the smallest spacedim components of the vertices are
+   * copied over. This is useful to create a Triangulation<2,3> out of a
+   * Triangulation<2,2>, or to project a Triangulation<2,3> into a
+   * Triangulation<2,2>, by neglecting the z components of the vertices.
    *
-   * No internal checks are performed on the vertices, which are
-   * assumed to make sense topologically in the target #spacedim2
-   * dimensional space. If this is not the case, you will encounter
-   * problems when using the triangulation later on.
+   * No internal checks are performed on the vertices, which are assumed to
+   * make sense topologically in the target #spacedim2 dimensional space. If
+   * this is not the case, you will encounter problems when using the
+   * triangulation later on.
    *
-   * All informations about cell manifold_ids and material ids are
-   * copied from one triangulation to the other, and only the boundary
-   * manifold_ids and boundary_ids are copied over from the faces of
-   * @p in_tria to the faces of @p out_tria. If you need to specify
-   * manifold ids on interior faces, they have to be specified
-   * manually after the triangulation is created.
+   * All informations about cell manifold_ids and material ids are copied from
+   * one triangulation to the other, and only the boundary manifold_ids and
+   * boundary_ids are copied over from the faces of @p in_tria to the faces of
+   * @p out_tria. If you need to specify manifold ids on interior faces, they
+   * have to be specified manually after the triangulation is created.
    *
    * This function will fail if the input Triangulation is of type
    * parallel::distributed::Triangulation, as well as when the input
@@ -806,7 +763,8 @@ namespace GridGenerator
    */
 
   /**
-   * @name Creating lower-dimensional meshes from parts of higher-dimensional meshes
+   * @name Creating lower-dimensional meshes from parts of higher-dimensional
+   * meshes
    * @{
    */
 
@@ -829,85 +787,48 @@ namespace GridGenerator
 #endif
 
   /**
-   * This function implements a boundary
-   * subgrid extraction.  Given a
-   * <dim,spacedim>-Triangulation (the
-   * "volume mesh") the function extracts a
-   * subset of its boundary (the "surface
-   * mesh").  The boundary to be extracted
-   * is specified by a list of
-   * boundary_ids.  If none is specified
-   * the whole boundary will be
-   * extracted. The function is used in
-   * step-38.
-   *
-   * The function also builds a mapping linking the
-   * cells on the surface mesh to the
-   * corresponding faces on the volume
-   * one. This mapping is the return value
-   * of the function.
-   *
-   * @note The function builds the surface
-   * mesh by creating a coarse mesh from
-   * the selected faces of the coarse cells
-   * of the volume mesh. It copies the
-   * boundary indicators of these faces to
-   * the cells of the coarse surface
-   * mesh. The surface mesh is then refined
-   * in the same way as the faces of the
-   * volume mesh are. In order to ensure
-   * that the surface mesh has the same
-   * vertices as the volume mesh, it is
-   * therefore important that you assign
-   * appropriate boundary objects through
-   * Triangulation::set_boundary to the
-   * surface mesh object before calling
-   * this function. If you don't, the
-   * refinement will happen under the
-   * assumption that all faces are straight
-   * (i.e using the StraightBoundary class)
-   * rather than any curved boundary object
-   * you may want to use to determine the
-   * location of new vertices.
-   *
-   *
-   * @tparam Container A type that satisfies the
-   * requirements of a mesh container (see @ref GlossMeshAsAContainer).
-   * The map that is returned will
-   * be between cell
-   * iterators pointing into the container describing the surface mesh
-   * and face
-   * iterators of the volume
-   * mesh container. If the Container argument is
-   * DoFHandler of hp::DoFHandler, then
-   * the function will
-   * re-build the triangulation
-   * underlying the second argument
-   * and return a map between
-   * appropriate iterators into the Container arguments. However,
-   * the function will not actually
-   * distribute degrees of freedom
-   * on this newly created surface
-   * mesh.
-   *
-   * @note The algorithm outlined
-   * above assumes that all faces
-   * on higher refinement levels
-   * always have exactly the same
-   * boundary indicator as their
-   * parent face. Consequently, we
-   * can start with coarse level
-   * faces and build the surface
-   * mesh based on that. It would
-   * not be very difficult to
-   * extend the function to also
-   * copy boundary indicators from
-   * finer level faces to their
-   * corresponding surface mesh
-   * cells, for example to
-   * accommodate different geometry
-   * descriptions in the case of
-   * curved boundaries.
+   * This function implements a boundary subgrid extraction.  Given a
+   * <dim,spacedim>-Triangulation (the "volume mesh") the function extracts a
+   * subset of its boundary (the "surface mesh").  The boundary to be
+   * extracted is specified by a list of boundary_ids.  If none is specified
+   * the whole boundary will be extracted. The function is used in step-38.
+   *
+   * The function also builds a mapping linking the cells on the surface mesh
+   * to the corresponding faces on the volume one. This mapping is the return
+   * value of the function.
+   *
+   * @note The function builds the surface mesh by creating a coarse mesh from
+   * the selected faces of the coarse cells of the volume mesh. It copies the
+   * boundary indicators of these faces to the cells of the coarse surface
+   * mesh. The surface mesh is then refined in the same way as the faces of
+   * the volume mesh are. In order to ensure that the surface mesh has the
+   * same vertices as the volume mesh, it is therefore important that you
+   * assign appropriate boundary objects through Triangulation::set_boundary
+   * to the surface mesh object before calling this function. If you don't,
+   * the refinement will happen under the assumption that all faces are
+   * straight (i.e using the StraightBoundary class) rather than any curved
+   * boundary object you may want to use to determine the location of new
+   * vertices.
+   *
+   *
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer). The map that is returned will
+   * be between cell iterators pointing into the container describing the
+   * surface mesh and face iterators of the volume mesh container. If the
+   * Container argument is DoFHandler of hp::DoFHandler, then the function
+   * will re-build the triangulation underlying the second argument and return
+   * a map between appropriate iterators into the Container arguments.
+   * However, the function will not actually distribute degrees of freedom on
+   * this newly created surface mesh.
+   *
+   * @note The algorithm outlined above assumes that all faces on higher
+   * refinement levels always have exactly the same boundary indicator as
+   * their parent face. Consequently, we can start with coarse level faces and
+   * build the surface mesh based on that. It would not be very difficult to
+   * extend the function to also copy boundary indicators from finer level
+   * faces to their corresponding surface mesh cells, for example to
+   * accommodate different geometry descriptions in the case of curved
+   * boundaries.
    */
   template <template <int,int> class Container, int dim, int spacedim>
 #ifndef _MSC_VER
@@ -932,9 +853,9 @@ namespace GridGenerator
 
   /**
    * This function transforms the @p Triangulation @p tria smoothly to a
-   * domain that is described by the boundary points in the map @p
-   * new_points. This map maps the point indices to the boundary points in the
-   * transformed domain.
+   * domain that is described by the boundary points in the map @p new_points.
+   * This map maps the point indices to the boundary points in the transformed
+   * domain.
    *
    * Note, that the @p Triangulation is changed in-place, therefore you don't
    * need to keep two triangulations, but the given triangulation is changed
@@ -942,14 +863,13 @@ namespace GridGenerator
    *
    * In 1d, this function is not currently implemented.
    *
-   * An optional @p coefficient for the Laplace problem an be used to control the amount of
-   * mesh deformation in different parts of the domain.
-   * Larger values make cells less prone to deformation (effectively increasing their stiffness).
-   * The coefficient is evaluated in the coordinate system of the old,
-   * undeformed configuration of the triangulation as input, i.e., before
-   * the transformation is applied.
-   * Should this function be provided, sensible results can only be expected if
-   * all coefficients are positive.
+   * An optional @p coefficient for the Laplace problem an be used to control
+   * the amount of mesh deformation in different parts of the domain. Larger
+   * values make cells less prone to deformation (effectively increasing their
+   * stiffness). The coefficient is evaluated in the coordinate system of the
+   * old, undeformed configuration of the triangulation as input, i.e., before
+   * the transformation is applied. Should this function be provided, sensible
+   * results can only be expected if all coefficients are positive.
    *
    * @deprecated This function has been moved to GridTools::laplace_transform
    */
index e20a12f2fc4ecdfb0e02efcc1e76c6fdb0dd3d87..f8ed49308aa7c7a4937083779af3339cb49ced09 100644 (file)
@@ -35,69 +35,67 @@ struct SubCellData;
 /**
  * This class implements an input mechanism for grid data. It allows to read a
  * grid structure into a triangulation object. At present, UCD (unstructured
- * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are supported as
- * input format for grid data. Any numerical data other than geometric
- * (vertex locations) and topological (how vertices form cells) information is
- * ignored.
+ * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are
+ * supported as input format for grid data. Any numerical data other than
+ * geometric (vertex locations) and topological (how vertices form cells)
+ * information is ignored.
  *
- * @note Since deal.II only supports line, quadrilateral and hexahedral meshes,
- * the functions in this class can only read meshes that consist exclusively
- * of such cells. If you absolutely need to work with a mesh that uses triangles
- * or tetrahedra, then your only option is to convert the mesh to quadrilaterals
- * and hexahedra. A tool that can do this is tethex, see
+ * @note Since deal.II only supports line, quadrilateral and hexahedral
+ * meshes, the functions in this class can only read meshes that consist
+ * exclusively of such cells. If you absolutely need to work with a mesh that
+ * uses triangles or tetrahedra, then your only option is to convert the mesh
+ * to quadrilaterals and hexahedra. A tool that can do this is tethex, see
  * http://code.google.com/p/tethex/wiki/Tethex .
  *
- * The mesh you read will form the coarsest level of a @p Triangulation object.
- * As such, it must not contain hanging nodes or other forms or adaptive
- * refinement and strange things will happen if the mesh represented by the
- * input file does in fact have them. This
- * is due to the fact that most mesh description formats do not store
- * neighborship information between cells, so the grid reading functions have
- * to regenerate it. They do so by checking whether two cells have a common
- * face. If there are hanging nodes in a triangulation, adjacent cells have no
- * common (complete) face, so the grid reader concludes that the adjacent
- * cells have no neighbors along these faces and must therefore be at the
- * boundary. In effect, an internal crack of the domain is introduced this
- * way. Since such cases are very hard to detect (how is GridIn supposed to
- * decide whether a place where the faces of two small cells coincide with
- * the face or a larger cell is in fact a hanging node associated with local
- * refinement, or is indeed meant to be a crack in the domain?), the library
- * does not make any attempt to catch such situations, and you will get a triangulation
- * that probably does not do what you want. If your goal is to save and later
- * read again a triangulation that has been adaptively refined, then this
- * class is not your solution; rather take a look at the
- * PersistentTriangulation class.
+ * The mesh you read will form the coarsest level of a @p Triangulation
+ * object. As such, it must not contain hanging nodes or other forms or
+ * adaptive refinement and strange things will happen if the mesh represented
+ * by the input file does in fact have them. This is due to the fact that most
+ * mesh description formats do not store neighborship information between
+ * cells, so the grid reading functions have to regenerate it. They do so by
+ * checking whether two cells have a common face. If there are hanging nodes
+ * in a triangulation, adjacent cells have no common (complete) face, so the
+ * grid reader concludes that the adjacent cells have no neighbors along these
+ * faces and must therefore be at the boundary. In effect, an internal crack
+ * of the domain is introduced this way. Since such cases are very hard to
+ * detect (how is GridIn supposed to decide whether a place where the faces of
+ * two small cells coincide with the face or a larger cell is in fact a
+ * hanging node associated with local refinement, or is indeed meant to be a
+ * crack in the domain?), the library does not make any attempt to catch such
+ * situations, and you will get a triangulation that probably does not do what
+ * you want. If your goal is to save and later read again a triangulation that
+ * has been adaptively refined, then this class is not your solution; rather
+ * take a look at the PersistentTriangulation class.
  *
  * @note It is not uncommon to experience unexpected problems when reading
  * generated meshes for the first time using this class. If this applies to
- * you, be sure to read the documentation right until the end, and
- * also read the documentation of the GridReordering class.
+ * you, be sure to read the documentation right until the end, and also read
+ * the documentation of the GridReordering class.
  *
- * To read grid data, the triangulation to be fed with has to be empty.
- * When giving a file which does not contain the assumed information or
- * which does not keep to the right format, the state of the triangulation
- * will be undefined afterwards. Upon input, only lines in one dimension
- * and line and quads in two dimensions are accepted. All other cell types
- * (e.g. triangles in two dimensions, quads and hexes in 3d) are rejected.
- * The vertex and cell numbering in the input file, which
- * need not be consecutively, is lost upon transfer to the triangulation
- * object, since this one needs consecutively numbered elements.
+ * To read grid data, the triangulation to be fed with has to be empty. When
+ * giving a file which does not contain the assumed information or which does
+ * not keep to the right format, the state of the triangulation will be
+ * undefined afterwards. Upon input, only lines in one dimension and line and
+ * quads in two dimensions are accepted. All other cell types (e.g. triangles
+ * in two dimensions, quads and hexes in 3d) are rejected. The vertex and cell
+ * numbering in the input file, which need not be consecutively, is lost upon
+ * transfer to the triangulation object, since this one needs consecutively
+ * numbered elements.
  *
- * Material indicators are accepted to denote the material ID of cells and
- * to denote boundary part indication for lines in 2D. Read the according
- * sections in the documentation of the Triangulation class for
- * further details.
+ * Material indicators are accepted to denote the material ID of cells and to
+ * denote boundary part indication for lines in 2D. Read the according
+ * sections in the documentation of the Triangulation class for further
+ * details.
  *
  *
  * <h3>Supported input formats</h3>
  *
  * At present, the following input formats are supported:
  * <ul>
- * <li> @p UCD (unstructured cell data) format: this format is used
- * for grid input as well as data output. If there are data vectors in
- * the input file, they are ignored, as we are only interested in the
- * grid in this class. The UCD format requires the vertices to be
- * in following ordering: in 2d
+ * <li> @p UCD (unstructured cell data) format: this format is used for grid
+ * input as well as data output. If there are data vectors in the input file,
+ * they are ignored, as we are only interested in the grid in this class. The
+ * UCD format requires the vertices to be in following ordering: in 2d
  * @verbatim
  *      3-----2
  *      |     |
@@ -118,37 +116,34 @@ struct SubCellData;
  *     |/       /       |       |/
  *     0-------1        0-------1
  * @endverbatim
- * Note, that this ordering is different from the deal.II numbering
- * scheme, see the Triangulation class.  The exact description of the
- * UCD format can be found in the AVS Explorer manual (see
- * http://www.avs.com).  The @p UCD format can be read by the
- * read_ucd() function.
+ * Note, that this ordering is different from the deal.II numbering scheme,
+ * see the Triangulation class.  The exact description of the UCD format can
+ * be found in the AVS Explorer manual (see http://www.avs.com).  The @p UCD
+ * format can be read by the read_ucd() function.
  *
  * <li> <tt>DB mesh</tt> format: this format is used by the @p BAMG mesh
- * generator (see
- * http://www-rocq.inria.fr/gamma/cdrom/www/bamg/eng.htm. The
- * documentation of the format in the @p BAMG manual is very
- * incomplete, so we don't actually parse many of the fields of the
- * output since we don't know their meaning, but the data that is read
- * is enough to build up the mesh as intended by the mesh generator.
- * This format can be read by the read_dbmesh() function.
+ * generator (see http://www-rocq.inria.fr/gamma/cdrom/www/bamg/eng.htm. The
+ * documentation of the format in the @p BAMG manual is very incomplete, so we
+ * don't actually parse many of the fields of the output since we don't know
+ * their meaning, but the data that is read is enough to build up the mesh as
+ * intended by the mesh generator. This format can be read by the
+ * read_dbmesh() function.
  *
- * <li> @p XDA format: this is a rather simple format used by the MGF
- * code. We don't have an exact specification of the format, but the reader
- * can read in several example files. If the reader does not grok your files,
- * it should be fairly simple to extend it.
+ * <li> @p XDA format: this is a rather simple format used by the MGF code. We
+ * don't have an exact specification of the format, but the reader can read in
+ * several example files. If the reader does not grok your files, it should be
+ * fairly simple to extend it.
  *
- * <li> <tt>Gmsh 1.0 mesh</tt> format: this format is used by the @p
- * GMSH mesh generator (see http://www.geuz.org/gmsh/ ). The
- * documentation in the @p GMSH manual explains how to generate meshes
- * compatible with the deal.II library (i.e. quads rather than
- * triangles). In order to use this format, Gmsh has to output the
- * file in the old format 1.0. This is done adding the line
- * "Mesh.MshFileVersion = 1" to the input file.
+ * <li> <tt>Gmsh 1.0 mesh</tt> format: this format is used by the @p GMSH mesh
+ * generator (see http://www.geuz.org/gmsh/ ). The documentation in the @p
+ * GMSH manual explains how to generate meshes compatible with the deal.II
+ * library (i.e. quads rather than triangles). In order to use this format,
+ * Gmsh has to output the file in the old format 1.0. This is done adding the
+ * line "Mesh.MshFileVersion = 1" to the input file.
  *
  * <li> <tt>Gmsh 2.0 mesh</tt> format: this is a variant of the above format.
- * The read_msh() function automatically determines whether an input file
- * is version 1 or version 2.
+ * The read_msh() function automatically determines whether an input file is
+ * version 1 or version 2.
  *
  * <li> <tt>Tecplot</tt> format: this format is used by @p TECPLOT and often
  * serves as a basis for data exchange between different applications. Note,
@@ -156,35 +151,36 @@ struct SubCellData;
  * read.
  *
  * <li> <tt>UNV</tt> format: this format is generated by the Salome mesh
- * generator, see http://www.salome-platform.org/ .
- * The sections of the format that the GridIn::read_unv function supports are
- * documented here:
+ * generator, see http://www.salome-platform.org/ . The sections of the format
+ * that the GridIn::read_unv function supports are documented here:
  * <ul>
- *  <li> section 2411: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2411.htm
- *  <li> section 2412: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2412.htm
- *  <li> section 2467: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2467.htm
- *  <li> all sections of this format, even if they may not be supported in
- *  our reader, can be found here:
- *  http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/file-formats
+ * <li> section 2411: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2411.htm
+ * <li> section 2412: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2412.htm
+ * <li> section 2467: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2467.htm
+ * <li> all sections of this format, even if they may not be supported in our
+ * reader, can be found here: http://www.sdrl.uc.edu/universal-file-formats-
+ * for-modal-analysis-testing-1/file-format-storehouse/file-formats
  * </ul>
- * Note that Salome, let's say in 2D, can only make a quad mesh on an object that
- * has exactly 4 edges (or 4 pieces of the boundary). That means, that if you have
- * a more complicated object and would like to mesh it with quads, you will need
- * to decompose the object into >= 2 separate objects. Then 1) each of these
- * separate objects is meshed, 2) the appropriate groups of cells and/or faces
- * associated with each of these separate objects are created, 3) a compound
- * mesh is built up, and 4) all numbers that might be associated with some of
- * the internal faces of this compound mesh are removed.
+ * Note that Salome, let's say in 2D, can only make a quad mesh on an object
+ * that has exactly 4 edges (or 4 pieces of the boundary). That means, that if
+ * you have a more complicated object and would like to mesh it with quads,
+ * you will need to decompose the object into >= 2 separate objects. Then 1)
+ * each of these separate objects is meshed, 2) the appropriate groups of
+ * cells and/or faces associated with each of these separate objects are
+ * created, 3) a compound mesh is built up, and 4) all numbers that might be
+ * associated with some of the internal faces of this compound mesh are
+ * removed.
  *
  * <li> <tt>VTK</tt> format: VTK Unstructured Grid Legacy file reader
- * generator. The reader can handle only Unstructured Grid format of data
- * at present for 2D & 3D geometries.
- * The documentation for the general legacy vtk file, including Unstructured Grid format
- * can be found here:
+ * generator. The reader can handle only Unstructured Grid format of data at
+ * present for 2D & 3D geometries. The documentation for the general legacy
+ * vtk file, including Unstructured Grid format can be found here:
  * http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html
  *
- * The VTK format requires the vertices to be
- * in following ordering: in 2d
+ * The VTK format requires the vertices to be in following ordering: in 2d
  * @verbatim
  *      3-----2
  *      |     |
@@ -213,23 +209,22 @@ struct SubCellData;
  * plug-in script can be found on the deal.II wiki page,
  * http://code.google.com/p/dealii/wiki/MeshInputAndOutput .
  *
- * There is also a little program <code>bin/mesh_conversion</code> (in the directory
- * where deal.II was installed), written by Jean-Paul Pelteret, that can
- * convert Cubit ABAQUS files into the UCD format that can be read in as
- * discussed above. The program was designed with the intention of
- * exporting geometries with complex boundary condition surfaces and
- * multiple materials from Cubit - information which is currently not
- * easily obtained through Cubit's python interface. Using the the
- * program is simple: to use it, it needs to be built and run with the
- * command
+ * There is also a little program <code>bin/mesh_conversion</code> (in the
+ * directory where deal.II was installed), written by Jean-Paul Pelteret, that
+ * can convert Cubit ABAQUS files into the UCD format that can be read in as
+ * discussed above. The program was designed with the intention of exporting
+ * geometries with complex boundary condition surfaces and multiple materials
+ * from Cubit - information which is currently not easily obtained through
+ * Cubit's python interface. Using the the program is simple: to use it, it
+ * needs to be built and run with the command
  * @code
  *  /path/to/deal.II/bin/mesh_conversion <spatial_dimension> /path/to/input_file.inp /path/to/output_file.ucd
  * @endcode.
- * More information is available in the readme file included with the
- * program and located in the <code>contrib/mesh_conversion/README.txt</code> file in
- * the deal.II source directory tree. Note that the program's copyright remains with its author
- * and that it is under a separate license than the rest of the
- * library.
+ * More information is available in the readme file included with the program
+ * and located in the <code>contrib/mesh_conversion/README.txt</code> file in
+ * the deal.II source directory tree. Note that the program's copyright
+ * remains with its author and that it is under a separate license than the
+ * rest of the library.
  *
  * To build the program, see the <code>doc/readmes.html</code> and
  * <code>doc/development/cmake.html</code> files.
@@ -238,16 +233,15 @@ struct SubCellData;
  *
  * <h3>Structure of input grid data. The GridReordering class</h3>
  *
- * It is your duty to use a correct numbering of vertices in the cell
- * list, i.e. for lines in 1d, you have to first give the vertex with
- * the lower coordinate value, then that with the higher coordinate
- * value. For quadrilaterals in two dimensions, the vertex indices in
- * the @p quad list have to be such that the vertices are numbered in
- * counter-clockwise sense.
+ * It is your duty to use a correct numbering of vertices in the cell list,
+ * i.e. for lines in 1d, you have to first give the vertex with the lower
+ * coordinate value, then that with the higher coordinate value. For
+ * quadrilaterals in two dimensions, the vertex indices in the @p quad list
+ * have to be such that the vertices are numbered in counter-clockwise sense.
  *
- * In two dimensions, another difficulty occurs, which has to do with the sense
- * of a quadrilateral. A quad consists of four lines which have a direction,
- * which is per definitionem as follows:
+ * In two dimensions, another difficulty occurs, which has to do with the
+ * sense of a quadrilateral. A quad consists of four lines which have a
+ * direction, which is per definitionem as follows:
  * @verbatim
  *   3-->--2
  *   |     |
@@ -255,38 +249,36 @@ struct SubCellData;
  *   |     |
  *   0-->--1
  * @endverbatim
- * Now, two adjacent cells must have a vertex numbering such that the direction
- * of the common side is the same. For example, the following two quads
+ * Now, two adjacent cells must have a vertex numbering such that the
+ * direction of the common side is the same. For example, the following two
+ * quads
  * @verbatim
  *   3---4---5
  *   |   |   |
  *   0---1---2
  * @endverbatim
- * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and
- * <tt>(1 2 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt>
- * when viewed from both cells.  The numbering <tt>(0 1 4 3)</tt> and
- * <tt>(5 4 1 2)</tt> would not be allowed, since the left quad would give the
- * common line the direction <tt>1->4</tt>, while the right one would want
- * to use <tt>4->1</tt>, leading to an ambiguity. The Triangulation
- * object is capable of detecting this special case, which can be
- * eliminated by rotating the indices of the right quad by
- * two. However, it would not know what to do if you gave the vertex
- * indices <tt>(4 1 2 5)</tt>, since then it would have to rotate by one
- * element or three, the decision which to take is not yet
+ * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and <tt>(1 2
+ * 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt> when
+ * viewed from both cells.  The numbering <tt>(0 1 4 3)</tt> and <tt>(5 4 1
+ * 2)</tt> would not be allowed, since the left quad would give the common
+ * line the direction <tt>1->4</tt>, while the right one would want to use
+ * <tt>4->1</tt>, leading to an ambiguity. The Triangulation object is capable
+ * of detecting this special case, which can be eliminated by rotating the
+ * indices of the right quad by two. However, it would not know what to do if
+ * you gave the vertex indices <tt>(4 1 2 5)</tt>, since then it would have to
+ * rotate by one element or three, the decision which to take is not yet
  * implemented.
  *
- * There are more ambiguous cases, where the triangulation may not
- * know what to do at all without the use of sophisticated
- * algorithms. Furthermore, similar problems exist in three space
- * dimensions, where faces and lines have orientations that need to be
- * taken care of.
+ * There are more ambiguous cases, where the triangulation may not know what
+ * to do at all without the use of sophisticated algorithms. Furthermore,
+ * similar problems exist in three space dimensions, where faces and lines
+ * have orientations that need to be taken care of.
  *
- * For this reason, the <tt>read_*</tt> functions of this class that read
- * in grids in various input formats call the GridReordering
- * class to bring the order of vertices that define the cells into an
- * ordering that satisfies the requiremenets of the
- * Triangulation class. Be sure to read the documentation of
- * that class if you experience unexpected problems when reading grids
+ * For this reason, the <tt>read_*</tt> functions of this class that read in
+ * grids in various input formats call the GridReordering class to bring the
+ * order of vertices that define the cells into an ordering that satisfies the
+ * requiremenets of the Triangulation class. Be sure to read the documentation
+ * of that class if you experience unexpected problems when reading grids
  * through this class.
  *
  *
@@ -316,12 +308,8 @@ class GridIn
 {
 public:
   /**
-   * List of possible mesh input
-   * formats. These values are used
-   * when calling the function
-   * read() in order to determine
-   * the actual reader to be
-   * called.
+   * List of possible mesh input formats. These values are used when calling
+   * the function read() in order to determine the actual reader to be called.
    */
   enum Format
   {
@@ -351,126 +339,93 @@ public:
   GridIn ();
 
   /**
-   * Attach this triangulation
-   * to be fed with the grid data.
+   * Attach this triangulation to be fed with the grid data.
    */
   void attach_triangulation (Triangulation<dim,spacedim> &tria);
 
   /**
-   * Read from the given stream. If
-   * no format is given,
-   * GridIn::Format::Default is
-   * used.
+   * Read from the given stream. If no format is given,
+   * GridIn::Format::Default is used.
    */
   void read (std::istream &in, Format format=Default);
 
   /**
-   * Open the file given by the
-   * string and call the previous
-   * function read(). This function
-   * uses the PathSearch mechanism
-   * to find files. The file class
+   * Open the file given by the string and call the previous function read().
+   * This function uses the PathSearch mechanism to find files. The file class
    * used is <code>MESH</code>.
    */
   void read (const std::string &in, Format format=Default);
 
   /**
-   * Read grid data from an vtk file.
-   * Numerical data is ignored.
+   * Read grid data from an vtk file. Numerical data is ignored.
    *
    * @author Mayank Sabharwal, Andreas Putz, 2013
    */
   void read_vtk(std::istream &in);
 
   /**
-   * Read grid data from an unv
-   * file as generated by the
-   * Salome mesh generator.
-   * Numerical data is ignored.
+   * Read grid data from an unv file as generated by the Salome mesh
+   * generator. Numerical data is ignored.
    *
-   * Note the comments on
-   * generating this file format in
-   * the general documentation of
-   * this class.
+   * Note the comments on generating this file format in the general
+   * documentation of this class.
    */
   void read_unv(std::istream &in);
 
   /**
-   * Read grid data from an ucd file.
-   * Numerical data is ignored.
+   * Read grid data from an ucd file. Numerical data is ignored.
    */
   void read_ucd (std::istream &in);
 
   /**
-   * Read grid data from a file
-   * containing data in the DB mesh
-   * format.
+   * Read grid data from a file containing data in the DB mesh format.
    */
   void read_dbmesh (std::istream &in);
 
   /**
-   * Read grid data from a file
-   * containing data in the XDA
-   * format.
+   * Read grid data from a file containing data in the XDA format.
    */
   void read_xda (std::istream &in);
 
   /**
-   * Read grid data from an msh
-   * file, either version 1 or
-   * version 2 of that file
-   * format. The GMSH formats are
-   * documented at
-   * http://www.geuz.org/gmsh/ .
+   * Read grid data from an msh file, either version 1 or version 2 of that
+   * file format. The GMSH formats are documented at http://www.geuz.org/gmsh/
+   * .
    *
-   * @note The input function of
-   * deal.II does not distinguish
-   * between newline and other
-   * whitespace. Therefore, deal.II
-   * will be able to read files in
-   * a slightly more general format
-   * than Gmsh.
+   * @note The input function of deal.II does not distinguish between newline
+   * and other whitespace. Therefore, deal.II will be able to read files in a
+   * slightly more general format than Gmsh.
    */
   void read_msh (std::istream &in);
 
   /**
-   * Read grid data from a NetCDF
-   * file. The only data format
-   * currently supported is the
-   * <tt>TAU grid format</tt>.
+   * Read grid data from a NetCDF file. The only data format currently
+   * supported is the <tt>TAU grid format</tt>.
    *
-   * This function requires the
-   * library to be linked with the
-   * NetCDF library.
+   * This function requires the library to be linked with the NetCDF library.
    */
   void read_netcdf (const std::string &filename);
 
   /**
-   * Read grid data from a file containing
-   * tecplot ASCII data. This also works in
-   * the absence of any tecplot
-   * installation.
+   * Read grid data from a file containing tecplot ASCII data. This also works
+   * in the absence of any tecplot installation.
    */
   void read_tecplot (std::istream &in);
 
   /**
-   * Returns the standard suffix
-   * for a file in this format.
+   * Returns the standard suffix for a file in this format.
    */
   static std::string default_suffix (const Format format);
 
   /**
-   * Return the enum Format for the
-   * format name.
+   * Return the enum Format for the format name.
    */
   static Format parse_format (const std::string &format_name);
 
   /**
-   * Return a list of implemented input
-   * formats. The different names are
-   * separated by vertical bar signs (<tt>`|'</tt>)
-   * as used by the ParameterHandler
-   * classes.
+   * Return a list of implemented input formats. The different names are
+   * separated by vertical bar signs (<tt>`|'</tt>) as used by the
+   * ParameterHandler classes.
    */
   static std::string get_format_names ();
 
@@ -553,55 +508,29 @@ public:
   DeclException0 (ExcGmshNoCellInformation);
 protected:
   /**
-   * Store address of the triangulation to
-   * be fed with the data read in.
+   * Store address of the triangulation to be fed with the data read in.
    */
   SmartPointer<Triangulation<dim,spacedim>,GridIn<dim,spacedim> > tria;
 
   /**
-   * This function can write the
-   * raw cell data objects created
-   * by the <tt>read_*</tt> functions in
-   * Gnuplot format to a
-   * stream. This is sometimes
-   * handy if one would like to see
-   * what actually was created, if
-   * it is known that the data is
-   * not correct in some way, but
-   * the Triangulation class
-   * refuses to generate a
-   * triangulation because of these
-   * errors. In particular, the
-   * output of this class writes
-   * out the cell numbers along
-   * with the direction of the
-   * faces of each cell. In
-   * particular the latter
-   * information is needed to
-   * verify whether the cell data
-   * objects follow the
-   * requirements of the ordering
-   * of cells and their faces,
-   * i.e. that all faces need to
-   * have unique directions and
-   * specified orientations with
-   * respect to neighboring cells
-   * (see the documentations to
-   * this class and the
-   * GridReordering class).
+   * This function can write the raw cell data objects created by the
+   * <tt>read_*</tt> functions in Gnuplot format to a stream. This is
+   * sometimes handy if one would like to see what actually was created, if it
+   * is known that the data is not correct in some way, but the Triangulation
+   * class refuses to generate a triangulation because of these errors. In
+   * particular, the output of this class writes out the cell numbers along
+   * with the direction of the faces of each cell. In particular the latter
+   * information is needed to verify whether the cell data objects follow the
+   * requirements of the ordering of cells and their faces, i.e. that all
+   * faces need to have unique directions and specified orientations with
+   * respect to neighboring cells (see the documentations to this class and
+   * the GridReordering class).
    *
-   * The output of this function
-   * consists of vectors for each
-   * line bounding the cells
-   * indicating the direction it
-   * has with respect to the
-   * orientation of this cell, and
-   * the cell number. The whole
-   * output is in a form such that
-   * it can be read in by Gnuplot
-   * and generate the full plot
-   * without further ado by the
-   * user.
+   * The output of this function consists of vectors for each line bounding
+   * the cells indicating the direction it has with respect to the orientation
+   * of this cell, and the cell number. The whole output is in a form such
+   * that it can be read in by Gnuplot and generate the full plot without
+   * further ado by the user.
    */
   static void debug_output_grid (const std::vector<CellData<dim> > &cells,
                                  const std::vector<Point<spacedim> > &vertices,
@@ -610,39 +539,27 @@ protected:
 private:
 
   /**
-   * Skip empty lines in the input
-   * stream, i.e. lines that
-   * contain either nothing or only
-   * whitespace.
+   * Skip empty lines in the input stream, i.e. lines that contain either
+   * nothing or only whitespace.
    */
   static void skip_empty_lines (std::istream &in);
 
   /**
-   * Skip lines of comment that
-   * start with the indicated
-   * character (e.g. <tt>#</tt>)
-   * following the point where the
-   * given input stream presently
-   * is. After the call to this
-   * function, the stream is at the
-   * start of the first line after
-   * the comment lines, or at the
-   * same position as before if
-   * there were no lines of
-   * comments.
+   * Skip lines of comment that start with the indicated character (e.g.
+   * <tt>#</tt>) following the point where the given input stream presently
+   * is. After the call to this function, the stream is at the start of the
+   * first line after the comment lines, or at the same position as before if
+   * there were no lines of comments.
    */
   static void skip_comment_lines (std::istream    &in,
                                   const char  comment_start);
 
   /**
-   * This function does the nasty work (due
-   * to very lax conventions and different
-   * versions of the tecplot format) of
-   * extracting the important parameters from
-   * a tecplot header, contained in the
-   * string @p header. The other variables
-   * are output variables, their value has no
-   * influence on the function execution..
+   * This function does the nasty work (due to very lax conventions and
+   * different versions of the tecplot format) of extracting the important
+   * parameters from a tecplot header, contained in the string @p header. The
+   * other variables are output variables, their value has no influence on the
+   * function execution..
    */
   static void parse_tecplot_header(std::string   &header,
                                    std::vector<unsigned int> &tecplot2deal,
@@ -654,8 +571,7 @@ private:
                                    bool          &blocked);
 
   /**
-   * Input format used by read() if
-   * no format is given.
+   * Input format used by read() if no format is given.
    */
   Format default_format;
 };
index e07e20cfacc404f17650c26a211e5adb12b6df6e..cc53ae816befa075dd6bc2a2fce8bf20567af089 100644 (file)
@@ -35,11 +35,10 @@ template <int dim, int spacedim> class Mapping;
 
 
 /**
- * Within this namespace, we define several structures that are used
- * to describe flags that can be given to grid output routines to
- * modify the default outfit of the grids written into a file. See the
- * different subclasses and the documentation of the GridOut
- * class for more details.
+ * Within this namespace, we define several structures that are used to
+ * describe flags that can be given to grid output routines to modify the
+ * default outfit of the grids written into a file. See the different
+ * subclasses and the documentation of the GridOut class for more details.
  *
  * @ingroup output
  */
@@ -73,8 +72,8 @@ namespace GridOutFlags
     bool write_measure;
 
     /**
-     * Write all faces, including interior faces. If <tt>false</tt>,
-     * only boundary faces are written.
+     * Write all faces, including interior faces. If <tt>false</tt>, only
+     * boundary faces are written.
      */
     bool write_all_faces;
 
@@ -106,33 +105,32 @@ namespace GridOutFlags
   struct Msh
   {
     /**
-     * When writing a mesh, write boundary faces explicitly if their
-     * boundary indicator is not the default boundary indicator, which
-     * is zero.  This is necessary if you later want to re-read the
-     * grid and want to get the same boundary indicators for the
-     * different parts of the boundary of the triangulation.
+     * When writing a mesh, write boundary faces explicitly if their boundary
+     * indicator is not the default boundary indicator, which is zero.  This
+     * is necessary if you later want to re-read the grid and want to get the
+     * same boundary indicators for the different parts of the boundary of the
+     * triangulation.
      *
-     * It is not necessary if you only want to write the triangulation
-     * to view or print it.
+     * It is not necessary if you only want to write the triangulation to view
+     * or print it.
      *
      * Default: @p false.
      */
     bool write_faces;
     /**
-      * When writing a mesh, write boundary lines explicitly if their
-      * boundary indicator is not the default boundary indicator,
-      * which is zero.  This is necessary if you later want to re-read
-      * the grid and want to get the same boundary indicators for the
-      * different parts of the boundary of the triangulation.
-      *
-      * It is not necessary if you only want to write the
-      * triangulation to view or print it.
-      *
-      * This is used only if <tt>dim==3</tt>, and ignored in all other
-      * cases.
-      *
-      * Default: @p false.
-      */
+     * When writing a mesh, write boundary lines explicitly if their boundary
+     * indicator is not the default boundary indicator, which is zero.  This
+     * is necessary if you later want to re-read the grid and want to get the
+     * same boundary indicators for the different parts of the boundary of the
+     * triangulation.
+     *
+     * It is not necessary if you only want to write the triangulation to view
+     * or print it.
+     *
+     * This is used only if <tt>dim==3</tt>, and ignored in all other cases.
+     *
+     * Default: @p false.
+     */
     bool write_lines;
 
     /**
@@ -160,44 +158,43 @@ namespace GridOutFlags
   struct Ucd
   {
     /**
-     * Write a comment at the beginning of the file stating the date
-     * of creation and some other data.  While this is supported by
-     * the UCD format (and the AVS program), some other programs get
-     * confused by this, so the default is to not write a
-     * preamble. However, a preamble can be written using this flag.
+     * Write a comment at the beginning of the file stating the date of
+     * creation and some other data.  While this is supported by the UCD
+     * format (and the AVS program), some other programs get confused by this,
+     * so the default is to not write a preamble. However, a preamble can be
+     * written using this flag.
      *
      * Default: <code>false</code>.
      */
     bool write_preamble;
 
     /**
-     * When writing a mesh, write boundary faces explicitly if their
-     * boundary indicator is not the default boundary indicator, which
-     * is zero.  This is necessary if you later want to re-read the
-     * grid and want to get the same boundary indicators for the
-     * different parts of the boundary of the triangulation.
+     * When writing a mesh, write boundary faces explicitly if their boundary
+     * indicator is not the default boundary indicator, which is zero.  This
+     * is necessary if you later want to re-read the grid and want to get the
+     * same boundary indicators for the different parts of the boundary of the
+     * triangulation.
      *
-     * It is not necessary if you only want to write the triangulation
-     * to view or print it.
+     * It is not necessary if you only want to write the triangulation to view
+     * or print it.
      *
      * Default: @p false.
      */
     bool write_faces;
 
     /**
-     * When writing a mesh, write boundary lines explicitly if their
-     * boundary indicator is not the default boundary indicator, which
-     * is zero.  This is necessary if you later want to re-read the
-     * grid and want to get the same boundary indicators for the
-     * different parts of the boundary of the triangulation.
+     * When writing a mesh, write boundary lines explicitly if their boundary
+     * indicator is not the default boundary indicator, which is zero.  This
+     * is necessary if you later want to re-read the grid and want to get the
+     * same boundary indicators for the different parts of the boundary of the
+     * triangulation.
      *
-     * It is not necessary if you only want to write the triangulation
-     * to view or print it.
+     * It is not necessary if you only want to write the triangulation to view
+     * or print it.
      *
-     * This directive is ignored if
-     * <tt>dim!=3</tt>.
+     * This directive is ignored if <tt>dim!=3</tt>.
      *
-     *  Default: @p false.
+     * Default: @p false.
      */
     bool write_lines;
 
@@ -228,12 +225,11 @@ namespace GridOutFlags
   struct Gnuplot
   {
     /**
-     * Write the number of each cell into the output file before
-     * starting with the lines it is composed of, as a comment. This
-     * might be useful if you want to find out details about the grid,
-     * for example the position of cells of which you know the
-     * number. It enlarges the size of the output significantly,
-     * however.
+     * Write the number of each cell into the output file before starting with
+     * the lines it is composed of, as a comment. This might be useful if you
+     * want to find out details about the grid, for example the position of
+     * cells of which you know the number. It enlarges the size of the output
+     * significantly, however.
      *
      * Default: @p false.
      */
@@ -241,15 +237,15 @@ namespace GridOutFlags
 
     /**
      * Based on the vertices of the face and #n_boundary_face_points
-     * additional points a tensor product mesh (tranformed to the real
-     * space) of (#n_boundary_face_points+2)<sup>dim-1</sup> points is
-     * plotted on each boundary face.
+     * additional points a tensor product mesh (tranformed to the real space)
+     * of (#n_boundary_face_points+2)<sup>dim-1</sup> points is plotted on
+     * each boundary face.
      */
     unsigned int n_boundary_face_points;
 
     /**
-     * Flag. If true also inner cells are plotted with curved
-     * boundaries. This is useful when for e.g.  MappingQEulerian with
+     * Flag. If true also inner cells are plotted with curved boundaries. This
+     * is useful when for e.g.  MappingQEulerian with
      * #n_boundary_face_points&gt;.
      */
     bool curved_inner_cells;
@@ -272,22 +268,22 @@ namespace GridOutFlags
   };
 
   /**
-   * Flags describing the details of output for encapsulated
-   * postscript.  In this structure, the flags common to all
-   * dimensions are listed. Flags which are specific to one space
-   * dimension only are listed in derived classes.
+   * Flags describing the details of output for encapsulated postscript.  In
+   * this structure, the flags common to all dimensions are listed. Flags
+   * which are specific to one space dimension only are listed in derived
+   * classes.
    *
-   * By default, the size of the picture is scaled such that the width
-   * equals 300 units.
+   * By default, the size of the picture is scaled such that the width equals
+   * 300 units.
    *
    * @ingroup output
    */
   struct EpsFlagsBase
   {
     /**
-     * Enum denoting the possibilities whether the scaling should be
-     * done such that the given @p size equals the width or the height
-     * of the resulting picture.
+     * Enum denoting the possibilities whether the scaling should be done such
+     * that the given @p size equals the width or the height of the resulting
+     * picture.
      */
     enum SizeType
     {
@@ -300,9 +296,9 @@ namespace GridOutFlags
     SizeType size_type;
 
     /**
-     * Width or height of the output as given in postscript units This
-     * usually is given by the strange unit 1/72 inch. Whether this is
-     * height or width is specified by the flag @p size_type.
+     * Width or height of the output as given in postscript units This usually
+     * is given by the strange unit 1/72 inch. Whether this is height or width
+     * is specified by the flag @p size_type.
      *
      * Default is 300.
      */
@@ -314,26 +310,25 @@ namespace GridOutFlags
     double line_width;
 
     /**
-     * Should lines with a set @p user_flag be drawn in a different
-     * color (red)?  See @ref GlossUserFlags for information about
-     * user flags.
-    */
+     * Should lines with a set @p user_flag be drawn in a different color
+     * (red)?  See @ref GlossUserFlags for information about user flags.
+     */
     bool color_lines_on_user_flag;
 
     /**
-     * This is the number of points on a boundary face, that are
-     * ploted additionally to the vertices of the face.
+     * This is the number of points on a boundary face, that are ploted
+     * additionally to the vertices of the face.
      *
-     * This is used if the mapping used is not the standard @p
-     * MappingQ1 mapping.
+     * This is used if the mapping used is not the standard @p MappingQ1
+     * mapping.
      */
     unsigned int n_boundary_face_points;
 
     /**
-     * Should lines be colored according to their refinement level?
-     * This overrides color_lines_on_user_flag for all levels except
-     * level 0.  Colors are: level 0: black, other levels: rainbow
-     * scale from blue to red.
+     * Should lines be colored according to their refinement level? This
+     * overrides color_lines_on_user_flag for all levels except level 0.
+     * Colors are: level 0: black, other levels: rainbow scale from blue to
+     * red.
      */
     bool color_lines_level;
 
@@ -352,24 +347,22 @@ namespace GridOutFlags
     static void declare_parameters (ParameterHandler &param);
 
     /**
-     * Parse parameters of
-     * ParameterHandler.
+     * Parse parameters of ParameterHandler.
      */
     void parse_parameters (ParameterHandler &param);
   };
 
 
   /**
-   * Flags describing the details of output for encapsulated
-   * postscript for all dimensions not explicitly specialized
-   * below. Some flags that are common to all dimensions are listed in
-   * the base class.
+   * Flags describing the details of output for encapsulated postscript for
+   * all dimensions not explicitly specialized below. Some flags that are
+   * common to all dimensions are listed in the base class.
    *
-   * This class does not actually exist, we only here declare the
-   * general template and declare explicit specializations below.
+   * This class does not actually exist, we only here declare the general
+   * template and declare explicit specializations below.
    *
    * @ingroup output
-  */
+   */
   template <int dim>
   struct Eps
   {};
@@ -411,28 +404,26 @@ namespace GridOutFlags
   struct Eps<2> : public EpsFlagsBase
   {
     /**
-     * If this flag is set, then we place the number of the cell into
-     * the middle of each cell. The default value is to not do this.
+     * If this flag is set, then we place the number of the cell into the
+     * middle of each cell. The default value is to not do this.
      *
-     * The format of the cell number written is <tt>level.index</tt>,
-     * or simply @p index, depending on the value of the following
-     * flag.
+     * The format of the cell number written is <tt>level.index</tt>, or
+     * simply @p index, depending on the value of the following flag.
      */
     bool write_cell_numbers;
     /**
-     * If the cell numbers shall be written, using the above flag,
-     * then the value of this flag determines whether the format shall
-     * be <tt>level.index</tt>, or simply @p index. If @p true, the
-     * first format is taken. Default is @p true.
+     * If the cell numbers shall be written, using the above flag, then the
+     * value of this flag determines whether the format shall be
+     * <tt>level.index</tt>, or simply @p index. If @p true, the first format
+     * is taken. Default is @p true.
      *
-     * The flag has obviously no effect if @p write_cell_numbers is @p
-     * false.
+     * The flag has obviously no effect if @p write_cell_numbers is @p false.
      */
     bool write_cell_number_level;
 
     /**
-     * Vertex numbers can be written onto the vertices. This is
-     * controlled by the following flag. Default is @p false.
+     * Vertex numbers can be written onto the vertices. This is controlled by
+     * the following flag. Default is @p false.
      */
     bool write_vertex_numbers;
 
@@ -475,10 +466,10 @@ namespace GridOutFlags
     double azimut_angle;
 
     /**
-     * Angle by which the viewers position projected onto the
-     * x-y-plane is rotated around the z-axis, in positive sense when
-     * viewed from above. The unit are degrees, and zero equals a
-     * position above or below the negative y-axis.
+     * Angle by which the viewers position projected onto the x-y-plane is
+     * rotated around the z-axis, in positive sense when viewed from above.
+     * The unit are degrees, and zero equals a position above or below the
+     * negative y-axis.
      *
      * Default is the Gnuplot-default of 30.
      */
@@ -535,14 +526,14 @@ namespace GridOutFlags
     /**
      * @deprecated Use the color_by enum instead.
      *
-     * Change color depending on level. Default is false, therefore,
-     * color is coded by material or boundary id.
+     * Change color depending on level. Default is false, therefore, color is
+     * coded by material or boundary id.
      */
     bool level_color DEAL_II_DEPRECATED;
 
     /**
-     * Code level to depth. Default is true. If false, color depends
-     * on material or boundary id.
+     * Code level to depth. Default is true. If false, color depends on
+     * material or boundary id.
      *
      * Depth of the object is 900-level, if this value is true.
      */
@@ -559,21 +550,21 @@ namespace GridOutFlags
     Point<2> scaling;
 
     /**
-     * Offset of the graph. Before scaling, the coordinates are
-     * shifted by this value. Default is zero in each direction.
+     * Offset of the graph. Before scaling, the coordinates are shifted by
+     * this value. Default is zero in each direction.
      */
     Point<2> offset;
 
     /**
-     * Style for filling cells. Default is solid fill (20). This value
-     * is forwarded unchanged into the corresponding field
-     * <tt>fill_style</tt> of the polyline object of XFig.
+     * Style for filling cells. Default is solid fill (20). This value is
+     * forwarded unchanged into the corresponding field <tt>fill_style</tt> of
+     * the polyline object of XFig.
      */
     int fill_style;
 
     /**
-     * Style for drawing border lines of polygons. Defaults to solid
-     * (0) and is forwarded to XFig.
+     * Style for drawing border lines of polygons. Defaults to solid (0) and
+     * is forwarded to XFig.
      */
     int line_style;
 
@@ -682,8 +673,8 @@ namespace GridOutFlags
     /**
      * Cell labeling (fixed order).
      *
-     * The following booleans determine which properties of the cell
-     * shall be displayed as text in the middle of each cell.
+     * The following booleans determine which properties of the cell shall be
+     * displayed as text in the middle of each cell.
      */
     bool label_level_number;    // default: true
     bool label_cell_index;      // default: true
@@ -745,8 +736,8 @@ namespace GridOutFlags
 
 
   /**
-   * Flags for grid output in Vtk format. These flags are the same as
-   * those declared in DataOutBase::VtkFlags.
+   * Flags for grid output in Vtk format. These flags are the same as those
+   * declared in DataOutBase::VtkFlags.
    *
    * @ingroup output
    */
@@ -755,8 +746,8 @@ namespace GridOutFlags
 
 
   /**
-   * Flags for grid output in Vtu format. These flags are the same as
-   * those declared in DataOutBase::VtuFlags.
+   * Flags for grid output in Vtu format. These flags are the same as those
+   * declared in DataOutBase::VtuFlags.
    *
    * @ingroup output
    */
@@ -784,30 +775,30 @@ namespace GridOutFlags
  *   ofstream output_file("some_filename" + GridOut::default_suffix(output_format));
  *   GridOut().write (tria, output_file, output_format);
  * @endcode
- * The function <tt>get_output_format_names()</tt> provides a list of possible names of
- * output formats in a string that is understandable by the ParameterHandler class.
+ * The function <tt>get_output_format_names()</tt> provides a list of possible
+ * names of output formats in a string that is understandable by the
+ * ParameterHandler class.
  *
- * Note that here, we have created an unnamed object of type GridOut and called
- * one of its <tt>write_*</tt> functions. This looks like as if the respective function
- * could really be made @p static. This was not done in order to allow for
- * parameters to be passed to the different output functions in a way compatible
- * with the scheme of allowing the right output format to be selected at run-time
- * through the generic @p write function.
+ * Note that here, we have created an unnamed object of type GridOut and
+ * called one of its <tt>write_*</tt> functions. This looks like as if the
+ * respective function could really be made @p static. This was not done in
+ * order to allow for parameters to be passed to the different output
+ * functions in a way compatible with the scheme of allowing the right output
+ * format to be selected at run-time through the generic @p write function.
  *
  * In order to explain this, consider each function had one or more additional
- * parameters giving the details of output, for example position of the spectator
- * for 3d meshed, line thicknesses, etc. While this would allow each output
- * function any flexibility it needs, it would not allow us to use the generic
- * function @p write which is given a parameter determining the output format,
- * since it is impractical to give it a list of parameters for each and every
- * output format supported which it may then pass on to the respective output
- * function.
+ * parameters giving the details of output, for example position of the
+ * spectator for 3d meshed, line thicknesses, etc. While this would allow each
+ * output function any flexibility it needs, it would not allow us to use the
+ * generic function @p write which is given a parameter determining the output
+ * format, since it is impractical to give it a list of parameters for each
+ * and every output format supported which it may then pass on to the
+ * respective output function.
  *
- * Rather, we have chosen to let each object of this class
- * GridOut have a set of parameters for each supported output
- * format. These are collected in structures GridOutFlags::Eps(),
- * GridOutFlags::Gnuplot(), etc declared in the GridOutFlags
- * namespace, and you can set your preferred flags like this:
+ * Rather, we have chosen to let each object of this class GridOut have a set
+ * of parameters for each supported output format. These are collected in
+ * structures GridOutFlags::Eps(), GridOutFlags::Gnuplot(), etc declared in
+ * the GridOutFlags namespace, and you can set your preferred flags like this:
  * @code
  *   GridOut grid_out;
  *   GridOutFlags::Ucd ucd_flags;
@@ -817,39 +808,36 @@ namespace GridOutFlags
  *   ...    // write some file with data_out
  * @endcode
  * The respective output function then use the so-set flags. By default, they
- * are set to reasonable values as described above and in the documentation
- * of the different flags structures. Resetting the flags can
- * be done by calling <tt>grid_out.set_flags (GridOutFlags::Ucd());</tt>, since the
- * default constructor of each of the flags structures sets the parameters
- * to their initial values.
+ * are set to reasonable values as described above and in the documentation of
+ * the different flags structures. Resetting the flags can be done by calling
+ * <tt>grid_out.set_flags (GridOutFlags::Ucd());</tt>, since the default
+ * constructor of each of the flags structures sets the parameters to their
+ * initial values.
  *
  * The advantage of this approach is that it is possible to change the flags
  * of one or more output formats according to your needs and later use the
- * generic @p write function; the actual output function then called will
- * use the flags as set before.
+ * generic @p write function; the actual output function then called will use
+ * the flags as set before.
  *
  * Note that some of the structures describing the flags of the different
- * output formats are empty since the respective format does not support
- * any flags. The structure and the @p set_flags function are provided
- * anyway. Note also that some of the structures may differ between the
- * dimensions supported by this class; they then have a template parameter,
- * as usual.
+ * output formats are empty since the respective format does not support any
+ * flags. The structure and the @p set_flags function are provided anyway.
+ * Note also that some of the structures may differ between the dimensions
+ * supported by this class; they then have a template parameter, as usual.
  *
  * @ingroup grid
  * @ingroup output
- * @author Wolfgang Bangerth, Guido Kanschat, Luca Heltai, Stefan Nauber, Christian Wülker
+ * @author Wolfgang Bangerth, Guido Kanschat, Luca Heltai, Stefan Nauber,
+ * Christian Wülker
  * @date 1999 - 2013
  */
 class GridOut
 {
 public:
   /**
-   * Declaration of a name for each
-   * of the different output
-   * formats. These are used by the
-   * generic output function
-   * write() to determine the
-   * actual output format.
+   * Declaration of a name for each of the different output formats. These are
+   * used by the generic output function write() to determine the actual
+   * output format.
    */
   enum OutputFormat
   {
@@ -883,82 +871,47 @@ public:
   GridOut ();
 
   /**
-   * Write triangulation in OpenDX
-   * format.
+   * Write triangulation in OpenDX format.
    *
-   * Cells or faces are written
-   * together with their level and
-   * their material id or boundary
-   * indicator, resp.
+   * Cells or faces are written together with their level and their material
+   * id or boundary indicator, resp.
    *
-   * Not implemented for the
-   * codimension one case.
+   * Not implemented for the codimension one case.
    */
   template <int dim, int spacedim>
   void write_dx (const Triangulation<dim,spacedim> &tria,
                  std::ostream             &out) const;
 
   /**
-   * Write the triangulation in the
-   * gnuplot format.
+   * Write the triangulation in the gnuplot format.
    *
-   * In GNUPLOT format, each cell
-   * is written as a sequence of
-   * its confining lines. Apart
-   * from the coordinates of the
-   * line's end points, the level
-   * and the material of the cell
-   * are appended to each line of
-   * output. Therefore, if you let
-   * GNUPLOT draw a 2d grid as a 3d
-   * plot, you will see more
-   * refined cells being raised
-   * against cells with less
-   * refinement.  Also, if you draw
-   * a cut through a 3d grid, you
-   * can extrude the refinement
-   * level in the direction
-   * orthogonal to the cut
-   * plane. The same can be done
-   * with the material id, which is
-   * plotted after the level.
+   * In GNUPLOT format, each cell is written as a sequence of its confining
+   * lines. Apart from the coordinates of the line's end points, the level and
+   * the material of the cell are appended to each line of output. Therefore,
+   * if you let GNUPLOT draw a 2d grid as a 3d plot, you will see more refined
+   * cells being raised against cells with less refinement.  Also, if you draw
+   * a cut through a 3d grid, you can extrude the refinement level in the
+   * direction orthogonal to the cut plane. The same can be done with the
+   * material id, which is plotted after the level.
    *
-   * A more useful application of
-   * this feature is the following:
-   * if you use the GNUPLOT
-   * command (for a 2d grid here)
+   * A more useful application of this feature is the following: if you use
+   * the GNUPLOT command (for a 2d grid here)
    * @verbatim
    * splot [:][:][2.5:3.5] "grid_file.gnuplot" *
    * @endverbatim
-   * then the
-   * whole x- and y-range will be
-   * plotted, i.e. the whole grid,
-   * but only those lines with a
-   * z-value between 2.5 and
-   * 3.5. Since the z-values were
-   * chosen to be the level to
-   * which a cell belongs, this
-   * results in a plot of those
-   * cells only that belong to
-   * level 3 in this example. This
-   * way, it is easy to produce
-   * plots of the different levels
-   * of grid.
+   * then the whole x- and y-range will be plotted, i.e. the whole grid, but
+   * only those lines with a z-value between 2.5 and 3.5. Since the z-values
+   * were chosen to be the level to which a cell belongs, this results in a
+   * plot of those cells only that belong to level 3 in this example. This
+   * way, it is easy to produce plots of the different levels of grid.
    *
-   * @p mapping is a pointer to a
-   * mapping used for the
-   * transformation of cells at the
-   * boundary. If zero, then use
-   * standard Q1 mapping.
+   * @p mapping is a pointer to a mapping used for the transformation of cells
+   * at the boundary. If zero, then use standard Q1 mapping.
    *
-   * Names and values of additional
-   * flags controlling the output
-   * can be found in the
-   * documentation of the
-   * GridOutFlags::Gnuplot() class.
+   * Names and values of additional flags controlling the output can be found
+   * in the documentation of the GridOutFlags::Gnuplot() class.
    *
-   * Not implemented for the
-   * codimension one case.
+   * Not implemented for the codimension one case.
    */
   template <int dim, int spacedim>
   void write_gnuplot (const Triangulation<dim,spacedim> &tria,
@@ -968,19 +921,18 @@ public:
   /**
    * Write the triangulation in the msh format.
    *
-   * Msh is the format used by Gmsh and it is described in the gmsh
-   * user's guide. Besides the usual output of the grid only, you can
-   * decide through additional flags (see below, and the documentation
-   * of the GridOutFlags::Msh() class) whether boundary faces with
-   * non-zero boundary indicator shall be written to the file
-   * explicitly. This is useful, if you want to re-read the grid later
-   * on, since <tt>deal.II</tt> sets the boundary indicator to zero by
-   * default; therefore, to obtain the same triangulation as before,
-   * you have to specify faces with differing boundary indicators
-   * explicitly, which is done by this flag.
+   * Msh is the format used by Gmsh and it is described in the gmsh user's
+   * guide. Besides the usual output of the grid only, you can decide through
+   * additional flags (see below, and the documentation of the
+   * GridOutFlags::Msh() class) whether boundary faces with non-zero boundary
+   * indicator shall be written to the file explicitly. This is useful, if you
+   * want to re-read the grid later on, since <tt>deal.II</tt> sets the
+   * boundary indicator to zero by default; therefore, to obtain the same
+   * triangulation as before, you have to specify faces with differing
+   * boundary indicators explicitly, which is done by this flag.
    *
-   * Names and values of further flags controlling the output can be
-   * found in the documentation of the GridOut::Msh() class.
+   * Names and values of further flags controlling the output can be found in
+   * the documentation of the GridOut::Msh() class.
    *
    * Works also in the codimension one case.
    */
@@ -991,20 +943,19 @@ public:
   /**
    * Write the triangulation in the ucd format.
    *
-   * UCD (unstructured cell data) is the format used by AVS and some
-   * other programs. It is described in the AVS developer's
-   * guide. Besides the usual output of the grid only, you can decide
-   * through additional flags (see below, and the documentation of the
-   * GridOutFlags::Ucd() class) whether boundary faces with non-zero
-   * boundary indicator shall be written to the file explicitly. This
-   * is useful, if you want to re-read the grid later on, since
-   * <tt>deal.II</tt> sets the boundary indicator to zero by default;
-   * therefore, to obtain the same triangulation as before, you have
-   * to specify faces with differing boundary indicators explicitly,
-   * which is done by this flag.
+   * UCD (unstructured cell data) is the format used by AVS and some other
+   * programs. It is described in the AVS developer's guide. Besides the usual
+   * output of the grid only, you can decide through additional flags (see
+   * below, and the documentation of the GridOutFlags::Ucd() class) whether
+   * boundary faces with non-zero boundary indicator shall be written to the
+   * file explicitly. This is useful, if you want to re-read the grid later
+   * on, since <tt>deal.II</tt> sets the boundary indicator to zero by
+   * default; therefore, to obtain the same triangulation as before, you have
+   * to specify faces with differing boundary indicators explicitly, which is
+   * done by this flag.
    *
-   * Names and values of further flags controlling the output can be
-   * found in the documentation of the GridOut::Ucd() class.
+   * Names and values of further flags controlling the output can be found in
+   * the documentation of the GridOut::Ucd() class.
    *
    * Works also for the codimension one case.
    */
@@ -1015,31 +966,29 @@ public:
   /**
    * Write the triangulation in the encapsulated postscript format.
    *
-   * In this format, each line of the triangulation is written
-   * separately. We scale the picture such that either x-values or
-   * y-values range between zero and a fixed size. The other axis is
-   * scaled by the same factor. Which axis is taken to compute the
-   * scale and the size of the box it shall fit into is determined by
-   * the output flags (see below, and the documentation of the
-   * GridOutFlags::Eps() class).
+   * In this format, each line of the triangulation is written separately. We
+   * scale the picture such that either x-values or y-values range between
+   * zero and a fixed size. The other axis is scaled by the same factor. Which
+   * axis is taken to compute the scale and the size of the box it shall fit
+   * into is determined by the output flags (see below, and the documentation
+   * of the GridOutFlags::Eps() class).
    *
-   * The bounding box is close to the triangulation on all four sides,
-   * without an extra frame. The line width is chosen to be 0.5 by
-   * default, but can be changed. The line width is to be compared
-   * with the extension of the picture, of which the default is 300.
+   * The bounding box is close to the triangulation on all four sides, without
+   * an extra frame. The line width is chosen to be 0.5 by default, but can be
+   * changed. The line width is to be compared with the extension of the
+   * picture, of which the default is 300.
    *
-   * The flag @p color_lines_on_user_flag allows to draw lines with
-   * the @p user_flag set to be drawn in red. The colors black and red
-   * are defined as @p b and @p r in the preamble of the output file
-   * and can be changed there according to need.
+   * The flag @p color_lines_on_user_flag allows to draw lines with the @p
+   * user_flag set to be drawn in red. The colors black and red are defined as
+   * @p b and @p r in the preamble of the output file and can be changed there
+   * according to need.
    *
-   * @p mapping is a pointer to a mapping used for the transformation
-   * of cells at the boundary. If zero, then use standard Q1 mapping.
+   * @p mapping is a pointer to a mapping used for the transformation of cells
+   * at the boundary. If zero, then use standard Q1 mapping.
    *
-   * Names and values of additional flags controlling the output can
-   * be found in the documentation of the GridOutFlags::Eps()
-   * class. Especially the viewpoint for three dimensional grids is of
-   * importance here.
+   * Names and values of additional flags controlling the output can be found
+   * in the documentation of the GridOutFlags::Eps() class. Especially the
+   * viewpoint for three dimensional grids is of importance here.
    *
    * Not implemented for the codimension one case.
    */
@@ -1051,18 +1000,18 @@ public:
   /**
    * Write two-dimensional XFig-file.
    *
-   * This function writes all grid cells as polygons and optionally
-   * boundary lines. Several parameters can be adjusted by the
-   * XFigFlags control object.
+   * This function writes all grid cells as polygons and optionally boundary
+   * lines. Several parameters can be adjusted by the XFigFlags control
+   * object.
    *
-   * If levels are coded to depth, the complete grid hierarchy is
-   * plotted with fine cells before their parents. This way, levels
-   * can be switched on and off in xfig by selecting levels.
+   * If levels are coded to depth, the complete grid hierarchy is plotted with
+   * fine cells before their parents. This way, levels can be switched on and
+   * off in xfig by selecting levels.
    *
    * Polygons are either at depth 900-level or at 900+@p material_id,
-   * depending on the flag @p level_depth. Accordingly, boundary edges
-   * are at depth 800-level or at 800+@p boundary_id. Therefore,
-   * boundary edges are alway in front of cells.
+   * depending on the flag @p level_depth. Accordingly, boundary edges are at
+   * depth 800-level or at 800+@p boundary_id. Therefore, boundary edges are
+   * alway in front of cells.
    *
    * Not implemented for the codimension one case.
    */
@@ -1074,24 +1023,20 @@ public:
   /**
    * Write the triangulation in the SVG format.
    *
-   * SVG (Scalable Vector Graphics) is
-   * an XML-based vector image format
-   * developed and maintained by the
-   * World Wide Web Consortium (W3C).
-   * This function conforms to the
-   * latest specification SVG 1.1,
-   * released on August 16, 2011.
+   * SVG (Scalable Vector Graphics) is an XML-based vector image format
+   * developed and maintained by the World Wide Web Consortium (W3C). This
+   * function conforms to the latest specification SVG 1.1, released on August
+   * 16, 2011.
    *
-   * The cells of the triangulation are written as polygons with
-   * additional lines at the boundary of the triangulation. A coloring
-   * of the cells is further possible in order to visualize a certain
-   * property of the cells such as their level or material id. A
-   * colorbar can be drawn to encode the chosen coloring.  Moreover, a
-   * cell label can be added, showing level index, etc.
+   * The cells of the triangulation are written as polygons with additional
+   * lines at the boundary of the triangulation. A coloring of the cells is
+   * further possible in order to visualize a certain property of the cells
+   * such as their level or material id. A colorbar can be drawn to encode the
+   * chosen coloring.  Moreover, a cell label can be added, showing level
+   * index, etc.
    *
-   * @note This function is currently only implemented for
-   * two-dimensional grids in two
-   * space dimensions.
+   * @note This function is currently only implemented for two-dimensional
+   * grids in two space dimensions.
    */
   void write_svg (const Triangulation<2,2> &tria,
                   std::ostream             &out) const;
@@ -1107,17 +1052,16 @@ public:
 
 
   /**
-   * Write triangulation in MathGL script format. To interpret this
-   * file a version of MathGL>=2.0.0 is required.
+   * Write triangulation in MathGL script format. To interpret this file a
+   * version of MathGL>=2.0.0 is required.
    *
    * To get a handle on the resultant MathGL script within a graphical
-   * environment an interpreter is needed. A suggestion to start with
-   * is <code>mglview</code>, which is bundled with MathGL.
-   * <code>mglview</code> can interpret and display small-to-medium
-   * MathGL scripts in a graphical window and enables conversion to
-   * other formats such as EPS, PNG, JPG, SVG, as well as view/display
-   * animations. Some minor editing, such as modifying the lighting or
-   * alpha channels, can also be done.
+   * environment an interpreter is needed. A suggestion to start with is
+   * <code>mglview</code>, which is bundled with MathGL. <code>mglview</code>
+   * can interpret and display small-to-medium MathGL scripts in a graphical
+   * window and enables conversion to other formats such as EPS, PNG, JPG,
+   * SVG, as well as view/display animations. Some minor editing, such as
+   * modifying the lighting or alpha channels, can also be done.
    *
    * @note Not implemented for the codimension one case.
    */
@@ -1140,8 +1084,8 @@ public:
                   std::ostream                      &out) const;
 
   /**
-   * Write grid to @p out according to the given data format. This
-   * function simply calls the appropriate <tt>write_*</tt> function.
+   * Write grid to @p out according to the given data format. This function
+   * simply calls the appropriate <tt>write_*</tt> function.
    */
   template <int dim, int spacedim>
   void write (const Triangulation<dim,spacedim> &tria,
@@ -1178,14 +1122,12 @@ public:
   void set_flags (const GridOutFlags::Gnuplot &flags);
 
   /**
-   * Set flags for EPS output of a
-   * one-dimensional triangulation
+   * Set flags for EPS output of a one-dimensional triangulation
    */
   void set_flags (const GridOutFlags::Eps<1> &flags);
 
   /**
-   * Set flags for EPS output of a
-   * two-dimensional triangulation
+   * Set flags for EPS output of a two-dimensional triangulation
    */
   void set_flags (const GridOutFlags::Eps<2> &flags);
 
@@ -1220,8 +1162,7 @@ public:
   void set_flags (const GridOutFlags::Vtu &flags);
 
   /**
-   * Provide a function that can tell us which
-   * suffix a given output format
+   * Provide a function that can tell us which suffix a given output format
    * usually has. For example, it defines the following mappings:
    * <ul>
    * <li> @p OpenDX: <tt>.dx</tt>
@@ -1231,9 +1172,8 @@ public:
    * </ul>
    * Similar mappings are provided for all implemented formats.
    *
-   * Since this function does not need data from this object, it is
-   * static and can thus be called without creating an object of this
-   * class.
+   * Since this function does not need data from this object, it is static and
+   * can thus be called without creating an object of this class.
    */
   static std::string default_suffix (const OutputFormat output_format);
 
@@ -1244,25 +1184,23 @@ public:
   std::string default_suffix () const;
 
   /**
-   * Return the @p OutputFormat value corresponding to the given
-   * string. If the string does not match any known format, an
-   * exception is thrown.
+   * Return the @p OutputFormat value corresponding to the given string. If
+   * the string does not match any known format, an exception is thrown.
    *
-   * Since this function does not need data from this object, it is
-   * static and can thus be called without creating an object of this
-   * class. Its main purpose is to allow a program to use any
-   * implemented output format without the need to extend the
-   * program's parser each time a new format is implemented.
+   * Since this function does not need data from this object, it is static and
+   * can thus be called without creating an object of this class. Its main
+   * purpose is to allow a program to use any implemented output format
+   * without the need to extend the program's parser each time a new format is
+   * implemented.
    *
-   * To get a list of presently available format names, e.g. to give
-   * it to the ParameterHandler class, use the function
-   * get_output_format_names().
+   * To get a list of presently available format names, e.g. to give it to the
+   * ParameterHandler class, use the function get_output_format_names().
    */
   static OutputFormat parse_output_format (const std::string &format_name);
 
   /**
-   * Return a list of implemented output formats. The different names
-   * are separated by vertical bar signs (<tt>`|'</tt>) as used by the
+   * Return a list of implemented output formats. The different names are
+   * separated by vertical bar signs (<tt>`|'</tt>) as used by the
    * ParameterHandler classes.
    */
   static std::string get_output_format_names ();
@@ -1278,8 +1216,8 @@ public:
   void parse_parameters (ParameterHandler &param);
 
   /**
-   * Determine an estimate for the memory consumption (in bytes) of
-   * this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -1300,44 +1238,38 @@ private:
   GridOutFlags::DX dx_flags;
 
   /**
-   * Flags for GMSH output. Can be changed by using the set_flags(const GridOutFlags::Msh&)
-   * function.
+   * Flags for GMSH output. Can be changed by using the set_flags(const
+   * GridOutFlags::Msh&) function.
    */
   GridOutFlags::Msh     msh_flags;
 
   /**
-   * Flags for UCD output. Can be changed by using the set_flags(const GridOutFlags::Ucd&)
-   * function.
+   * Flags for UCD output. Can be changed by using the set_flags(const
+   * GridOutFlags::Ucd&) function.
    */
   GridOutFlags::Ucd     ucd_flags;
 
   /**
-   * Flags to be used upon output of GNUPLOT data. Can be changed by
-   * using the set_flags(const GridOutFlags::Gnuplot&) function.
+   * Flags to be used upon output of GNUPLOT data. Can be changed by using the
+   * set_flags(const GridOutFlags::Gnuplot&) function.
    */
   GridOutFlags::Gnuplot gnuplot_flags;
 
   /**
-   * Flags to be used upon output of EPS
-   * data in one space dimension. Can be
-   * changed by using the set_flags(const GridOutFlags::Eps<1>&)
-   * function.
+   * Flags to be used upon output of EPS data in one space dimension. Can be
+   * changed by using the set_flags(const GridOutFlags::Eps<1>&) function.
    */
   GridOutFlags::Eps<1>  eps_flags_1;
 
   /**
-   * Flags to be used upon output of EPS
-   * data in two space dimensions. Can be
-   * changed by using the @p set_flags
-   * function.
+   * Flags to be used upon output of EPS data in two space dimensions. Can be
+   * changed by using the @p set_flags function.
    */
   GridOutFlags::Eps<2>  eps_flags_2;
 
   /**
-   * Flags to be used upon output of EPS
-   * data in three space dimensions. Can be
-   * changed by using the @p set_flags
-   * function.
+   * Flags to be used upon output of EPS data in three space dimensions. Can
+   * be changed by using the @p set_flags function.
    */
   GridOutFlags::Eps<3>  eps_flags_3;
 
@@ -1367,21 +1299,19 @@ private:
   GridOutFlags::Vtu vtu_flags;
 
   /**
-   * Write the grid information about faces to @p out. Only those
-   * faces are printed which are on the boundary and which have a
-   * boundary indicator not equal to zero, since the latter is the
-   * default for boundary faces.
+   * Write the grid information about faces to @p out. Only those faces are
+   * printed which are on the boundary and which have a boundary indicator not
+   * equal to zero, since the latter is the default for boundary faces.
    *
-   * Since cells and faces are continuously numbered, the @p
-   * starting_index for the numbering of the faces is passed also.
+   * Since cells and faces are continuously numbered, the @p starting_index
+   * for the numbering of the faces is passed also.
    *
    * This function unfortunately can not be included in the regular @p
    * write_msh function, since it needs special treatment for the case
-   * <tt>dim==1</tt>, in which case the face iterators are
-   * <tt>void*</tt>'s and lack the member functions which are
-   * called. We would not actually call these functions, but the
-   * compiler would complain anyway when compiling the function for
-   * <tt>dim==1</tt>. Bad luck.
+   * <tt>dim==1</tt>, in which case the face iterators are <tt>void*</tt>'s
+   * and lack the member functions which are called. We would not actually
+   * call these functions, but the compiler would complain anyway when
+   * compiling the function for <tt>dim==1</tt>. Bad luck.
    */
   template <int dim, int spacedim>
   void write_msh_faces (const Triangulation<dim,spacedim> &tria,
@@ -1389,16 +1319,13 @@ private:
                         std::ostream             &out) const;
 
   /**
-   * Declaration of the specialization
-   * of above function for 1d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 1d. Does nothing.
    */
   void write_msh_faces (const Triangulation<1,1> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
   /**
-   * Declaration of the specialization
-   * of above function for 1d, 2sd. Does
+   * Declaration of the specialization of above function for 1d, 2sd. Does
    * nothing.
    */
   void write_msh_faces (const Triangulation<1,2> &tria,
@@ -1411,21 +1338,19 @@ private:
 
 
   /**
-   * Write the grid information about lines to @p out. Only those
-   * lines are printed which are on the boundary and which have a
-   * boundary indicator not equal to zero, since the latter is the
-   * default for boundary faces.
+   * Write the grid information about lines to @p out. Only those lines are
+   * printed which are on the boundary and which have a boundary indicator not
+   * equal to zero, since the latter is the default for boundary faces.
    *
-   * Since cells and faces are continuously numbered, the @p
-   * starting_index for the numbering of the lines is passed also.
+   * Since cells and faces are continuously numbered, the @p starting_index
+   * for the numbering of the lines is passed also.
    *
    * This function unfortunately can not be included in the regular @p
    * write_msh function, since it needs special treatment for the case
-   * <tt>dim==1</tt> and <tt>dim==2</tt>, in which case the edge
-   * iterators are <tt>void*</tt>'s and lack the member functions
-   * which are called. We would not actually call these functions, but
-   * the compiler would complain anyway when compiling the function
-   * for <tt>dim==1/2</tt>. Bad luck.
+   * <tt>dim==1</tt> and <tt>dim==2</tt>, in which case the edge iterators are
+   * <tt>void*</tt>'s and lack the member functions which are called. We would
+   * not actually call these functions, but the compiler would complain anyway
+   * when compiling the function for <tt>dim==1/2</tt>. Bad luck.
    */
   template <int dim, int spacedim>
   void write_msh_lines (const Triangulation<dim,spacedim> &tria,
@@ -1433,16 +1358,15 @@ private:
                         std::ostream             &out) const;
 
   /**
-   * Declaration of the specialization of above function for 1d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 1d. Does nothing.
    */
   void write_msh_lines (const Triangulation<1,1> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
 
   /**
-   * Declaration of the specialization of above function for 1d,
-   * 2sd. Does nothing.
+   * Declaration of the specialization of above function for 1d, 2sd. Does
+   * nothing.
    */
   void write_msh_lines (const Triangulation<1,2> &tria,
                         const unsigned int      starting_index,
@@ -1451,36 +1375,33 @@ private:
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
   /**
-   * Declaration of the specialization of above function for 2d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 2d. Does nothing.
    */
   void write_msh_lines (const Triangulation<2,2> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
   /**
-   * Declaration of the specialization of above function for 2d,
-   * 3sd. Does nothing.
+   * Declaration of the specialization of above function for 2d, 3sd. Does
+   * nothing.
    */
   void write_msh_lines (const Triangulation<2,3> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
 
   /**
-   * Write the grid information about faces to @p out. Only those
-   * faces are printed which are on the boundary and which have a
-   * boundary indicator not equal to zero, since the latter is the
-   * default for boundary faces.
+   * Write the grid information about faces to @p out. Only those faces are
+   * printed which are on the boundary and which have a boundary indicator not
+   * equal to zero, since the latter is the default for boundary faces.
    *
-   * Since cells and faces are continuously numbered, the @p
-   * starting_index for the numbering of the faces is passed also.
+   * Since cells and faces are continuously numbered, the @p starting_index
+   * for the numbering of the faces is passed also.
    *
    * This function unfortunately can not be included in the regular @p
    * write_ucd function, since it needs special treatment for the case
-   * <tt>dim==1</tt>, in which case the face iterators are
-   * <tt>void*</tt>'s and lack the member functions which are
-   * called. We would not actually call these functions, but the
-   * compiler would complain anyway when compiling the function for
-   * <tt>dim==1</tt>. Bad luck.
+   * <tt>dim==1</tt>, in which case the face iterators are <tt>void*</tt>'s
+   * and lack the member functions which are called. We would not actually
+   * call these functions, but the compiler would complain anyway when
+   * compiling the function for <tt>dim==1</tt>. Bad luck.
    */
 
 
@@ -1490,16 +1411,15 @@ private:
                         std::ostream             &out) const;
 
   /**
-   * Declaration of the specialization of above function for 1d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 1d. Does nothing.
    */
   void write_ucd_faces (const Triangulation<1,1> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
 
   /**
-   * Declaration of the specialization of above function for 1d,
-   * 2sd. Does nothing.
+   * Declaration of the specialization of above function for 1d, 2sd. Does
+   * nothing.
    */
   void write_ucd_faces (const Triangulation<1,2> &tria,
                         const unsigned int      starting_index,
@@ -1510,21 +1430,19 @@ private:
 
 
   /**
-   * Write the grid information about lines to @p out. Only those
-   * lines are printed which are on the boundary and which have a
-   * boundary indicator not equal to zero, since the latter is the
-   * default for boundary lines.
+   * Write the grid information about lines to @p out. Only those lines are
+   * printed which are on the boundary and which have a boundary indicator not
+   * equal to zero, since the latter is the default for boundary lines.
    *
    * Since cells, faces and lines are continuously numbered, the @p
    * starting_index for the numbering of the faces is passed also.
    *
    * This function unfortunately can not be included in the regular @p
    * write_ucd function, since it needs special treatment for the case
-   * <tt>dim==1/2</tt>, in which case the edge iterators are
-   * <tt>void*</tt>'s and lack the member functions which are
-   * called. We would not actually call these functions, but the
-   * compiler would complain anyway when compiling the function for
-   * <tt>dim==1/2</tt>. Bad luck.
+   * <tt>dim==1/2</tt>, in which case the edge iterators are <tt>void*</tt>'s
+   * and lack the member functions which are called. We would not actually
+   * call these functions, but the compiler would complain anyway when
+   * compiling the function for <tt>dim==1/2</tt>. Bad luck.
    */
 
 
@@ -1534,15 +1452,14 @@ private:
                         std::ostream             &out) const;
 
   /**
-   * Declaration of the specialization of above function for 1d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 1d. Does nothing.
    */
   void write_ucd_lines (const Triangulation<1,1> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
   /**
-   * Declaration of the specialization of above function for 1d,
-   * 2sd. Does nothing.
+   * Declaration of the specialization of above function for 1d, 2sd. Does
+   * nothing.
    */
   void write_ucd_lines (const Triangulation<1,2> &tria,
                         const unsigned int      starting_index,
@@ -1553,15 +1470,14 @@ private:
 
 
   /**
-   * Declaration of the specialization of above function for 2d. Does
-   * nothing.
+   * Declaration of the specialization of above function for 2d. Does nothing.
    */
   void write_ucd_lines (const Triangulation<2,2> &tria,
                         const unsigned int      starting_index,
                         std::ostream           &out) const;
   /**
-   * Declaration of the specialization of above function for 2d,
-   * 3sd. Does nothing.
+   * Declaration of the specialization of above function for 2d, 3sd. Does
+   * nothing.
    */
   void write_ucd_lines (const Triangulation<2,3> &tria,
                         const unsigned int      starting_index,
@@ -1569,12 +1485,12 @@ private:
 
 
   /**
-   * This function projects a three-dimensional point (Point<3> point)
-   * onto a two-dimensional image plane, specified by the position of
-   * the camera viewing system (Point<3> camera_position), camera
-   * direction (Point<3> camera_position), camera horizontal (Point<3>
-   * camera_horizontal, necessary for the correct alignment of the
-   * later images), and the focus of the camera (float camera_focus).
+   * This function projects a three-dimensional point (Point<3> point) onto a
+   * two-dimensional image plane, specified by the position of the camera
+   * viewing system (Point<3> camera_position), camera direction (Point<3>
+   * camera_position), camera horizontal (Point<3> camera_horizontal,
+   * necessary for the correct alignment of the later images), and the focus
+   * of the camera (float camera_focus).
    *
    * For SVG output of grids.
    */
@@ -1585,73 +1501,69 @@ private:
                                     float camera_focus);
 
   /**
-   * Return the number of faces in the triangulation which have a
-   * boundary indicator not equal to zero. Only these faces are
-   * explicitly printed in the <tt>write_*</tt> functions; all faces
-   * with indicator numbers::internal_face_boundary_id are interior
-   * ones and an indicator with value zero for faces at the boundary
-
-   * are considered default.
+   * Return the number of faces in the triangulation which have a boundary
+   * indicator not equal to zero. Only these faces are explicitly printed in
+   * the <tt>write_*</tt> functions; all faces with indicator
+   * numbers::internal_face_boundary_id are interior ones and an indicator
+   * with value zero for faces at the boundary  are considered default.
    *
    * This function always returns an empty list in one dimension.
    *
-   * The reason for this function is the same as for
-   * write_ucd_faces(). See there for more information.
+   * The reason for this function is the same as for write_ucd_faces(). See
+   * there for more information.
    */
   template <int dim, int spacedim>
   unsigned int n_boundary_faces (const Triangulation<dim,spacedim> &tria) const;
 
   /**
-   * Declaration of the specialization of above function for
-   * 1d. Simply returns zero.
+   * Declaration of the specialization of above function for 1d. Simply
+   * returns zero.
    */
   unsigned int n_boundary_faces (const Triangulation<1,1> &tria) const;
 
   /**
-   * Declaration of the specialization of above function for 1d,
-   * 2sd. Simply returns zero.
+   * Declaration of the specialization of above function for 1d, 2sd. Simply
+   * returns zero.
    */
   unsigned int n_boundary_faces (const Triangulation<1,2> &tria) const;
   unsigned int n_boundary_faces (const Triangulation<1,3> &tria) const;
 
   /**
-   * Return the number of lines in the triangulation which have a
-   * boundary indicator not equal to zero. Only these lines are
-   * explicitly printed in the <tt>write_*</tt> functions; all lines
-   * with indicator numbers::internal_face_boundary_id are interior
-   * ones and an indicator with value zero for faces at the boundary
-   * are considered default.
+   * Return the number of lines in the triangulation which have a boundary
+   * indicator not equal to zero. Only these lines are explicitly printed in
+   * the <tt>write_*</tt> functions; all lines with indicator
+   * numbers::internal_face_boundary_id are interior ones and an indicator
+   * with value zero for faces at the boundary are considered default.
    *
-   * This function always returns an empty list in one and two
-   * dimensions.
+   * This function always returns an empty list in one and two dimensions.
    *
-   * The reason for this function is the same as for
-   * write_ucd_faces(). See there for more information.
+   * The reason for this function is the same as for write_ucd_faces(). See
+   * there for more information.
    */
   template <int dim, int spacedim>
   unsigned int n_boundary_lines (const Triangulation<dim,spacedim> &tria) const;
 
   /**
-   * Declaration of the specialization of above function for
-   * 1d. Simply returns zero.
+   * Declaration of the specialization of above function for 1d. Simply
+   * returns zero.
    */
   unsigned int n_boundary_lines (const Triangulation<1,1> &tria) const;
 
   /**
-   * Declaration of the specialization of above function for 1d,
-   * 2sd. Simply returns zero.
+   * Declaration of the specialization of above function for 1d, 2sd. Simply
+   * returns zero.
    */
   unsigned int n_boundary_lines (const Triangulation<1,2> &tria) const;
   unsigned int n_boundary_lines (const Triangulation<1,3> &tria) const;
 
   /**
-   * Declaration of the specialization of above function for
-   * 2d. Simply returns zero.
+   * Declaration of the specialization of above function for 2d. Simply
+   * returns zero.
    */
   unsigned int n_boundary_lines (const Triangulation<2,2> &tria) const;
   /**
-   * Declaration of the specialization of above function for 2d,
-   * 3sd. Simply returns zero.
+   * Declaration of the specialization of above function for 2d, 3sd. Simply
+   * returns zero.
    */
   unsigned int n_boundary_lines (const Triangulation<2,3> &tria) const;
 };
index 45a13e8b08ddf7d9a1bae1582ba5f46288506c51..d4d98d39254ccb232f0543a497cae30e246c97a0 100644 (file)
@@ -36,12 +36,11 @@ template <class T> class Vector;
  * Triangulation objects.
  *
  * The functions in this namespace form two categories. There are the
- * auxiliary functions refine() and coarsen(). More important for
- * users are the other functions, which implement refinement
- * strategies, as being found in the literature on adaptive finite
- * element methods. For mathematical discussion of these methods,
- * consider works by D&ouml;rfler, Morin, Nochetto, Rannacher,
- * Stevenson and many more.
+ * auxiliary functions refine() and coarsen(). More important for users are
+ * the other functions, which implement refinement strategies, as being found
+ * in the literature on adaptive finite element methods. For mathematical
+ * discussion of these methods, consider works by D&ouml;rfler, Morin,
+ * Nochetto, Rannacher, Stevenson and many more.
  *
  * @ingroup grid
  * @author Wolfgang Bangerth, Thomas Richter, Guido Kanschat 1998, 2000, 2009
@@ -49,69 +48,66 @@ template <class T> class Vector;
 namespace GridRefinement
 {
   /**
-   * This function provides a refinement strategy with predictable
-   * growth of the mesh.
+   * This function provides a refinement strategy with predictable growth of
+   * the mesh.
    *
    * The function takes a vector of refinement @p criteria and two values
-   * between zero and one denoting the fractions of cells to be refined
-   * and coarsened. It flags cells for further processing by
+   * between zero and one denoting the fractions of cells to be refined and
+   * coarsened. It flags cells for further processing by
    * Triangulation::execute_coarsening_and_refinement() according to the
    * following greedy algorithm:
    *
    * <ol>
    *
-   *  <li> Sort the cells according to descending values of @p criteria.
+   * <li> Sort the cells according to descending values of @p criteria.
    *
-   *  <li> Set the refinement threshold to be the criterion belonging to
-   *  the cell at position @p top_fraction_of_cells times
-   *  Triangulation::n_active_cells().
+   * <li> Set the refinement threshold to be the criterion belonging to the
+   * cell at position @p top_fraction_of_cells times
+   * Triangulation::n_active_cells().
    *
    * <li> Set the coarsening threshold accordingly using the cell @p
-   *  bottom_fraction_of_cells times Triangulation::n_active_cells()
-   *  from the end of the sorted list.
+   * bottom_fraction_of_cells times Triangulation::n_active_cells() from the
+   * end of the sorted list.
    *
-   *  <li> Use these two thresholds in calls to refine() and coarsen(),
-   *  respectively.
+   * <li> Use these two thresholds in calls to refine() and coarsen(),
+   * respectively.
    *
    * </ol>
    *
-   * As an example, with no coarsening, setting @p top_fraction_of_cells
-   * to 1/3 will result in approximately doubling the number of cells in
-   * two dimensions. The same effect in three dimensions is achieved by
-   * refining 1/7th of the cells. These values are good initial guesses,
-   * but should be adjusted depending on the singularity of approximated
-   * function.
-   *
-   * The sorting of criteria is not done actually, since we only need
-   * the threshold values in order to call refine() and coarsen(). The
-   * order of cells with higher and of those with lower criteria is
-   * irrelevant. Getting this value is accomplished by the @p
-   * nth_element function of the <tt>C++</tt> standard library, which
-   * takes only linear time in the number of elements, rather than <tt>N
-   * log N</tt> for sorting all values.
-   *
-   * @warning This function only sets the coarsening and refinement
-   * flags. The mesh is not changed until you call
+   * As an example, with no coarsening, setting @p top_fraction_of_cells to
+   * 1/3 will result in approximately doubling the number of cells in two
+   * dimensions. The same effect in three dimensions is achieved by refining
+   * 1/7th of the cells. These values are good initial guesses, but should be
+   * adjusted depending on the singularity of approximated function.
+   *
+   * The sorting of criteria is not done actually, since we only need the
+   * threshold values in order to call refine() and coarsen(). The order of
+   * cells with higher and of those with lower criteria is irrelevant. Getting
+   * this value is accomplished by the @p nth_element function of the
+   * <tt>C++</tt> standard library, which takes only linear time in the number
+   * of elements, rather than <tt>N log N</tt> for sorting all values.
+   *
+   * @warning This function only sets the coarsening and refinement flags. The
+   * mesh is not changed until you call
    * Triangulation::execute_coarsening_and_refinement().
    *
-   * @arg @p criteria: the refinement criterion computed on each mesh
-   * cell. Entries may not be negative.
+   * @arg @p criteria: the refinement criterion computed on each mesh cell.
+   * Entries may not be negative.
    *
-   * @arg @p top_fraction_of_cells is the fraction of cells to be
-   * refined. If this number is zero, no cells will be refined. If it
-   * equals one, the result will be flagging for global refinement.
+   * @arg @p top_fraction_of_cells is the fraction of cells to be refined. If
+   * this number is zero, no cells will be refined. If it equals one, the
+   * result will be flagging for global refinement.
    *
    * @arg @p bottom_fraction_of_cells is the fraction of cells to be
    * coarsened. If this number is zero, no cells will be coarsened.
    *
-   * @arg @p max_n_cells can be used to specify a maximal number of
-   * cells. If this number is going to be exceeded upon refinement, then
-   * refinement and coarsening fractions are going to be adjusted in an
-   * attempt to reach the maximum number of cells. Be aware though that
-   * through proliferation of refinement due to
-   * Triangulation::MeshSmoothing, this number is only an indicator. The
-   * default value of this argument is to impose no limit on the number
-   * of cells.
+   * @arg @p max_n_cells can be used to specify a maximal number of cells. If
+   * this number is going to be exceeded upon refinement, then refinement and
+   * coarsening fractions are going to be adjusted in an attempt to reach the
+   * maximum number of cells. Be aware though that through proliferation of
+   * refinement due to Triangulation::MeshSmoothing, this number is only an
+   * indicator. The default value of this argument is to impose no limit on
+   * the number of cells.
    */
   template <int dim, class Vector, int spacedim>
   void
@@ -123,17 +119,17 @@ namespace GridRefinement
     const unsigned int          max_n_cells = std::numeric_limits<unsigned int>::max());
 
   /**
-   * This function provides a refinement strategy controlling the
-   * reduction of the error estimate.
+   * This function provides a refinement strategy controlling the reduction of
+   * the error estimate.
    *
    * Also known as the <b>bulk criterion</b>, this function computes the
-   * thresholds for refinement and coarsening such that the @p criteria
-   * of cells getting flagged for refinement make up for a certain
-   * fraction of the total error. We explain its operation for
-   * refinement, coarsening works analogously.
+   * thresholds for refinement and coarsening such that the @p criteria of
+   * cells getting flagged for refinement make up for a certain fraction of
+   * the total error. We explain its operation for refinement, coarsening
+   * works analogously.
    *
-   * Let <i>c<sub>K</sub></i> be the criterion of cell <i>K</i>. Then
-   * the total error estimate is computed by the formula
+   * Let <i>c<sub>K</sub></i> be the criterion of cell <i>K</i>. Then the
+   * total error estimate is computed by the formula
    * @f[
    * E = \sum_{K\in \cal T} c_K.
    * @f]
@@ -148,32 +144,31 @@ namespace GridRefinement
    * refine_and_coarsen_fixed_number().
    *
    * @note The often used formula with squares on the left and right is
-   * recovered by actually storing the square of <i>c<sub>K</sub></i> in
-   * the vector @p criteria.
+   * recovered by actually storing the square of <i>c<sub>K</sub></i> in the
+   * vector @p criteria.
    *
-   * From the point of view of implementation, this time we really need
-   * to sort the array of criteria.  Just like the other strategy
-   * described above, this function only computes the threshold values
-   * and then passes over to refine() and coarsen().
+   * From the point of view of implementation, this time we really need to
+   * sort the array of criteria.  Just like the other strategy described
+   * above, this function only computes the threshold values and then passes
+   * over to refine() and coarsen().
    *
-   * @arg @p criteria: the refinement criterion computed on each mesh
-   * cell. Entries may not be negative.
+   * @arg @p criteria: the refinement criterion computed on each mesh cell.
+   * Entries may not be negative.
    *
-   * @arg @p top_fraction is the fraction of the total estimate which
-   * should be refined. If this number is zero, no cells will be refined. If it
+   * @arg @p top_fraction is the fraction of the total estimate which should
+   * be refined. If this number is zero, no cells will be refined. If it
    * equals one, the result will be flagging for global refinement.
    *
-   * @arg @p bottom_fraction is the fraction of the estimate
-   * coarsened. If this number is zero, no cells will be coarsened.
+   * @arg @p bottom_fraction is the fraction of the estimate coarsened. If
+   * this number is zero, no cells will be coarsened.
    *
-   * @arg @p max_n_cells can be used to specify a maximal number of
-   * cells. If this number is going to be exceeded upon refinement, then
-   * refinement and coarsening fractions are going to be adjusted in an
-   * attempt to reach the maximum number of cells. Be aware though that
-   * through proliferation of refinement due to
-   * Triangulation::MeshSmoothing, this number is only an indicator. The
-   * default value of this argument is to impose no limit on the number
-   * of cells.
+   * @arg @p max_n_cells can be used to specify a maximal number of cells. If
+   * this number is going to be exceeded upon refinement, then refinement and
+   * coarsening fractions are going to be adjusted in an attempt to reach the
+   * maximum number of cells. Be aware though that through proliferation of
+   * refinement due to Triangulation::MeshSmoothing, this number is only an
+   * indicator. The default value of this argument is to impose no limit on
+   * the number of cells.
    */
   template <int dim, class Vector, int spacedim>
   void
@@ -195,23 +190,23 @@ namespace GridRefinement
    * argument to this function, then the error on the children (for all
    * children together) will only be $2^{-\text{order}}\eta_K$ where
    * <code>order</code> is the third argument of this function. This makes the
-   * assumption that the error is only a local property on a mesh and can
-   * be reduced by local refinement -- an assumption that is true for the
+   * assumption that the error is only a local property on a mesh and can be
+   * reduced by local refinement -- an assumption that is true for the
    * interpolation operator, but not for the usual Galerkin projection,
    * although it is approximately true for elliptic problems where the Greens
-   * function decays quickly and the error here is not too much affected by
-   * too coarse mesh somewhere else.
+   * function decays quickly and the error here is not too much affected by a
+   * too coarse mesh somewhere else.
    *
-   * With this, we can define the objective function this function tries
-   * to optimize. Let us assume that the mesh currently has $N_0$ cells.
-   * Then, if we refine the $m$ cells with the largest errors, we expect
-   * to get (in $d$ space dimensions)
+   * With this, we can define the objective function this function tries to
+   * optimize. Let us assume that the mesh currently has $N_0$ cells. Then, if
+   * we refine the $m$ cells with the largest errors, we expect to get (in $d$
+   * space dimensions)
    * @f[
    *   N(m) = (N_0-m) + 2^d m = N_0 + (2^d-1)m
    * @f]
-   * cells ($N_0-m$ are not refined, and each of the $m$ cells we refine
-   * yield $2^d$ child cells. On the other hand, with refining $m$ cells,
-   * and using the assumptions above, we expect that the error will be
+   * cells ($N_0-m$ are not refined, and each of the $m$ cells we refine yield
+   * $2^d$ child cells. On the other hand, with refining $m$ cells, and using
+   * the assumptions above, we expect that the error will be
    * @f[
    *   \eta^\text{exp}(m)
    *   =
@@ -219,48 +214,44 @@ namespace GridRefinement
    *   +
    *   \sum_{K, K\; \text{will be refined}} 2^{-\text{order}}\eta_K
    * @f]
-   * where the first sum extends over $N_0-m$ cells and the second
-   * over the $m$ cells that will be refined. Note that $N(m)$
-   * is an increasing function of $m$ whereas $\eta^\text{exp}(m)$
-   * is a decreasing function.
+   * where the first sum extends over $N_0-m$ cells and the second over the
+   * $m$ cells that will be refined. Note that $N(m)$ is an increasing
+   * function of $m$ whereas $\eta^\text{exp}(m)$ is a decreasing function.
    *
-   * This function then tries to find that number $m$ of cells to refine
-   * for which the objective function
+   * This function then tries to find that number $m$ of cells to refine for
+   * which the objective function
    * @f[
    *   J(m) = N(m)^{\text{order}/d} \eta^\text{exp}(m)
    * @f]
    * is minimal.
    *
-   * The rationale for this function is two-fold. First, compared to
-   * the refine_and_coarsen_fixed_fraction() and
-   * refine_and_coarsen_fixed_number() functions, this function has
-   * the property that if all refinement indicators are the same
-   * (i.e., we have achieved a mesh where the error per cell is
-   * equilibrated), then the entire mesh is refined. This is based on
-   * the observation that a mesh with equilibrated error indicators is
-   * the optimal mesh (i.e., has the least overall error) among all
-   * meshes with the same number of cells. (For proofs of this, see
-   * R. Becker, M. Braack, R. Rannacher: "Numerical simulation of
-   * laminar flames at low Mach number with adaptive finite elements",
-   * Combustion Theory and Modelling, Vol. 3, Nr. 3, p. 503-534 1999;
-   * and W. Bangerth, R. Rannacher: "Adaptive Finite Element Methods
-   * for Differential Equations", Birkhauser, 2003.)
-   *
-   * Second, the function uses the observation that ideally, the error
-   * behaves like $e \approx c N^{-\alpha}$ with some constant
-   * $\alpha$ that depends on the dimension and the finite element
-   * degree. It should - given optimal mesh refinement - not depend so
-   * much on the regularity of the solution, as it is based on the
-   * idea, that all singularities can be resolved by refinement. Mesh
-   * refinement is then based on the idea that we want to make
-   * $c=e N^\alpha$ small. This corresponds to the functional $J(m)$
+   * The rationale for this function is two-fold. First, compared to the
+   * refine_and_coarsen_fixed_fraction() and refine_and_coarsen_fixed_number()
+   * functions, this function has the property that if all refinement
+   * indicators are the same (i.e., we have achieved a mesh where the error
+   * per cell is equilibrated), then the entire mesh is refined. This is based
+   * on the observation that a mesh with equilibrated error indicators is the
+   * optimal mesh (i.e., has the least overall error) among all meshes with
+   * the same number of cells. (For proofs of this, see R. Becker, M. Braack,
+   * R. Rannacher: "Numerical simulation of laminar flames at low Mach number
+   * with adaptive finite elements", Combustion Theory and Modelling, Vol. 3,
+   * Nr. 3, p. 503-534 1999; and W. Bangerth, R. Rannacher: "Adaptive Finite
+   * Element Methods for Differential Equations", Birkhauser, 2003.)
+   *
+   * Second, the function uses the observation that ideally, the error behaves
+   * like $e \approx c N^{-\alpha}$ with some constant $\alpha$ that depends
+   * on the dimension and the finite element degree. It should - given optimal
+   * mesh refinement - not depend so much on the regularity of the solution,
+   * as it is based on the idea, that all singularities can be resolved by
+   * refinement. Mesh refinement is then based on the idea that we want to
+   * make $c=e N^\alpha$ small. This corresponds to the functional $J(m)$
    * above.
    *
-   * @note This function was originally implemented by Thomas
-   *   Richter. It follows a strategy described in T. Richter,
-   *   "Parallel Multigrid Method for Adaptive Finite Elements with
-   *   Application to 3D Flow Problems", PhD thesis, University of
-   *   Heidelberg, 2005. See in particular Section 4.3, pp. 42-43.
+   * @note This function was originally implemented by Thomas Richter. It
+   * follows a strategy described in T. Richter, "Parallel Multigrid Method
+   * for Adaptive Finite Elements with Application to 3D Flow Problems", PhD
+   * thesis, University of Heidelberg, 2005. See in particular Section 4.3,
+   * pp. 42-43.
    */
   template <int dim, class Vector, int spacedim>
   void
@@ -272,16 +263,15 @@ namespace GridRefinement
    * Flag all mesh cells for which the value in @p criteria exceeds @p
    * threshold for refinement, but only flag up to @p max_to_mark cells.
    *
-   * The vector @p criteria contains a nonnegative value for each active
-   * cell, ordered in the canonical order of of
-   * Triangulation::active_cell_iterator.
+   * The vector @p criteria contains a nonnegative value for each active cell,
+   * ordered in the canonical order of of Triangulation::active_cell_iterator.
    *
-   * The cells are only flagged for refinement, they are not actually
-   * refined. To do so, you have to call
+   * The cells are only flagged for refinement, they are not actually refined.
+   * To do so, you have to call
    * Triangulation::execute_coarsening_and_refinement().
    *
-   * This function does not implement a refinement strategy, it is more
-   * helper function for the actual strategies.
+   * This function does not implement a refinement strategy, it is more a
+   * helper function for the actual strategies.
    */
   template <int dim, class Vector, int spacedim>
   void refine (Triangulation<dim,spacedim> &tria,
@@ -290,19 +280,18 @@ namespace GridRefinement
                const unsigned int max_to_mark = numbers::invalid_unsigned_int);
 
   /**
-   * Flag all mesh cells for which the value in @p criteria
-   * is less than @p threshold for coarsening.
+   * Flag all mesh cells for which the value in @p criteria is less than @p
+   * threshold for coarsening.
    *
    * The vector @p criteria contains a nonnegative value for each active cell,
-   * ordered in the canonical order of of
-   * Triangulation::active_cell_iterator.
+   * ordered in the canonical order of of Triangulation::active_cell_iterator.
    *
    * The cells are only flagged for coarsening, they are not actually
    * coarsened. To do so, you have to call
    * Triangulation::execute_coarsening_and_refinement().
    *
-   * This function does not implement a refinement strategy, it is more
-   * helper function for the actual strategies.
+   * This function does not implement a refinement strategy, it is more a
+   * helper function for the actual strategies.
    */
   template <int dim, class Vector, int spacedim>
   void coarsen (Triangulation<dim,spacedim> &tria,
@@ -310,17 +299,14 @@ namespace GridRefinement
                 const double                threshold);
 
   /**
-   * An exception thrown if the
-   * vector with cell criteria contains
-   * negative values
+   * An exception thrown if the vector with cell criteria contains negative
+   * values
    */
   DeclException0(ExcNegativeCriteria);
 
   /**
-   * One of the threshold parameters
-   * causes trouble. Or the
-   * refinement and coarsening
-   * thresholds overlap.
+   * One of the threshold parameters causes trouble. Or the refinement and
+   * coarsening thresholds overlap.
    */
   DeclException0 (ExcInvalidParameterValue);
 }
index d7c38b60cc7bb6a983de73afd79ad6ba1558ed5e..69cd09cd0df0f09b3bbd2ec3c1ee03feca7d216a 100644 (file)
@@ -34,12 +34,11 @@ DEAL_II_NAMESPACE_OPEN
  * deal.II triangulations.
  *
  * @note In contrast to the rest of the deal.II library, by default this class
- * uses the old deal.II numbering scheme, which was used up to deal.II
- * version 5.2 (but the main function of this class takes a flag that
- * specifies whether it should do an implicit conversion from the new
- * to the old format before doing its work, and then back again after
- * reordering). In this old format, the vertex and face ordering in 2d is assumed
- * to be
+ * uses the old deal.II numbering scheme, which was used up to deal.II version
+ * 5.2 (but the main function of this class takes a flag that specifies
+ * whether it should do an implicit conversion from the new to the old format
+ * before doing its work, and then back again after reordering). In this old
+ * format, the vertex and face ordering in 2d is assumed to be
  * @verbatim
  *          2
  *      3--->---2
@@ -75,30 +74,29 @@ DEAL_II_NAMESPACE_OPEN
  *     |/       /       |       |/
  *     *-------*        *-------*
  * @endverbatim
- * After calling the GridReordering::reorder_cells() function the
- * CellData is still in this old numbering scheme. Hence, for creating
- * a Triangulation based on the resulting CellData the
+ * After calling the GridReordering::reorder_cells() function the CellData is
+ * still in this old numbering scheme. Hence, for creating a Triangulation
+ * based on the resulting CellData the
  * Triangulation::create_triangulation_compatibility() (and not the
- * Triangulation::create_triangulation()) function must be used.  For
- * a typical use of the reorder_cells() function see the
- * implementation of the GridIn <code>read_*()</code> functions.
+ * Triangulation::create_triangulation()) function must be used.  For a
+ * typical use of the reorder_cells() function see the implementation of the
+ * GridIn <code>read_*()</code> functions.
  *
  *
  * <h3>Statement of problems</h3>
  *
- * Triangulations in deal.II have a special structure, in that there
- * are not only cells, but also faces, and in 3d also edges, that are
- * objects of their own right. Faces and edges have unique
- * orientations, and they have a specified orientation also with
- * respect to the cells that are adjacent. Thus, a line that separates
- * two cells in two space dimensions does not only have a direction,
- * but it must also have a well-defined orientation with respect to
- * the other lines bounding the two quadrilaterals adjacent to the
- * first line. Likewise definitions hold for three dimensional cells
- * and the objects (lines, quads) that separate them.
- *
- * For example, in two dimensions, a quad consists of four lines which
- * have a direction, which is by definition as follows:
+ * Triangulations in deal.II have a special structure, in that there are not
+ * only cells, but also faces, and in 3d also edges, that are objects of their
+ * own right. Faces and edges have unique orientations, and they have a
+ * specified orientation also with respect to the cells that are adjacent.
+ * Thus, a line that separates two cells in two space dimensions does not only
+ * have a direction, but it must also have a well-defined orientation with
+ * respect to the other lines bounding the two quadrilaterals adjacent to the
+ * first line. Likewise definitions hold for three dimensional cells and the
+ * objects (lines, quads) that separate them.
+ *
+ * For example, in two dimensions, a quad consists of four lines which have a
+ * direction, which is by definition as follows:
  * @verbatim
  *   3-->--2
  *   |     |
@@ -106,26 +104,27 @@ DEAL_II_NAMESPACE_OPEN
  *   |     |
  *   0-->--1
  * @endverbatim
- * Now, two adjacent cells must have a vertex numbering such that the direction
- * of the common side is the same. For example, the following two quads
+ * Now, two adjacent cells must have a vertex numbering such that the
+ * direction of the common side is the same. For example, the following two
+ * quads
  * @verbatim
  *   3---4---5
  *   |   |   |
  *   0---1---2
  * @endverbatim
- * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and
- * <tt>(1 2 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt>
- * when viewed from both cells.  The numbering <tt>(0 1 4 3)</tt> and
- * <tt>(5 4 1 2)</tt> would not be allowed, since the left quad would give the
- * common line the direction <tt>1->4</tt>, while the right one would want
- * to use <tt>4->1</tt>, leading to an ambiguity.
- *
- * As a sidenote, we remark that if one adopts the idea that having
- * directions of faces is useful, then the orientation of the four
- * faces of a cell as shown above is almost necessary. In particular,
- * it is not possible to orient them such that they represent a
- * (counter-)clockwise sense, since then we couldn't already find a
- * valid orientation of the following patch of three cells:
+ * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and <tt>(1 2
+ * 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt> when
+ * viewed from both cells.  The numbering <tt>(0 1 4 3)</tt> and <tt>(5 4 1
+ * 2)</tt> would not be allowed, since the left quad would give the common
+ * line the direction <tt>1->4</tt>, while the right one would want to use
+ * <tt>4->1</tt>, leading to an ambiguity.
+ *
+ * As a sidenote, we remark that if one adopts the idea that having directions
+ * of faces is useful, then the orientation of the four faces of a cell as
+ * shown above is almost necessary. In particular, it is not possible to
+ * orient them such that they represent a (counter-)clockwise sense, since
+ * then we couldn't already find a valid orientation of the following patch of
+ * three cells:
  * @verbatim
  *       o
  *     /   \
@@ -135,70 +134,64 @@ DEAL_II_NAMESPACE_OPEN
  *   |   |   |
  *   o---o---o
  * @endverbatim
- * (The reader is asked to try to find a conforming choice of line
- * directions; it will soon be obvious that there can't exists such a
- * thing, even if we allow that there might be cells with clockwise
- * and counterclockwise orientation of the lines at the same time.)
- *
- * One might argue that the definition of unique directions for faces
- * and edges, and the definition of directions relative to the cells
- * they bound, is a misfeature of deal.II. In fact, it makes reading
- * in grids created by mesh generators rather difficult, as they
- * usually don't follow these conventions when generating their
- * output. On the other hand, there are good reasons to introduce such
- * conventions, as they can make programming much simpler in many
- * cases, leading to an increase in speed of some computations as one
- * can avoid expensive checks in many places because the orientation
- * of faces is known by assumption that it is guaranteed by the
- * triangulation.
- *
- * The purpose of this class is now to find an ordering for a given
- * set of cells such that the generated triangulation satisfies all
- * the requirements stated above. To this end, we will first show some
- * examples why this is a difficult problem, and then develop
- * algorithms that finds such a reordering. Note that the algorithm
- * operates on a set of CellData objects that are used to
- * describe a mesh to the triangulation class. These objects are, for
- * example, generated by the GridIn class, when reading in grids
- * from input files.
- *
- * As a last question for this first section: is it guaranteed that
- * such orientations of faces always exist for a given subdivision of
- * a domain into cells? The linear complexity algorithm described
- * below for 2d also proves that the answer is yes for 2d. For 3d, the
- * answer is no (which also underlines that using such orientations
- * might be an -- unfortunately uncurable -- misfeature of deal.II). A
- * simple counter-example in 3d illustrates this: take a string of 3d
- * cells and bend it together to a torus. Since opposing lines in a
- * cell need to have the same direction, there is a simple ordering
- * for them, for example all lines radially outward, tangentially
- * clockwise, and axially upward. However, if before joining the two
- * ends of the string of cells, the string is twisted by 180 degrees,
- * then no such orientation is possible any more, as can easily be
- * checked. In effect, some meshes could not be used in deal.II.
- * In order to overcome this problem, the <code>face_rotation</code>,
- * <code>face_flip</code> and <code>line_orientation</code> flags have
- * been introduced. With these, it is possible to treat all purely hexahedral
+ * (The reader is asked to try to find a conforming choice of line directions;
+ * it will soon be obvious that there can't exists such a thing, even if we
+ * allow that there might be cells with clockwise and counterclockwise
+ * orientation of the lines at the same time.)
+ *
+ * One might argue that the definition of unique directions for faces and
+ * edges, and the definition of directions relative to the cells they bound,
+ * is a misfeature of deal.II. In fact, it makes reading in grids created by
+ * mesh generators rather difficult, as they usually don't follow these
+ * conventions when generating their output. On the other hand, there are good
+ * reasons to introduce such conventions, as they can make programming much
+ * simpler in many cases, leading to an increase in speed of some computations
+ * as one can avoid expensive checks in many places because the orientation of
+ * faces is known by assumption that it is guaranteed by the triangulation.
+ *
+ * The purpose of this class is now to find an ordering for a given set of
+ * cells such that the generated triangulation satisfies all the requirements
+ * stated above. To this end, we will first show some examples why this is a
+ * difficult problem, and then develop algorithms that finds such a
+ * reordering. Note that the algorithm operates on a set of CellData objects
+ * that are used to describe a mesh to the triangulation class. These objects
+ * are, for example, generated by the GridIn class, when reading in grids from
+ * input files.
+ *
+ * As a last question for this first section: is it guaranteed that such
+ * orientations of faces always exist for a given subdivision of a domain into
+ * cells? The linear complexity algorithm described below for 2d also proves
+ * that the answer is yes for 2d. For 3d, the answer is no (which also
+ * underlines that using such orientations might be an -- unfortunately
+ * uncurable -- misfeature of deal.II). A simple counter-example in 3d
+ * illustrates this: take a string of 3d cells and bend it together to a
+ * torus. Since opposing lines in a cell need to have the same direction,
+ * there is a simple ordering for them, for example all lines radially
+ * outward, tangentially clockwise, and axially upward. However, if before
+ * joining the two ends of the string of cells, the string is twisted by 180
+ * degrees, then no such orientation is possible any more, as can easily be
+ * checked. In effect, some meshes could not be used in deal.II. In order to
+ * overcome this problem, the <code>face_rotation</code>,
+ * <code>face_flip</code> and <code>line_orientation</code> flags have been
+ * introduced. With these, it is possible to treat all purely hexahedral
  * meshes. However, in order to reduce the effect of possible bugs, it should
- * still be tried to reorder a grid. Only if this procedure fails, the original
- * connectivity information should be used.
+ * still be tried to reorder a grid. Only if this procedure fails, the
+ * original connectivity information should be used.
  *
  *
  * <h3>Examples of problems</h3>
  *
- * As noted, reordering the vertex lists of cells such that the
- * resulting grid is not a trivial problem. In particular, it is often
- * not sufficient to only look at the neighborhood of a cell that
- * cannot be added to a set of other cells without violating the
- * requirements stated above. We will show two examples where this is
- * obvious.
- *
- * The first such example is the following, which we will call the
- * ``four cells at the end'' because of the four cells that close of
- * the right end of a row of three vertical cells each (in the
- * following picture we only show one such column of three cells at
- * the left, but we will indicate what happens if we prolong this
- * list):
+ * As noted, reordering the vertex lists of cells such that the resulting grid
+ * is not a trivial problem. In particular, it is often not sufficient to only
+ * look at the neighborhood of a cell that cannot be added to a set of other
+ * cells without violating the requirements stated above. We will show two
+ * examples where this is obvious.
+ *
+ * The first such example is the following, which we will call the ``four
+ * cells at the end'' because of the four cells that close of the right end of
+ * a row of three vertical cells each (in the following picture we only show
+ * one such column of three cells at the left, but we will indicate what
+ * happens if we prolong this list):
  * @verbatim
  *   9---10-----11
  *   |   |    / |
@@ -219,12 +212,12 @@ DEAL_II_NAMESPACE_OPEN
  *   ^   ^    \ |
  *   0->-1------2
  * @endverbatim
- * (This could for example be done by using the indices <tt>(0 1 4 3)</tt>, <tt>(3 4 7 6)</tt>,
- * <tt>(6 7 10 9)</tt> for the three cells). Now, you will not find a way of giving
- * indices for the right cells, without introducing either ambiguity for
- * one line or other, or without violating that within each cells, there must be
- * one vertex from which both lines are directed away and the opposite one to
- * which both adjacent lines point to.
+ * (This could for example be done by using the indices <tt>(0 1 4 3)</tt>,
+ * <tt>(3 4 7 6)</tt>, <tt>(6 7 10 9)</tt> for the three cells). Now, you will
+ * not find a way of giving indices for the right cells, without introducing
+ * either ambiguity for one line or other, or without violating that within
+ * each cells, there must be one vertex from which both lines are directed
+ * away and the opposite one to which both adjacent lines point to.
  *
  * The solution in this case is to renumber one of the three left cells, e.g.
  * by reverting the sense of the line between vertices 7 and 10 by numbering
@@ -250,18 +243,17 @@ DEAL_II_NAMESPACE_OPEN
  *   |   |   |   |   |    \ |
  *   o---o---o---o---o------o
  * @endverbatim
- * Then we run into the same problem as above if we order the cells at
- * the left uniformly, thus forcing us to revert the ordering of one
- * cell (the one which we could order as <tt>(9 6 7 10)</tt>
- * above). However, since opposite lines have to have the same
- * direction, this in turn would force us to rotate the cell left of
- * it, and then the one left to that, and so on until we reach the
- * left end of the grid. This is therefore an example we we have to
- * track back right until the first column of three cells to find a
+ * Then we run into the same problem as above if we order the cells at the
+ * left uniformly, thus forcing us to revert the ordering of one cell (the one
+ * which we could order as <tt>(9 6 7 10)</tt> above). However, since opposite
+ * lines have to have the same direction, this in turn would force us to
+ * rotate the cell left of it, and then the one left to that, and so on until
+ * we reach the left end of the grid. This is therefore an example we we have
+ * to track back right until the first column of three cells to find a
  * consistent ordering, if we had initially ordered them uniformly.
  *
- * As a second example, consider the following simple grid, where the
- * order in which the cells are numbered is important:
+ * As a second example, consider the following simple grid, where the order in
+ * which the cells are numbered is important:
  * @verbatim
  *   3-----2-----o-----o ... o-----7-----6
  *   |     |     |     |     |     |     |
@@ -269,11 +261,10 @@ DEAL_II_NAMESPACE_OPEN
  *   |     |     |     |     |     |     |
  *   0-----1-----o-----o ... o-----4-----5
  * @endverbatim
- * We have here only indicated the numbers of the vertices that are
- * relevant. Assume that the user had given the cells 0 and 1 by the
- * vertex indices <tt>0 1 2 3</tt> and <tt>6 7 4 5</tt>. Then, if we follow this
- * orientation, the grid after creating the lines for these two cells
- * would look like this:
+ * We have here only indicated the numbers of the vertices that are relevant.
+ * Assume that the user had given the cells 0 and 1 by the vertex indices
+ * <tt>0 1 2 3</tt> and <tt>6 7 4 5</tt>. Then, if we follow this orientation,
+ * the grid after creating the lines for these two cells would look like this:
  * @verbatim
  *   3-->--2-----o-----o ... o-----7--<--6
  *   |     |     |     |     |     |     |
@@ -281,102 +272,93 @@ DEAL_II_NAMESPACE_OPEN
  *   |     |     |     |     |     |     |
  *   0-->--1-----o-----o ... o-----4--<--5
  * @endverbatim
- * Now, since opposite lines must point in the same direction, we can
- * only add the cells 2 through N-1 to cells 1 such that all vertical
- * lines point down. Then, however, we cannot add cell N in any
- * direction, as it would have two opposite lines that do not point in
- * the same direction. We would have to rotate either cell 0 or 1 in
- * order to be able to add all the other cells such that the
- * requirements of deal.II triangulations are met.
- *
- * These two examples demonstrate that if we have added a certain
- * number of cells in some orientation of faces and can't add the next
- * one without introducing faces that had already been added in another
- * direction, then it might not be sufficient to only rotate cells in
- * the neighborhood of the the cell that we failed to add. It might be
- * necessary to go back a long way and rotate cells that have been
- * entered long ago.
+ * Now, since opposite lines must point in the same direction, we can only add
+ * the cells 2 through N-1 to cells 1 such that all vertical lines point down.
+ * Then, however, we cannot add cell N in any direction, as it would have two
+ * opposite lines that do not point in the same direction. We would have to
+ * rotate either cell 0 or 1 in order to be able to add all the other cells
+ * such that the requirements of deal.II triangulations are met.
+ *
+ * These two examples demonstrate that if we have added a certain number of
+ * cells in some orientation of faces and can't add the next one without
+ * introducing faces that had already been added in another direction, then it
+ * might not be sufficient to only rotate cells in the neighborhood of the the
+ * cell that we failed to add. It might be necessary to go back a long way and
+ * rotate cells that have been entered long ago.
  *
  *
  * <h3>Solution</h3>
  *
- * From the examples above, it is obvious that if we encounter a cell
- * that cannot be added to the cells which have already been entered,
- * we can not usually point to a cell that is the culprit and that
- * must be entered in a different oreintation. Furthermore, even if we
- * knew which cell, there might be large number of cells that would
- * then cease to fit into the grid and which we would have to find a
- * different orientation as well (in the second example above, if we
- * rotated cell 1, then we would have to rotate the cells 1 through
- * N-1 as well).
- *
- * A brute force approach to this problem is the following: if
- * cell N can't be added, then try to rotate cell N-1. If we can't
- * rotate cell N-1 any more, then try to rotate cell N-2 and try to
- * add cell N with all orientations of cell N-1. And so
- * on. Algorithmically, we can visualize this by a tree structure,
- * where node N has as many children as there are possible
+ * From the examples above, it is obvious that if we encounter a cell that
+ * cannot be added to the cells which have already been entered, we can not
+ * usually point to a cell that is the culprit and that must be entered in a
+ * different oreintation. Furthermore, even if we knew which cell, there might
+ * be large number of cells that would then cease to fit into the grid and
+ * which we would have to find a different orientation as well (in the second
+ * example above, if we rotated cell 1, then we would have to rotate the cells
+ * 1 through N-1 as well).
+ *
+ * A brute force approach to this problem is the following: if cell N can't be
+ * added, then try to rotate cell N-1. If we can't rotate cell N-1 any more,
+ * then try to rotate cell N-2 and try to add cell N with all orientations of
+ * cell N-1. And so on. Algorithmically, we can visualize this by a tree
+ * structure, where node N has as many children as there are possible
  * orientations of node N+1 (in two space dimensions, there are four
- * orientations in which each cell can be constructed from its four
- * vertices; for example, if the vertex indicaes are <tt>(0 1 2 3)</tt>,
- * then the four possibilities would be <tt>(0 1 2 3)</tt>, <tt>(1 2 3 0)</tt>,
- * <tt>(2 3 0 1)</tt>, and <tt>(3 0 1 2)</tt>). When adding one cell after the
- * other, we traverse this tree in a depth-first (pre-order)
- * fashion. When we encounter that one path from the root (cell 0) to
- * a leaf (the last cell) is not allowed (i.e. that the orientations
- * of the cells which are encoded in the path through the tree does
- * not lead to a valid triangulation), we have to track back and try
- * another path through the tree.
- *
- * In practice, of course, we do not follow each path to a final node
- * and then find out whether a path leads to a valid triangulation,
- * but rather use an inductive argument: if for all previously added
- * cells the triangulation is a valid one, then we can find out
- * whether a path through the tree can yield a valid triangulation by
- * checking whether entering the present cell would introduce any
- * faces that have a nonunique direction; if that is so, then we can
- * stop following all paths below this point and track back
- * immediately.
- *
- * Nevertheless, it is already obvious that the tree has <tt>4**N</tt>
- * leaves in two space dimensions, since each of the N cells can be
- * added in four orientations. Most of these nodes can be discarded
- * rapidly, since firstly the orientation of the first cell is
- * irrelevant, and secondly if we add one cell that has a neighbor
- * that has already been added, then there are already only two
- * possible orientations left, so the total number of checks we have
- * to make until we find a valid way is significantly smaller than
+ * orientations in which each cell can be constructed from its four vertices;
+ * for example, if the vertex indicaes are <tt>(0 1 2 3)</tt>, then the four
+ * possibilities would be <tt>(0 1 2 3)</tt>, <tt>(1 2 3 0)</tt>, <tt>(2 3 0
+ * 1)</tt>, and <tt>(3 0 1 2)</tt>). When adding one cell after the other, we
+ * traverse this tree in a depth-first (pre-order) fashion. When we encounter
+ * that one path from the root (cell 0) to a leaf (the last cell) is not
+ * allowed (i.e. that the orientations of the cells which are encoded in the
+ * path through the tree does not lead to a valid triangulation), we have to
+ * track back and try another path through the tree.
+ *
+ * In practice, of course, we do not follow each path to a final node and then
+ * find out whether a path leads to a valid triangulation, but rather use an
+ * inductive argument: if for all previously added cells the triangulation is
+ * a valid one, then we can find out whether a path through the tree can yield
+ * a valid triangulation by checking whether entering the present cell would
+ * introduce any faces that have a nonunique direction; if that is so, then we
+ * can stop following all paths below this point and track back immediately.
+ *
+ * Nevertheless, it is already obvious that the tree has <tt>4**N</tt> leaves
+ * in two space dimensions, since each of the N cells can be added in four
+ * orientations. Most of these nodes can be discarded rapidly, since firstly
+ * the orientation of the first cell is irrelevant, and secondly if we add one
+ * cell that has a neighbor that has already been added, then there are
+ * already only two possible orientations left, so the total number of checks
+ * we have to make until we find a valid way is significantly smaller than
  * <tt>4**N</tt>. However, the algorithm is still exponential in time and
- * linear in memory (we only have to store the information for the
- * present path in form of a stack of orientations of cells that have
- * already been added).
+ * linear in memory (we only have to store the information for the present
+ * path in form of a stack of orientations of cells that have already been
+ * added).
  *
- * In fact, the two examples above show that the exponential estimate
- * is not a pessimized one: we indeed have to track back to one of the
- * very first cells there to find a way to add all cells in a
- * consistent fashion.
+ * In fact, the two examples above show that the exponential estimate is not a
+ * pessimized one: we indeed have to track back to one of the very first cells
+ * there to find a way to add all cells in a consistent fashion.
  *
- * This discouraging situation is greatly improved by the fact that we
- * have an alternative algorithm for 2d that is always linear in
- * runtime (discovered and implemented by Michael Anderson of TICAM,
- * University of Texas, in 2003), and that for 3d we can find an
- * algorithm that in practice is usually only roughly linear in time
- * and memory. We will describe these algorithms in the following.
+ * This discouraging situation is greatly improved by the fact that we have an
+ * alternative algorithm for 2d that is always linear in runtime (discovered
+ * and implemented by Michael Anderson of TICAM, University of Texas, in
+ * 2003), and that for 3d we can find an algorithm that in practice is usually
+ * only roughly linear in time and memory. We will describe these algorithms
+ * in the following.
  *
  *
  * <h3>The 2d linear complexity algorithm</h3>
  *
- * The algorithm uses the fact that opposite faces of a cell need to
- * have the same orientation. So you start with one arbitrary line,
- * choose an orientation. Then the orientation of the opposite face is
- * already fixed. Then go to the two cells across the two faces we
- * have fixed: for them, one face is fixed, so we can also fix the
- * opposite face. Go on with doing so. Eventually, we have done this
- * for a string of cells. Then take one of the non-fixed faces of a
- * cell which has already two fixed faces and do all this again.
- *
- * In more detail, the algorithm is best illustrated using an
- * example. We consider the mesh below:
+ * The algorithm uses the fact that opposite faces of a cell need to have the
+ * same orientation. So you start with one arbitrary line, choose an
+ * orientation. Then the orientation of the opposite face is already fixed.
+ * Then go to the two cells across the two faces we have fixed: for them, one
+ * face is fixed, so we can also fix the opposite face. Go on with doing so.
+ * Eventually, we have done this for a string of cells. Then take one of the
+ * non-fixed faces of a cell which has already two fixed faces and do all this
+ * again.
+ *
+ * In more detail, the algorithm is best illustrated using an example. We
+ * consider the mesh below:
  * @verbatim
  *   9------10-------11
  *   |      |        /|
@@ -393,10 +375,10 @@ DEAL_II_NAMESPACE_OPEN
  *   0------1---------2
  * @endverbatim
  * First a cell is chosen ( (0,1,4,3) in this case). A single side of the cell
- * is oriented arbitrarily (3->4). This choice of orientation is then propogated
- * through the mesh, across sides and elements. (0->1), (6->7) and (9->10).
- * The involves edge-hopping and face hopping, giving a path through the mesh
- * shown in dots.
+ * is oriented arbitrarily (3->4). This choice of orientation is then
+ * propogated through the mesh, across sides and elements. (0->1), (6->7) and
+ * (9->10). The involves edge-hopping and face hopping, giving a path through
+ * the mesh shown in dots.
  * @verbatim
  *   9-->--10-------11
  *   |  .  |        /|
@@ -479,8 +461,8 @@ DEAL_II_NAMESPACE_OPEN
  *   |     |        \|
  *   0-->--1-->-------2
  * @endverbatim
- * It is obvious that this algorithm has linear run-time, since it
- * only ever touches each face exactly once.
+ * It is obvious that this algorithm has linear run-time, since it only ever
+ * touches each face exactly once.
  *
  * The algorithm just described is implemented in a specialization of this
  * class for the 2d case. A similar, but slightly more complex algorithm is
@@ -500,48 +482,41 @@ DEAL_II_NAMESPACE_OPEN
  * here is how it works, and why it doesn't always work for large meshes since
  * its run-time can be exponential in bad cases.
  *
- * The first observation is that although there are counterexamples,
- * problems are usually local. For example, in the second example
- * mentioned above, if we had numbered the cells in a way that
- * neighboring cells have similar cell numbers, then the amount of
- * backtracking needed is greatly reduced. Therefore, in the
- * implementation of the algorithm, the first step is to renumber the
- * cells in a Cuthill-McKee fashion: start with the cell with the
- * least number of neighbors and assign to it the cell number
- * zero. Then find all neighbors of this cell and assign to them
- * consecutive further numbers. Then find their neighbors that have
- * not yet been numbered and assign to them numbers, and so
- * on. Graphically, this represents finding zones of cells
- * consecutively further away from the initial cells and number them
- * in this front-marching way. This already greatly improves locality
- * of problems and consequently reduced the necessary amount of
- * backtracking.
- *
- * The second point is that we can use some methods to prune the tree,
- * which usually lead to a valid orientation of all cells very
- * quickly.
- *
- * The first such method is based on the observation that if we
- * fail to insert one cell with number N, then this may not be due to
- * cell N-1 unless N-1 is a direct neighbor of N. The reason is
- * abvious: the chosen orientation of cell M could only affect the
- * possibilities to add cell N if either it were a direct neighbor or
- * if there were a sequence of cells that were added after M and that
- * connected cells M and N. Clearly, for M=N-1, the latter cannot be
- * the case. Conversely, if we fail to add cell N, then it is not
- * necessary to track back to cell N-1, but we can track back to the
- * neighbor of N with the largest cell index and which has already
- * been added.
- *
- * Unfortunately, this method can fail to yield a valid path through
- * the tree if not applied with care. Consider the following
- * situation, initially extracted from a mesh of 950 cells generated
- * automatically by the program BAMG (this program usually generates
- * meshes that are quite badly balanced, often have many -- sometimes
- * 10 or more -- neighbors of one vertex, and exposed several problems
- * in the initial algorithm; note also that the example is in 2d where
- * we now have the much better algorithm described above, but the same
- * observations also apply to 3d):
+ * The first observation is that although there are counterexamples, problems
+ * are usually local. For example, in the second example mentioned above, if
+ * we had numbered the cells in a way that neighboring cells have similar cell
+ * numbers, then the amount of backtracking needed is greatly reduced.
+ * Therefore, in the implementation of the algorithm, the first step is to
+ * renumber the cells in a Cuthill-McKee fashion: start with the cell with the
+ * least number of neighbors and assign to it the cell number zero. Then find
+ * all neighbors of this cell and assign to them consecutive further numbers.
+ * Then find their neighbors that have not yet been numbered and assign to
+ * them numbers, and so on. Graphically, this represents finding zones of
+ * cells consecutively further away from the initial cells and number them in
+ * this front-marching way. This already greatly improves locality of problems
+ * and consequently reduced the necessary amount of backtracking.
+ *
+ * The second point is that we can use some methods to prune the tree, which
+ * usually lead to a valid orientation of all cells very quickly.
+ *
+ * The first such method is based on the observation that if we fail to insert
+ * one cell with number N, then this may not be due to cell N-1 unless N-1 is
+ * a direct neighbor of N. The reason is abvious: the chosen orientation of
+ * cell M could only affect the possibilities to add cell N if either it were
+ * a direct neighbor or if there were a sequence of cells that were added
+ * after M and that connected cells M and N. Clearly, for M=N-1, the latter
+ * cannot be the case. Conversely, if we fail to add cell N, then it is not
+ * necessary to track back to cell N-1, but we can track back to the neighbor
+ * of N with the largest cell index and which has already been added.
+ *
+ * Unfortunately, this method can fail to yield a valid path through the tree
+ * if not applied with care. Consider the following situation, initially
+ * extracted from a mesh of 950 cells generated automatically by the program
+ * BAMG (this program usually generates meshes that are quite badly balanced,
+ * often have many -- sometimes 10 or more -- neighbors of one vertex, and
+ * exposed several problems in the initial algorithm; note also that the
+ * example is in 2d where we now have the much better algorithm described
+ * above, but the same observations also apply to 3d):
  * @verbatim
  * 13----------14----15
  * | \         |     |
@@ -561,15 +536,14 @@ DEAL_II_NAMESPACE_OPEN
  * |     |     |     |
  * 0-----1-----2-----3
  * @endverbatim
- * Note that there is a hole in the middle. Assume now that the user
- * described the first cell 0 by the vertex numbers <tt>2 3 7 6</tt>, and
- * cell 5 by <tt>15 14 10 11</tt>, and assume that cells 1, 2, 3, and 4 are
- * numbered such that 5 can be added in initial rotation. All other
- * cells are numbered in the usual way, i.e. starting at the bottom
- * left and counting counterclockwise. Given this description of
- * cells, the algorithm will start with cell zero and add one cell
- * after the other, up until the sixth one. Then the situation will be
- * the following:
+ * Note that there is a hole in the middle. Assume now that the user described
+ * the first cell 0 by the vertex numbers <tt>2 3 7 6</tt>, and cell 5 by
+ * <tt>15 14 10 11</tt>, and assume that cells 1, 2, 3, and 4 are numbered
+ * such that 5 can be added in initial rotation. All other cells are numbered
+ * in the usual way, i.e. starting at the bottom left and counting
+ * counterclockwise. Given this description of cells, the algorithm will start
+ * with cell zero and add one cell after the other, up until the sixth one.
+ * Then the situation will be the following:
  * @verbatim
  * 13----->---14--<--15
  * | \         |     |
@@ -589,60 +563,54 @@ DEAL_II_NAMESPACE_OPEN
  * |     |     |     |
  * 0-->--1-->--2-->--3
  * @endverbatim
- * Coming now to cell 7, we see that the two opposite lines at its top
- * and bottom have different directions; we will therefore find no
- * orientation of cell 7 in which it can be added without violation of
- * the consistency of the triangulation. According to the rule stated
- * above, we track back to the neighbor with greatest index, which is
- * cell 6, but since its bottom line is to the right, its top line
- * must be to the right as well, so we won't be able to find an
- * orientation of cell 6 such that 7 will fit into the
- * triangulation. Then, if we have finished all possible orientations
- * of cell 6, we track back to the neighbor of 6 with the largest
- * index and which has been added already. This would be cell
- * 0. However, we know that the orientation of cell 0 can't be
- * important, so we conclude that there is no possible way to orient
- * all the lines of the given cells such that they satisfy the
- * requirements if deal.II triangulations. We know that this can't be,
- * so it results in an exception be thrown.
- *
- * The bottom line of this example is that when we looked at all
- * possible orientations of cell 6, we couldn't find one such that
- * cell 7 could be added, and then decided to track back to cell 0. We
- * did not even attempt to turn cell 5, after which it would be simple
- * to add cell 7. Thus, the algorithm described above has to be
- * modified: we are only allowed to track back to that neighbor that
- * has already been added, with the largest cell index, if we fail to
- * add a cell in any orientation. If we track back further because we
- * have exhausted all possible orientations but could add the cell
- * (i.e. we track back since another cell, further down the road
- * couldn't be added, irrespective of the orientation of the cell
- * which we are presently considering), then we are not allowed to
- * track back to one of its neighbors, but have to track back only one
- * cell index.
- *
- * The second method to prune the tree is that usually we cannot add a
- * new cell since the orientation of one of its neighbors that have
- * already been added is wrong. Thus, if we may try to rotate one of
- * the neighbors (of course making sure that rotating that neighbor
- * does not violate the consistency of the triangulation) in order to
- * allow the present cell to be added.
- *
- * While the first method could be explained in terms of backtracking
- * in the tree of orientations more than one step at once, turning a
- * neighbor means jumping to a totally different place in the
- * tree. For both methods, one can find arguments that they will never
- * miss a path that is valid and only skip paths that are invalid
- * anyway.
- *
- * These two methods have proven extremely efficient. We have been
- * able to read very large grids (several ten thousands of cells)
- * without the need to track back much. In particular, the time to find
- * an ordering of the cells was found to be mostly linear in the
- * number of cells, and the time to reorder them is usually much
- * smaller (for example by one order of magnitude) than the time
- * needed to read the data from a file, and also to actually generate
- * the triangulation from this data using the
+ * Coming now to cell 7, we see that the two opposite lines at its top and
+ * bottom have different directions; we will therefore find no orientation of
+ * cell 7 in which it can be added without violation of the consistency of the
+ * triangulation. According to the rule stated above, we track back to the
+ * neighbor with greatest index, which is cell 6, but since its bottom line is
+ * to the right, its top line must be to the right as well, so we won't be
+ * able to find an orientation of cell 6 such that 7 will fit into the
+ * triangulation. Then, if we have finished all possible orientations of cell
+ * 6, we track back to the neighbor of 6 with the largest index and which has
+ * been added already. This would be cell 0. However, we know that the
+ * orientation of cell 0 can't be important, so we conclude that there is no
+ * possible way to orient all the lines of the given cells such that they
+ * satisfy the requirements if deal.II triangulations. We know that this can't
+ * be, so it results in an exception be thrown.
+ *
+ * The bottom line of this example is that when we looked at all possible
+ * orientations of cell 6, we couldn't find one such that cell 7 could be
+ * added, and then decided to track back to cell 0. We did not even attempt to
+ * turn cell 5, after which it would be simple to add cell 7. Thus, the
+ * algorithm described above has to be modified: we are only allowed to track
+ * back to that neighbor that has already been added, with the largest cell
+ * index, if we fail to add a cell in any orientation. If we track back
+ * further because we have exhausted all possible orientations but could add
+ * the cell (i.e. we track back since another cell, further down the road
+ * couldn't be added, irrespective of the orientation of the cell which we are
+ * presently considering), then we are not allowed to track back to one of its
+ * neighbors, but have to track back only one cell index.
+ *
+ * The second method to prune the tree is that usually we cannot add a new
+ * cell since the orientation of one of its neighbors that have already been
+ * added is wrong. Thus, if we may try to rotate one of the neighbors (of
+ * course making sure that rotating that neighbor does not violate the
+ * consistency of the triangulation) in order to allow the present cell to be
+ * added.
+ *
+ * While the first method could be explained in terms of backtracking in the
+ * tree of orientations more than one step at once, turning a neighbor means
+ * jumping to a totally different place in the tree. For both methods, one can
+ * find arguments that they will never miss a path that is valid and only skip
+ * paths that are invalid anyway.
+ *
+ * These two methods have proven extremely efficient. We have been able to
+ * read very large grids (several ten thousands of cells) without the need to
+ * track back much. In particular, the time to find an ordering of the cells
+ * was found to be mostly linear in the number of cells, and the time to
+ * reorder them is usually much smaller (for example by one order of
+ * magnitude) than the time needed to read the data from a file, and also to
+ * actually generate the triangulation from this data using the
  * Triangulation::create_triangulation() function.
  *
  * @ingroup grid
@@ -654,56 +622,36 @@ class GridReordering
 public:
 
   /**
-   *  This is the main function,
-   *  doing what is announced in
-   *  the general documentation of
-   *  this class for dim=2 and 3
-   *  and doing nothing for dim=1.
+   * This is the main function, doing what is announced in the general
+   * documentation of this class for dim=2 and 3 and doing nothing for dim=1.
    *
-   *  If a consistent reordering is not
-   *  possible in dim=3, the original
-   *  connectivity data is restored.
+   * If a consistent reordering is not possible in dim=3, the original
+   * connectivity data is restored.
    *
-   * @param original_cells An object that contains the data that describes
-   *   the mesh.
-   * @param use_new_style_ordering If true, then use the standard
-   *   ordering of vertices within a cell. If false (the default), then
-   *   use the "old-style" ordering of vertices within cells used by
-   *   deal.II before version 5.2 and as explained in the documentation
-   *   of this class.
+   * @param original_cells An object that contains the data that describes the
+   * mesh.
+   * @param use_new_style_ordering If true, then use the standard ordering of
+   * vertices within a cell. If false (the default), then use the "old-style"
+   * ordering of vertices within cells used by deal.II before version 5.2 and
+   * as explained in the documentation of this class.
    */
   static void reorder_cells (std::vector<CellData<dim> > &original_cells,
                              const bool use_new_style_ordering = false);
 
   /**
-   * Grids generated by grid
-   * generators may have an
-   * orientation of cells which is
-   * the inverse of the orientation
-   * required by deal.II.
+   * Grids generated by grid generators may have an orientation of cells which
+   * is the inverse of the orientation required by deal.II.
    *
-   * In 2d and 3d this function checks
-   * whether all cells have
-   * negative or positive
-   * measure/volume. In the former
-   * case, all cells are inverted.
-   * It does nothing in 1d.
+   * In 2d and 3d this function checks whether all cells have negative or
+   * positive measure/volume. In the former case, all cells are inverted. It
+   * does nothing in 1d.
    *
-   * The invertion of cells might
-   * also work when only a subset
-   * of all cells have negative
-   * volume. However, grids
-   * consisting of a mixture of
-   * negative and positiv oriented
-   * cells are very likely to be
-   * broken. Therefore, an
-   * exception is thrown, in case
-   * cells are not uniformly
-   * oriented.
+   * The invertion of cells might also work when only a subset of all cells
+   * have negative volume. However, grids consisting of a mixture of negative
+   * and positiv oriented cells are very likely to be broken. Therefore, an
+   * exception is thrown, in case cells are not uniformly oriented.
    *
-   * Note, that this function
-   * should be called before
-   * reorder_cells().
+   * Note, that this function should be called before reorder_cells().
    */
   static void invert_all_cells_of_negative_grid(
     const std::vector<Point<spacedim> > &all_vertices,
index f0218dc301348abe58f4163285602e6f997d4451..686a009f0c761162cbdf4c80a345e615458cbd73 100644 (file)
@@ -38,32 +38,24 @@ namespace internal
   {
 
     /**
-     * Check whether a given
-     * arrangement of cells is
-     * already consisten. If this is
-     * the case, then we skip the
-     * reordering pass.
+     * Check whether a given arrangement of cells is already consisten. If
+     * this is the case, then we skip the reordering pass.
      *
-     * This function works by looping
-     * over all cells, checking
-     * whether one of its faces
-     * already exists in a list of
-     * edges, and if it already
-     * exists in reverse order, then
-     * return @p false. If it is not
-     * already in the list, or in the
-     * correct direction, then go on
-     * with the next faces or cell.
+     * This function works by looping over all cells, checking whether one of
+     * its faces already exists in a list of edges, and if it already exists
+     * in reverse order, then return @p false. If it is not already in the
+     * list, or in the correct direction, then go on with the next faces or
+     * cell.
      */
     bool
     is_consistent (const std::vector<CellData<2> > &cells);
 
 
     /**
-     * Defines a variety of variables related to the connectivity of a
-     * simple quad element. This includes the nodes on each edge, which
-     * edges come into each node and what the default deal.II directions
-     * are for the quad.
+     * Defines a variety of variables related to the connectivity of a simple
+     * quad element. This includes the nodes on each edge, which edges come
+     * into each node and what the default deal.II directions are for the
+     * quad.
      *
      * @verbatim
      *       s2
@@ -83,23 +75,19 @@ namespace internal
     {
     public:
       /**
-       * The nodes on each edge in
-       * anti-clockwise order
-       * { {0,1},{1,2},{2,3},{3,0} }
+       * The nodes on each edge in anti-clockwise order {
+       * {0,1},{1,2},{2,3},{3,0} }
        */
       static const int EdgeToNode[4][2];
 
       /**
-       * The edges comin into each
-       * node, in anti-clockwise
-       * order
-       * { {3,0},{0,1},{1,2},{2,3} }
+       * The edges comin into each node, in anti-clockwise order {
+       * {3,0},{0,1},{1,2},{2,3} }
        */
       static const int NodeToEdge[4][2];
 
       /**
-       * The nodes on each edge in
-       * "default direction order".
+       * The nodes on each edge in "default direction order".
        * {{0,1},{1,2},{3,2},{0,3}}
        */
       static const int DefaultOrientation[4][2];
@@ -107,8 +95,8 @@ namespace internal
 
 
     /**
-     * An enriched quad with information about how the mesh fits together
-     * so that we can move around the mesh efficiently.
+     * An enriched quad with information about how the mesh fits together so
+     * that we can move around the mesh efficiently.
      *
      * @author Michael Anderson, 2003
      */
@@ -116,10 +104,8 @@ namespace internal
     {
     public:
       /**
-       * v0 - v3 are indexes of the
-       * vertices of the quad, s0 -
-       * s3 are indexes for the
-       * sides of the quad
+       * v0 - v3 are indexes of the vertices of the quad, s0 - s3 are indexes
+       * for the sides of the quad
        */
       MQuad (const unsigned int  v0,
              const unsigned int  v1,
@@ -141,17 +127,16 @@ namespace internal
       unsigned int side[4];
 
       /**
-       * Copy of the @p CellData object
-       * from which we construct the
-       * data of this object.
+       * Copy of the @p CellData object from which we construct the data of
+       * this object.
        */
       CellData<2>  original_cell_data;
     };
 
     /**
      * The enriched side class containing connectivity information.
-     * Orientation is from v0 to v1; Initially this should have v0<v1.
-     * After global orientation could be either way.
+     * Orientation is from v0 to v1; Initially this should have v0<v1. After
+     * global orientation could be either way.
      *
      * @author Michael Anderson, 2003
      */
@@ -164,9 +149,7 @@ namespace internal
              const unsigned int initv1);
 
       /**
-       * Return whether the sides
-       * are equal, even if their
-       * ends are reversed.
+       * Return whether the sides are equal, even if their ends are reversed.
        */
       bool operator==(const MSide &s2) const;
 
@@ -192,10 +175,8 @@ namespace internal
       struct SideRectify;
 
       /**
-       * Provides a side ordering,
-       * s1<s2, without assuming
-       * v0<v1 in either of the
-       * sides.
+       * Provides a side ordering, s1<s2, without assuming v0<v1 in either of
+       * the sides.
        */
       struct SideSortLess;
     };
@@ -213,150 +194,101 @@ namespace internal
     public:
 
       /**
-       * Do the work intended by
-       * this class.
+       * Do the work intended by this class.
        */
       void reorient(std::vector<CellData<2> > &quads);
     private:
 
       /**
-       * Sets up the internal data
-       * structures so that the we can
-       * do side hopping and face
-       * switching efficiently. This
-       * means we need a whole bunch of
-       * connectivity information
+       * Sets up the internal data structures so that the we can do side
+       * hopping and face switching efficiently. This means we need a whole
+       * bunch of connectivity information
        */
       void build_graph (const std::vector<CellData<2> > &inquads);
 
       /**
-       * Orient the internal data
-       * into deal.II format The
-       * orientation algorith is as
-       * follows
+       * Orient the internal data into deal.II format The orientation algorith
+       * is as follows
        *
-       * 1) Find an unoriented quad
-       (A)
+       * 1) Find an unoriented quad (A)
        *
-       * 2) Orient an un_oriented
-       side (s) of (A)
+       * 2) Orient an un_oriented side (s) of (A)
        *
-       * 3) side hop on (s) of (A)
-       to get (B)
+       * 3) side hop on (s) of (A) to get (B)
        *
-       * 4) if opposite side to (s)
-       * of (B) is unoriented
-       * orient it
+       * 4) if opposite side to (s) of (B) is unoriented orient it
        *
-       * 5) repeat 3) and 4) until
-       * side-hoppong fails (we've
-       * reached a boundary) or (s)
-       * has already been oriented
-       * (we've closed a loop or
+       * 5) repeat 3) and 4) until side-hoppong fails (we've reached a
+       * boundary) or (s) has already been oriented (we've closed a loop or
        * unoriented sides).
        *
-       * 6) Repeat 2), 3), 4) and
-       * 5) on other unoriented
-       * sides of (A)
+       * 6) Repeat 2), 3), 4) and 5) on other unoriented sides of (A)
        *
-       * 7) Choose a new unoriented
-       * A.
+       * 7) Choose a new unoriented A.
        */
       void orient();
 
       /**
-       * Get the (now correctly
-       * oriented if we've called
-       * orient) quads.
+       * Get the (now correctly oriented if we've called orient) quads.
        */
       void get_quads(std::vector<CellData<2> > &outquads) const;
 
       /**
-       * Orient_side(qnum,lsn)
-       * orients the local side lsn
-       * of the quad qnum in the
-       * triangulation. If the side
-       * opposite lsn is oriented
-       * then lsn is oriented to
-       * match it. Otherwise it is
-       * oriented in the "default"
+       * Orient_side(qnum,lsn) orients the local side lsn of the quad qnum in
+       * the triangulation. If the side opposite lsn is oriented then lsn is
+       * oriented to match it. Otherwise it is oriented in the "default"
        * direction for the quad.
        */
       void orient_side (const unsigned int quadnum,
                         const unsigned int localsidenum);
 
       /**
-       * Returns true if all sides
-       * of the quad quadnum are
-       * oriented.
+       * Returns true if all sides of the quad quadnum are oriented.
        */
       bool is_fully_oriented_quad (const unsigned int quadnum) const;
 
       /**
-       * Returns true if the side lsn
-       * of the quad quadnum is
-       * oriented.
+       * Returns true if the side lsn of the quad quadnum is oriented.
        */
       bool is_oriented_side (const unsigned int quadnum,
                              const unsigned int lsn) const;
 
       /**
-       * Returns true is the side is
-       * oriented in the "default"
-       * direction
+       * Returns true is the side is oriented in the "default" direction
        */
       bool is_side_default_oriented (const unsigned int qnum,
                                      const unsigned int lsn) const;
 
       /**
-       * Increases UnOrQLoc from
-       * it's original value to the
-       * next quad with an
-       * unoriented side. Returns
-       * true if there was another
-       * unoriented quad.
+       * Increases UnOrQLoc from it's original value to the next quad with an
+       * unoriented side. Returns true if there was another unoriented quad.
        */
       bool get_unoriented_quad (unsigned int &UnOrQLoc) const;
 
       /**
-       * Sets sidenum to the local
-       * sidenumber of an
-       * unoriented side of the
-       * quad quadnum. Returns true
-       * if such a side exists.
+       * Sets sidenum to the local sidenumber of an unoriented side of the
+       * quad quadnum. Returns true if such a side exists.
        */
       bool get_unoriented_side (const unsigned int quadnum,
                                 unsigned int &sidenum) const;
 
       /**
-       * side_hop(&qnum, &lsn) has
-       * qnum being the quadnumber
-       * of a quad in the
-       * triangulation, and a local
-       * side number. side_hop then
-       * sets qnum to the
-       * quadnumber across the
-       * other side of the side,
-       * and sets lsn so that
-       * quads[qnum].sides[lsn] is
-       * the same before and after
-       * the call.  if there is no
-       * other quad on the other
-       * side of the current quad,
-       * then side_hop returns
-       * false.
+       * side_hop(&qnum, &lsn) has qnum being the quadnumber of a quad in the
+       * triangulation, and a local side number. side_hop then sets qnum to
+       * the quadnumber across the other side of the side, and sets lsn so
+       * that quads[qnum].sides[lsn] is the same before and after the call.
+       * if there is no other quad on the other side of the current quad, then
+       * side_hop returns false.
        */
       bool side_hop (unsigned int &qnum,
                      unsigned int &lsn) const;
 
       /**
-       * A list of enriched
-       * sides/edges of the mesh.
+       * A list of enriched sides/edges of the mesh.
        */
       std::vector<MSide> sides;
       /**
-       * A list of enriched quads
-       * in the mesh.
+       * A list of enriched quads in the mesh.
        */
       std::vector<MQuad> mquads;
     };
@@ -372,53 +304,25 @@ namespace internal
   namespace GridReordering3d
   {
     /**
-     * A structure indicating the
-     * direction of an edge. In the
-     * implementation file, we define
-     * three objects,
-     * <tt>unoriented_edge</tt>,
-     * <tt>forward_edge</tt>, and
-     * <tt>backward_edge</tt>, that
-     * denote whether an edge has
-     * already been oriented, whether
-     * it is in standard orientation,
-     * or whether it has reverse
-     * direction. The state that each
-     * of these objects encode is
-     * stored in the
-     * <tt>orientation</tt> member
-     * variable -- we would really
-     * need only three such values,
-     * which we pick in the
-     * implementation file, and make
-     * sure when we compare such
-     * objects that only these three
-     * special values are actually
-     * used.
+     * A structure indicating the direction of an edge. In the implementation
+     * file, we define three objects, <tt>unoriented_edge</tt>,
+     * <tt>forward_edge</tt>, and <tt>backward_edge</tt>, that denote whether
+     * an edge has already been oriented, whether it is in standard
+     * orientation, or whether it has reverse direction. The state that each
+     * of these objects encode is stored in the <tt>orientation</tt> member
+     * variable -- we would really need only three such values, which we pick
+     * in the implementation file, and make sure when we compare such objects
+     * that only these three special values are actually used.
      *
-     * The reason for this way of
-     * implementing things is as
-     * follows. Usually, such a
-     * property would be implemented
-     * as an enum. However, in the
-     * previous implementation, a
-     * signed integer was used with
-     * unoriented=0, forward=+1, and
-     * backward=-1. A number of
-     * operations, such as equality
-     * of ordered edges were mapped
-     * to checking whether the
-     * product of two edge
-     * orientations equals +1. Such
-     * arithmetic isn't always
-     * portable and sometimes flagged
-     * when using -ftrapv with
-     * gcc. Using this class instead
-     * makes sure that there isn't
-     * going to be any arithmetic
-     * going on on edge orientations,
-     * just comparisons for equality
-     * or inequality.
+     * The reason for this way of implementing things is as follows. Usually,
+     * such a property would be implemented as an enum. However, in the
+     * previous implementation, a signed integer was used with unoriented=0,
+     * forward=+1, and backward=-1. A number of operations, such as equality
+     * of ordered edges were mapped to checking whether the product of two
+     * edge orientations equals +1. Such arithmetic isn't always portable and
+     * sometimes flagged when using -ftrapv with gcc. Using this class instead
+     * makes sure that there isn't going to be any arithmetic going on on edge
+     * orientations, just comparisons for equality or inequality.
      *
      * @author Wolfgang Bangerth, 2005
      */
@@ -441,20 +345,12 @@ namespace internal
     };
 
     /**
-     * During building the
-     * connectivity information we
-     * don't need all the heavy duty
-     * information about edges that
-     * we will need later. So we can
-     * save memory and time by using
-     * a light-weight class for
-     * edges. It stores the two
-     * vertices, but no direction, so
-     * we make the optimization to
-     * store the vertex number in
-     * sorted order to allow for
-     * easier comparison of edge
-     * objects.
+     * During building the connectivity information we don't need all the
+     * heavy duty information about edges that we will need later. So we can
+     * save memory and time by using a light-weight class for edges. It stores
+     * the two vertices, but no direction, so we make the optimization to
+     * store the vertex number in sorted order to allow for easier comparison
+     * of edge objects.
      */
     struct CheapEdge
     {
@@ -469,16 +365,13 @@ namespace internal
       const unsigned int node1;
 
       /**
-       * Constructor. Take the
-       * vertex numbers and store
-       * them sorted.
+       * Constructor. Take the vertex numbers and store them sorted.
        */
       CheapEdge (const unsigned int n0,
                  const unsigned int n1);
 
       /**
-       * Need a partial ordering
-       * for the STL
+       * Need a partial ordering for the STL
        */
       bool operator< (const CheapEdge &e2) const;
     };
@@ -486,8 +379,7 @@ namespace internal
 
 
     /**
-     * A connectivity and orientation
-     * aware edge class.
+     * A connectivity and orientation aware edge class.
      */
     struct Edge
     {
@@ -503,28 +395,17 @@ namespace internal
       unsigned int nodes[2];
 
       /**
-       * Whether the edge has not
-       * already been oriented,
-       * points from node 0 to node
-       * 1, or the reverse.
-       * The initial state of
-       * this flag is unoriented.
+       * Whether the edge has not already been oriented, points from node 0 to
+       * node 1, or the reverse. The initial state of this flag is unoriented.
        */
       EdgeOrientation orientation_flag;
 
       /**
-       * Used to determine which
-       * "sheet" or equivalence
-       * class of parallel edges
-       * the edge falls in when
-       * oriented.
-       * numbers::invalid_unsigned_int
-       * means not yet
-       * decided. This is also the
-       * default value after
-       * construction. Each edge
-       * will later be assigned an
-       * index greater than zero.
+       * Used to determine which "sheet" or equivalence class of parallel
+       * edges the edge falls in when oriented. numbers::invalid_unsigned_int
+       * means not yet decided. This is also the default value after
+       * construction. Each edge will later be assigned an index greater than
+       * zero.
        */
       unsigned int group;
 
@@ -535,25 +416,16 @@ namespace internal
     };
 
     /**
-     * A connectivity and orientation
-     * aware cell.
+     * A connectivity and orientation aware cell.
      *
-     * The connectivity of the cell
-     * is not contained within. (This
-     * was for flexibility in using
-     * deal.II's ordering of edges or
-     * the XDA format etc.) For this
-     * information we need the
-     * ElemInfo class.
+     * The connectivity of the cell is not contained within. (This was for
+     * flexibility in using deal.II's ordering of edges or the XDA format
+     * etc.) For this information we need the ElemInfo class.
      *
-     * One thing we do know is that
-     * the first four edges in the
-     * edge class are parallel, as
-     * are the second four, and the
-     * third four.
+     * One thing we do know is that the first four edges in the edge class are
+     * parallel, as are the second four, and the third four.
      *
-     * TODO: Need to move connectivity information out
-     *       of cell and into edge.
+     * TODO: Need to move connectivity information out of cell and into edge.
      */
     struct Cell
     {
@@ -573,34 +445,24 @@ namespace internal
       unsigned int nodes[GeometryInfo<3>::vertices_per_cell];
 
       /**
-       * Which way do the edges
-       * point.  Whether node 0 of
-       * the edge is the base of
-       * the edge in local element
-       * (1) or node 1 is the base
-       * (-1).
+       * Which way do the edges point.  Whether node 0 of the edge is the base
+       * of the edge in local element (1) or node 1 is the base (-1).
        */
       EdgeOrientation local_orientation_flags[GeometryInfo<3>::lines_per_cell];
 
       /**
-       * An internal flag used to
-       * determine whether the cell
-       * is in the queue of cells
-       * to be oriented in the
-       * current sheet.
+       * An internal flag used to determine whether the cell is in the queue
+       * of cells to be oriented in the current sheet.
        */
       bool waiting_to_be_processed;
     };
 
 
     /**
-     * This holds all the pieces for
-     * orientation together.
+     * This holds all the pieces for orientation together.
      *
-     * Contains lists of nodes, edges
-     * and cells.  As well as the
-     * information about how they all
-     * connect together.
+     * Contains lists of nodes, edges and cells.  As well as the information
+     * about how they all connect together.
      */
     class Mesh
     {
@@ -611,11 +473,8 @@ namespace internal
       Mesh (const std::vector<CellData<3> > &incubes);
 
       /**
-       * Export the data of this
-       * object to the deal.II
-       * format that the
-       * Triangulation class
-       * wants as input.
+       * Export the data of this object to the deal.II format that the
+       * Triangulation class wants as input.
        */
       void
       export_to_deal_format (std::vector<CellData<3> > &outcubes) const;
@@ -632,75 +491,55 @@ namespace internal
       std::vector<Cell> cell_list;
 
       /**
-       * Checks whether every cell
-       * in the mesh is sensible.
+       * Checks whether every cell in the mesh is sensible.
        */
       void sanity_check() const;
 
       /**
-       * Given the cell list, build
-       * the edge list and all the
-       * connectivity information
-       * and other stuff that we
-       * will need later.
+       * Given the cell list, build the edge list and all the connectivity
+       * information and other stuff that we will need later.
        */
       void build_connectivity ();
 
       /**
-       * Unimplemented private copy
-       * constructor to disable it.
+       * Unimplemented private copy constructor to disable it.
        */
       Mesh (const Mesh &);
 
       /**
-       * Unimplemented private
-       * assignment operator to
-       * disable it.
+       * Unimplemented private assignment operator to disable it.
        */
       Mesh &operator=(const Mesh &);
 
       /**
-       * Checks that each edge
-       * going into a node is
-       * correctly set up.
+       * Checks that each edge going into a node is correctly set up.
        */
       void sanity_check_node (const Cell        &cell,
                               const unsigned int local_node_num) const;
 
       /**
-       * Let the orienter access
-       * out private fields.
+       * Let the orienter access out private fields.
        */
       friend class Orienter;
     };
 
 
     /**
-     * The class that orients the
-     * edges of a triangulation in
-     * 3d. The member variables
-     * basically only store the
-     * present state of the
-     * algorithm.
+     * The class that orients the edges of a triangulation in 3d. The member
+     * variables basically only store the present state of the algorithm.
      */
     class Orienter
     {
     public:
       /**
-       * Orient the given
-       * mesh. Creates an object of
-       * the present type and lets
-       * that toil away at the
-       * task.
+       * Orient the given mesh. Creates an object of the present type and lets
+       * that toil away at the task.
        *
-       * This function is the
-       * single entry point to the
-       * functionality of this
+       * This function is the single entry point to the functionality of this
        * class.
        *
-       * Returns, whether a consistent
-       * orientation of lines was possible
-       * for the given mesh.
+       * Returns, whether a consistent orientation of lines was possible for
+       * the given mesh.
        */
       static
       bool
@@ -708,90 +547,66 @@ namespace internal
 
     private:
       /**
-       * Internal representation of
-       * the given list of cells,
-       * including connectivity
-       * information and the like.
+       * Internal representation of the given list of cells, including
+       * connectivity information and the like.
        */
       Mesh mesh;
 
       /**
-       * The cube we're looking at
-       * presently.
+       * The cube we're looking at presently.
        */
       unsigned int cur_posn;
 
       /**
-       * We have fully oriented all
-       * cubes before this one.
+       * We have fully oriented all cubes before this one.
        */
       unsigned int marker_cube;
 
       /**
-       * The index of the sheet or
-       * equivalence class we are
-       * presently processing.
+       * The index of the sheet or equivalence class we are presently
+       * processing.
        */
       unsigned int cur_edge_group;
 
       /**
-       * Indices of the cells to be
-       * processed within the
-       * present sheet. If a cell
-       * is being processed
-       * presently, it is taken
-       * from this list.
+       * Indices of the cells to be processed within the present sheet. If a
+       * cell is being processed presently, it is taken from this list.
        */
       std::vector<int> sheet_to_process;
 
 
       /**
-       * Which edges of the current
-       * cell have been oriented
-       * during the current iteration.
-       * Is reset when moving on to
-       * the next cube.
+       * Which edges of the current cell have been oriented during the current
+       * iteration. Is reset when moving on to the next cube.
        */
       bool edge_orient_array[12];
 
       /**
-       * Constructor. Take a list
-       * of cells and set up the
-       * internal data structures
-       * of the mesh member
-       * variable.
+       * Constructor. Take a list of cells and set up the internal data
+       * structures of the mesh member variable.
        *
-       * Since it is
-       * private, the only entry
-       * point of this class is the
-       * static function
-       * orient_mesh().
+       * Since it is private, the only entry point of this class is the static
+       * function orient_mesh().
        */
       Orienter (const std::vector<CellData<3> > &incubes);
 
       /**
-       * Orient all the edges of a
-       * mesh.
+       * Orient all the edges of a mesh.
        *
-       * Returns, whether this action was
-       * carried out successfully.
+       * Returns, whether this action was carried out successfully.
        */
       bool orient_edges ();
 
       /**
-       * Given oriented edges,
-       * rotate the cubes so that
-       * the edges are in standard
-       * direction.
+       * Given oriented edges, rotate the cubes so that the edges are in
+       * standard direction.
        */
       void orient_cubes ();
 
       bool get_next_unoriented_cube ();
 
       /**
-       * Return whether the cell
-       * with cell number
-       * @p cell_num is fully
+       * Return whether the cell with cell number @p cell_num is fully
        * oriented.
        */
       bool is_oriented (const unsigned int cell_num) const;
@@ -801,15 +616,9 @@ namespace internal
       bool orient_next_unoriented_edge ();
 
       /**
-       * Return whether the cell is
-       * consistenty oriented at
-       * present (i.e. only
-       * considering those edges
-       * that are already
-       * oriented. This is a sanity
-       * check that should be
-       * called from inside an
-       * assert macro.
+       * Return whether the cell is consistenty oriented at present (i.e. only
+       * considering those edges that are already oriented. This is a sanity
+       * check that should be called from inside an assert macro.
        */
       bool cell_is_consistent (const unsigned int cell_num) const;
 
index f9ce7420f9d88f67478fcbd590e9fbb455dce646..7991ff55d99e69803a52fff6df8bcc5661169b8d 100644 (file)
@@ -74,100 +74,80 @@ namespace internal
 
 /**
  * This namespace is a collection of algorithms working on triangulations,
- * such as shifting or rotating triangulations, but also finding a
- * cell that contains a given point. See the descriptions of the
- * individual functions for more information.
+ * such as shifting or rotating triangulations, but also finding a cell that
+ * contains a given point. See the descriptions of the individual functions
+ * for more information.
  *
  * @ingroup grid
  */
 namespace GridTools
 {
   /**
-   *  @name Information about meshes and cells
+   * @name Information about meshes and cells
    */
   /*@{*/
 
   /**
-   * Return the diameter of a
-   * triangulation. The diameter is
-   * computed using only the
-   * vertices, i.e. if the diameter
-   * should be larger than the
-   * maximal distance between
-   * boundary vertices due to a
-   * higher order mapping, then
-   * this function will not catch
-   * this.
+   * Return the diameter of a triangulation. The diameter is computed using
+   * only the vertices, i.e. if the diameter should be larger than the maximal
+   * distance between boundary vertices due to a higher order mapping, then
+   * this function will not catch this.
    */
   template <int dim, int spacedim>
   double diameter (const Triangulation<dim, spacedim> &tria);
 
   /**
    * Compute the volume (i.e. the dim-dimensional measure) of the
-   * triangulation. We compute the measure using the integral
-   * $\sum_K \int_K 1 \; dx$ where $K$ are the cells of the
-   * given triangulation. The integral is approximated
-   * via quadrature for which we need the mapping argument.
-   *
-   * If the triangulation is a dim-dimensional one embedded in
-   * a higher dimensional space of dimension spacedim, then the
-   * value returned is the dim-dimensional measure. For example,
-   * for a two-dimensional triangulation in three-dimensional space,
-   * the value returned is the area of the surface so described.
-   * (This obviously makes sense since the spacedim-dimensional
-   * measure of a dim-dimensional triangulation would always be
-   * zero if dim @< spacedim.
+   * triangulation. We compute the measure using the integral $\sum_K \int_K 1
+   * \; dx$ where $K$ are the cells of the given triangulation. The integral
+   * is approximated via quadrature for which we need the mapping argument.
+   *
+   * If the triangulation is a dim-dimensional one embedded in a higher
+   * dimensional space of dimension spacedim, then the value returned is the
+   * dim-dimensional measure. For example, for a two-dimensional triangulation
+   * in three-dimensional space, the value returned is the area of the surface
+   * so described. (This obviously makes sense since the spacedim-dimensional
+   * measure of a dim-dimensional triangulation would always be zero if dim @<
+   * spacedim.
    *
    * This function also works for objects of type
-   * parallel::distributed::Triangulation, in which case the
-   * function is a collective operation.
+   * parallel::distributed::Triangulation, in which case the function is a
+   * collective operation.
    *
    * @param tria The triangulation.
-   * @param mapping An optional argument used to denote the mapping
-   *   that should be used when describing whether cells are bounded
-   *   by straight or curved faces. The default is to use a $Q_1$
-   *   mapping, which corresponds to straight lines bounding the
-   *   cells.
-   * @return The dim-dimensional measure of the domain described
-   *   by the triangulation, as discussed above.
+   * @param mapping An optional argument used to denote the mapping that
+   * should be used when describing whether cells are bounded by straight or
+   * curved faces. The default is to use a $Q_1$ mapping, which corresponds to
+   * straight lines bounding the cells. @return The dim-dimensional measure of
+   * the domain described by the triangulation, as discussed above.
    */
   template <int dim, int spacedim>
   double volume (const Triangulation<dim,spacedim> &tria,
                  const Mapping<dim,spacedim> &mapping = (StaticMappingQ1<dim,spacedim>::mapping));
 
   /**
-   * Return the diamater of the smallest
-   * active cell of a triangulation. See
-   * step-24 for an example
-   * of use of this function.
+   * Return the diamater of the smallest active cell of a triangulation. See
+   * step-24 for an example of use of this function.
    */
   template <int dim, int spacedim>
   double
   minimal_cell_diameter (const Triangulation<dim, spacedim> &triangulation);
 
   /**
-   * Return the diamater of the largest
-   * active cell of a triangulation.
+   * Return the diamater of the largest active cell of a triangulation.
    */
   template <int dim, int spacedim>
   double
   maximal_cell_diameter (const Triangulation<dim, spacedim> &triangulation);
 
   /**
-   * Given a list of vertices (typically
-   * obtained using
-   * Triangulation::get_vertices) as the
-   * first, and a list of vertex indices
-   * that characterize a single cell as the
-   * second argument, return the measure
-   * (area, volume) of this cell. If this
-   * is a real cell, then you can get the
-   * same result using
-   * <code>cell-@>measure()</code>, but
-   * this function also works for cells
-   * that do not exist except that you make
-   * it up by naming its vertices from the
-   * list.
+   * Given a list of vertices (typically obtained using
+   * Triangulation::get_vertices) as the first, and a list of vertex indices
+   * that characterize a single cell as the second argument, return the
+   * measure (area, volume) of this cell. If this is a real cell, then you can
+   * get the same result using <code>cell-@>measure()</code>, but this
+   * function also works for cells that do not exist except that you make it
+   * up by naming its vertices from the list.
    */
   template <int dim>
   double cell_measure (const std::vector<Point<dim> > &all_vertices,
@@ -175,41 +155,25 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Functions supporting the creation of meshes
+   * @name Functions supporting the creation of meshes
    */
   /*@{*/
 
   /**
-   * Remove vertices that are not
-   * referenced by any of the
-   * cells. This function is called
-   * by all <tt>GridIn::read_*</tt>
-   * functions to eliminate
-   * vertices that are listed in
-   * the input files but are not
-   * used by the cells in the input
-   * file. While these vertices
-   * should not be in the input
-   * from the beginning, they
-   * sometimes are, most often when
-   * some cells have been removed
-   * by hand without wanting to
-   * update the vertex lists, as
-   * they might be lengthy.
-   *
-   * This function is called by all
-   * <tt>GridIn::read_*</tt>
-   * functions as the triangulation
-   * class requires them to be
-   * called with used vertices
-   * only. This is so, since the
-   * vertices are copied verbatim
-   * by that class, so we have to
-   * eliminate unused vertices
-   * beforehand.
-   *
-   * Not implemented for the
-   * codimension one case.
+   * Remove vertices that are not referenced by any of the cells. This
+   * function is called by all <tt>GridIn::read_*</tt> functions to eliminate
+   * vertices that are listed in the input files but are not used by the cells
+   * in the input file. While these vertices should not be in the input from
+   * the beginning, they sometimes are, most often when some cells have been
+   * removed by hand without wanting to update the vertex lists, as they might
+   * be lengthy.
+   *
+   * This function is called by all <tt>GridIn::read_*</tt> functions as the
+   * triangulation class requires them to be called with used vertices only.
+   * This is so, since the vertices are copied verbatim by that class, so we
+   * have to eliminate unused vertices beforehand.
+   *
+   * Not implemented for the codimension one case.
    */
   template <int dim, int spacedim>
   void delete_unused_vertices (std::vector<Point<spacedim> >    &vertices,
@@ -217,26 +181,18 @@ namespace GridTools
                                SubCellData                 &subcelldata);
 
   /**
-   * Remove vertices that are duplicated,
-   * due to the input of a structured grid,
-   * for example. If these vertices are not
-   * removed, the faces bounded by these
-   * vertices become part of the boundary,
-   * even if they are in the interior of
-   * the mesh.
-   *
-   * This function is called by some
-   * <tt>GridIn::read_*</tt> functions. Only
-   * the vertices with indices in @p
-   * considered_vertices are tested for
-   * equality. This speeds up the algorithm,
-   * which is quadratic and thus quite slow
-   * to begin with. However, if you wish to
-   * consider all vertices, simply pass an
-   * empty vector.
-   *
-   * Two vertices are considered equal if
-   * their difference in each coordinate
+   * Remove vertices that are duplicated, due to the input of a structured
+   * grid, for example. If these vertices are not removed, the faces bounded
+   * by these vertices become part of the boundary, even if they are in the
+   * interior of the mesh.
+   *
+   * This function is called by some <tt>GridIn::read_*</tt> functions. Only
+   * the vertices with indices in @p considered_vertices are tested for
+   * equality. This speeds up the algorithm, which is quadratic and thus quite
+   * slow to begin with. However, if you wish to consider all vertices, simply
+   * pass an empty vector.
+   *
+   * Two vertices are considered equal if their difference in each coordinate
    * direction is less than @p tol.
    */
   template <int dim, int spacedim>
@@ -248,56 +204,41 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Rotating, stretching and otherwise transforming meshes
+   * @name Rotating, stretching and otherwise transforming meshes
    */
   /*@{*/
 
   /**
-   * Transform the vertices of the given
-   * triangulation by applying the
+   * Transform the vertices of the given triangulation by applying the
    * function object provided as first argument to all its vertices.
    *
-   * The transformation given as
-   * argument is used to transform
-   * each vertex. Its respective
-   * type has to offer a
-   * function-like syntax, i.e. the
-   * predicate is either an object
-   * of a type that has an
-   * <tt>operator()</tt>, or it is a
-   * pointer to the function. In
-   * either case, argument and
-   * return value have to be of
-   * type <tt>Point@<spacedim@></tt>.
-   *
-   * @note If you are using a parallel::distributed::Triangulation you will have
-   * hanging nodes in your local Triangulation even if your "global" mesh has
-   * no hanging nodes. This will cause issues with wrong positioning of hanging
-   * nodes in ghost cells if you call the current functions: The vertices of
-   * all locally owned cells will be correct,
-   * but the vertices of some ghost cells may not. This means that
-   * computations like KellyErrorEstimator may give wrong answers. A safe approach is
-   * to use this function prior to any refinement in parallel, if that is possible, but
-   * not after you refine the mesh.
-   *
-   * This function is used in the
-   * "Possibilities for extensions" section
-   * of step-38. It is also used in step-49 and step-53.
+   * The transformation given as argument is used to transform each vertex.
+   * Its respective type has to offer a function-like syntax, i.e. the
+   * predicate is either an object of a type that has an <tt>operator()</tt>,
+   * or it is a pointer to the function. In either case, argument and return
+   * value have to be of type <tt>Point@<spacedim@></tt>.
+   *
+   * @note If you are using a parallel::distributed::Triangulation you will
+   * have hanging nodes in your local Triangulation even if your "global" mesh
+   * has no hanging nodes. This will cause issues with wrong positioning of
+   * hanging nodes in ghost cells if you call the current functions: The
+   * vertices of all locally owned cells will be correct, but the vertices of
+   * some ghost cells may not. This means that computations like
+   * KellyErrorEstimator may give wrong answers. A safe approach is to use
+   * this function prior to any refinement in parallel, if that is possible,
+   * but not after you refine the mesh.
+   *
+   * This function is used in the "Possibilities for extensions" section of
+   * step-38. It is also used in step-49 and step-53.
    */
   template <int dim, typename Transformation, int spacedim>
   void transform (const Transformation        &transformation,
                   Triangulation<dim,spacedim> &triangulation);
 
   /**
-   * Shift each vertex of the
-   * triangulation by the given
-   * shift vector. This function
-   * uses the transform()
-   * function above, so the
-   * requirements on the
-   * triangulation stated there
-   * hold for this function as
-   * well.
+   * Shift each vertex of the triangulation by the given shift vector. This
+   * function uses the transform() function above, so the requirements on the
+   * triangulation stated there hold for this function as well.
    */
   template <int dim, int spacedim>
   void shift (const Point<spacedim>   &shift_vector,
@@ -305,56 +246,47 @@ namespace GridTools
 
 
   /**
-   * Rotate all vertices of the
-   * given two-dimensional
-   * triangulation in
-   * counter-clockwise sense around
-   * the origin of the coordinate
-   * system by the given angle
-   * (given in radians, rather than
-   * degrees). This function uses
-   * the transform() function
-   * above, so the requirements on
-   * the triangulation stated there
-   * hold for this function as
-   * well.
+   * Rotate all vertices of the given two-dimensional triangulation in
+   * counter-clockwise sense around the origin of the coordinate system by the
+   * given angle (given in radians, rather than degrees). This function uses
+   * the transform() function above, so the requirements on the triangulation
+   * stated there hold for this function as well.
    */
   void rotate (const double      angle,
                Triangulation<2> &triangulation);
 
   /**
    * Transform the given triangulation smoothly to a different domain where,
-   * typically, each of the vertices at the boundary of the triangulation is mapped to
-   * the corresponding points in the @p new_points map.
+   * typically, each of the vertices at the boundary of the triangulation is
+   * mapped to the corresponding points in the @p new_points map.
    *
    * The way this function works is that it solves a Laplace equation for each
    * of the dim components of a displacement field that maps the current
    * domain into one described by @p new_points . The @p new_points array
-   * therefore represents the boundary values of this displacement field.
-   * The function then evaluates this displacement field at each vertex in
-   * the interior and uses it to place the mapped vertex where the
-   * displacement field locates it. Because the solution of the Laplace
-   * equation is smooth, this guarantees a smooth mapping from the old
-   * domain to the new one.
-   *
-   * @param[in] new_points The locations where a subset of the existing vertices
-   * are to be placed. Typically, this would be a map from the vertex indices
-   * of all nodes on the boundary to their new locations, thus completely
-   * specifying the geometry of the mapped domain. However, it may also include
-   * interior points if necessary and it does not need to include all boundary
-   * vertices (although you then lose control over the exact shape of the mapped
-   * domain).
-   *
-   * @param[in,out] tria The Triangulation object. This object is changed in-place,
-   * i.e., the previous locations of vertices are overwritten.
+   * therefore represents the boundary values of this displacement field. The
+   * function then evaluates this displacement field at each vertex in the
+   * interior and uses it to place the mapped vertex where the displacement
+   * field locates it. Because the solution of the Laplace equation is smooth,
+   * this guarantees a smooth mapping from the old domain to the new one.
+   *
+   * @param[in] new_points The locations where a subset of the existing
+   * vertices are to be placed. Typically, this would be a map from the vertex
+   * indices of all nodes on the boundary to their new locations, thus
+   * completely specifying the geometry of the mapped domain. However, it may
+   * also include interior points if necessary and it does not need to include
+   * all boundary vertices (although you then lose control over the exact
+   * shape of the mapped domain).
+   *
+   * @param[in,out] tria The Triangulation object. This object is changed in-
+   * place, i.e., the previous locations of vertices are overwritten.
    *
    * @param[in] coefficient An optional coefficient for the Laplace problem.
-   * Larger values make cells less prone to deformation (effectively increasing their stiffness).
-   * The coefficient is evaluated in the coordinate system of the old,
-   * undeformed configuration of the triangulation as input, i.e., before
-   * the transformation is applied.
-   * Should this function be provided, sensible results can only be expected if
-   * all coefficients are positive.
+   * Larger values make cells less prone to deformation (effectively
+   * increasing their stiffness). The coefficient is evaluated in the
+   * coordinate system of the old, undeformed configuration of the
+   * triangulation as input, i.e., before the transformation is applied.
+   * Should this function be provided, sensible results can only be expected
+   * if all coefficients are positive.
    *
    * @note This function is not currently implemented for the 1d case.
    */
@@ -364,40 +296,25 @@ namespace GridTools
                           const Function<dim,double> *coefficient = 0);
 
   /**
-   * Scale the entire triangulation
-   * by the given factor. To
-   * preserve the orientation of
-   * the triangulation, the factor
-   * must be positive.
-   *
-   * This function uses the
-   * transform() function
-   * above, so the requirements on
-   * the triangulation stated there
-   * hold for this function as
-   * well.
+   * Scale the entire triangulation by the given factor. To preserve the
+   * orientation of the triangulation, the factor must be positive.
+   *
+   * This function uses the transform() function above, so the requirements on
+   * the triangulation stated there hold for this function as well.
    */
   template <int dim, int spacedim>
   void scale (const double        scaling_factor,
               Triangulation<dim, spacedim> &triangulation);
 
   /**
-   * Distort the given triangulation by randomly
-   * moving around all the vertices
-   * of the grid.  The direction of
-   * movement of each vertex is random, while the
-   * length of the shift vector has
-   * a value of @p factor times
-   * the minimal length of the
-   * active edges adjacent to this
-   * vertex. Note that @p factor
-   * should obviously be well below
-   * <tt>0.5</tt>.
-   *
-   * If @p keep_boundary is set to
-   * @p true (which is the
-   * default), then boundary
-   * vertices are not moved.
+   * Distort the given triangulation by randomly moving around all the
+   * vertices of the grid.  The direction of movement of each vertex is
+   * random, while the length of the shift vector has a value of @p factor
+   * times the minimal length of the active edges adjacent to this vertex.
+   * Note that @p factor should obviously be well below <tt>0.5</tt>.
+   *
+   * If @p keep_boundary is set to @p true (which is the default), then
+   * boundary vertices are not moved.
    */
   template <int dim, int spacedim>
   void distort_random (const double factor,
@@ -406,20 +323,18 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Finding cells and vertices of a triangulation
+   * @name Finding cells and vertices of a triangulation
    */
   /*@{*/
 
   /**
-   * Find and return the number of
-   * the used vertex in a given
-   * mesh that is located closest
-   * to a given point.
+   * Find and return the number of the used vertex in a given mesh that is
+   * located closest to a given point.
    *
-   * @param container A variable of a type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
-   * @param p The point for which we want to find the closest vertex.
-   * @return The index of the closest vertex found.
+   * @param container A variable of a type that satisfies the requirements of
+   * a mesh container (see @ref GlossMeshAsAContainer).
+   * @param p The point for which we want to find the closest vertex. @return
+   * The index of the closest vertex found.
    *
    * @author Ralf B. Schulz, 2006
    */
@@ -429,32 +344,27 @@ namespace GridTools
                        const Point<spacedim>     &p);
 
   /**
-   * Find and return a vector of
-   * iterators to active cells that
-   * surround a given vertex with index @p vertex_index.
-   *
-   * For locally refined grids, the
-   * vertex itself might not be a vertex
-   * of all adjacent cells that are returned.
-   * However, it will
-   * always be either a vertex of a cell or be
-   * a hanging node located on a face or an
-   * edge of it.
-   *
-   * @param container A variable of a type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
-   * @param vertex_index The index of the vertex for which we try to
-   *   find adjacent cells.
-   * @return A vector of cells that lie adjacent to the given vertex.
-   *
-   * @note If the point requested does not lie in any of the cells of
-   * the mesh given, then this function throws an exception of type
-   * GridTools::ExcPointNotFound. You can catch this exception and
-   * decide what to do in that case.
-   *
-   * @note It isn't entirely clear at this time whether the function
-   * does the right thing with anisotropically refined meshes. It needs
-   * to be checked for this case.
+   * Find and return a vector of iterators to active cells that surround a
+   * given vertex with index @p vertex_index.
+   *
+   * For locally refined grids, the vertex itself might not be a vertex of all
+   * adjacent cells that are returned. However, it will always be either a
+   * vertex of a cell or be a hanging node located on a face or an edge of it.
+   *
+   * @param container A variable of a type that satisfies the requirements of
+   * a mesh container (see @ref GlossMeshAsAContainer).
+   * @param vertex_index The index of the vertex for which we try to find
+   * adjacent cells. @return A vector of cells that lie adjacent to the given
+   * vertex.
+   *
+   * @note If the point requested does not lie in any of the cells of the mesh
+   * given, then this function throws an exception of type
+   * GridTools::ExcPointNotFound. You can catch this exception and decide what
+   * to do in that case.
+   *
+   * @note It isn't entirely clear at this time whether the function does the
+   * right thing with anisotropically refined meshes. It needs to be checked
+   * for this case.
    */
   template<int dim, template <int, int> class Container, int spacedim>
 #ifndef _MSC_VER
@@ -467,35 +377,34 @@ namespace GridTools
 
 
   /**
-   * Find and return an iterator to the active cell that surrounds a
-   * given point.
+   * Find and return an iterator to the active cell that surrounds a given
+   * point.
    *
-   * This is solely a wrapper function for the function of same name
-   * below.  A Q1 mapping is used for the boundary, and the iterator
-   * to the cell in which the point resides is returned.
+   * This is solely a wrapper function for the function of same name below.  A
+   * Q1 mapping is used for the boundary, and the iterator to the cell in
+   * which the point resides is returned.
    *
-   * It is recommended to use the other version of this function, as
-   * it simultaneously delivers the local coordinate of the given
-   * point without additional computational cost.
+   * It is recommended to use the other version of this function, as it
+   * simultaneously delivers the local coordinate of the given point without
+   * additional computational cost.
    *
-   * @param container A variable of a type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param container A variable of a type that satisfies the requirements of
+   * a mesh container (see @ref GlossMeshAsAContainer).
    * @param p The point for which we want to find the surrounding cell.
    * @return An iterator into the mesh container that points to the
-   *   surrounding cell.
-   *
-   * @note If the point requested does not lie in any of the cells of
-   * the mesh given, then this function throws an exception of type
-   * GridTools::ExcPointNotFound. You can catch this exception and
-   * decide what to do in that case.
-   *
-   * @note When applied to a triangulation or DoF handler object based
-   * on a parallel::distributed::Triangulation object, the cell
-   * returned may in fact be a ghost or artificial cell (see
-   * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
-   * many of the operations one may want to do on this cell
-   * (e.g., evaluating the solution) may not be possible and you
-   * will have to decide what to do in that case.
+   * surrounding cell.
+   *
+   * @note If the point requested does not lie in any of the cells of the mesh
+   * given, then this function throws an exception of type
+   * GridTools::ExcPointNotFound. You can catch this exception and decide what
+   * to do in that case.
+   *
+   * @note When applied to a triangulation or DoF handler object based on a
+   * parallel::distributed::Triangulation object, the cell returned may in
+   * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+   * GlossGhostCell). If so, many of the operations one may want to do on this
+   * cell (e.g., evaluating the solution) may not be possible and you will
+   * have to decide what to do in that case.
    */
   template <int dim, template <int,int> class Container, int spacedim>
 #ifndef _MSC_VER
@@ -507,50 +416,46 @@ namespace GridTools
                                  const Point<spacedim> &p);
 
   /**
-   * Find and return an iterator to the active cell that surrounds a
-   * given point @p p.
-   *
-   * The algorithm used in this function proceeds by first looking for
-   * vertex located closest to the given point, see
-   * find_closest_vertex(). Secondly, all adjacent cells to this point
-   * are found in the mesh, see find_cells_adjacent_to_vertex().
-   * Lastly, for each of these cells, it is tested whether the point
-   * is inside. This check is performed using arbitrary boundary
-   * mappings.  Still, it is possible that due to roundoff errors, the
-   * point cannot be located exactly inside the unit cell. In this
-   * case, even points at a very small distance outside the unit cell
-   * are allowed.
-   *
-   * If a point lies on the boundary of two or more cells, then the
-   * algorithm tries to identify the cell that is of highest
-   * refinement level.
-   *
-   * @param mapping The mapping used to determine whether the given
-   *   point is inside a given cell.
-   * @param container A variable of a type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * Find and return an iterator to the active cell that surrounds a given
+   * point @p p.
+   *
+   * The algorithm used in this function proceeds by first looking for vertex
+   * located closest to the given point, see find_closest_vertex(). Secondly,
+   * all adjacent cells to this point are found in the mesh, see
+   * find_cells_adjacent_to_vertex(). Lastly, for each of these cells, it is
+   * tested whether the point is inside. This check is performed using
+   * arbitrary boundary mappings.  Still, it is possible that due to roundoff
+   * errors, the point cannot be located exactly inside the unit cell. In this
+   * case, even points at a very small distance outside the unit cell are
+   * allowed.
+   *
+   * If a point lies on the boundary of two or more cells, then the algorithm
+   * tries to identify the cell that is of highest refinement level.
+   *
+   * @param mapping The mapping used to determine whether the given point is
+   * inside a given cell.
+   * @param container A variable of a type that satisfies the requirements of
+   * a mesh container (see @ref GlossMeshAsAContainer).
    * @param p The point for which we want to find the surrounding cell.
    * @return An pair of an iterator into the mesh container that points to the
-   *   surrounding cell, and of the coordinates of that point inside the cell
-   *   in the reference coordinates of that cell. This local
-   *   position might be located slightly outside an actual unit cell,
-   *   due to numerical roundoff.  Therefore, the point returned by this
-   *   function should be projected onto the unit cell, using
-   *   GeometryInfo::project_to_unit_cell().  This is not automatically
-   *   performed by the algorithm.
-   *
-   * @note If the point requested does not lie in any of the cells of
-   * the mesh given, then this function throws an exception of type
-   * GridTools::ExcPointNotFound. You can catch this exception and
-   * decide what to do in that case.
-   *
-   * @note When applied to a triangulation or DoF handler object based
-   * on a parallel::distributed::Triangulation object, the cell
-   * returned may in fact be a ghost or artificial cell (see
-   * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
-   * many of the operations one may want to do on this cell
-   * (e.g., evaluating the solution) may not be possible and you
-   * will have to decide what to do in that case.
+   * surrounding cell, and of the coordinates of that point inside the cell in
+   * the reference coordinates of that cell. This local position might be
+   * located slightly outside an actual unit cell, due to numerical roundoff.
+   * Therefore, the point returned by this function should be projected onto
+   * the unit cell, using GeometryInfo::project_to_unit_cell().  This is not
+   * automatically performed by the algorithm.
+   *
+   * @note If the point requested does not lie in any of the cells of the mesh
+   * given, then this function throws an exception of type
+   * GridTools::ExcPointNotFound. You can catch this exception and decide what
+   * to do in that case.
+   *
+   * @note When applied to a triangulation or DoF handler object based on a
+   * parallel::distributed::Triangulation object, the cell returned may in
+   * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+   * GlossGhostCell). If so, many of the operations one may want to do on this
+   * cell (e.g., evaluating the solution) may not be possible and you will
+   * have to decide what to do in that case.
    */
   template <int dim, template<int, int> class Container, int spacedim>
 #ifndef _MSC_VER
@@ -563,24 +468,22 @@ namespace GridTools
                                  const Point<spacedim>     &p);
 
   /**
-   * A version of the previous function where we use that mapping on a
-   * given cell that corresponds to the active finite element index of
-   * that cell. This is obviously only useful for hp problems, since
-   * the active finite element index for all other DoF handlers is
-   * always zero.
-   *
-   * @note If the point requested does not lie in any of the cells of
-   * the mesh given, then this function throws an exception of type
-   * GridTools::ExcPointNotFound. You can catch this exception and
-   * decide what to do in that case.
-   *
-   * @note When applied to a triangulation or DoF handler object based
-   * on a parallel::distributed::Triangulation object, the cell
-   * returned may in fact be a ghost or artificial cell (see
-   * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
-   * many of the operations one may want to do on this cell
-   * (e.g., evaluating the solution) may not be possible and you
-   * will have to decide what to do in that case.
+   * A version of the previous function where we use that mapping on a given
+   * cell that corresponds to the active finite element index of that cell.
+   * This is obviously only useful for hp problems, since the active finite
+   * element index for all other DoF handlers is always zero.
+   *
+   * @note If the point requested does not lie in any of the cells of the mesh
+   * given, then this function throws an exception of type
+   * GridTools::ExcPointNotFound. You can catch this exception and decide what
+   * to do in that case.
+   *
+   * @note When applied to a triangulation or DoF handler object based on a
+   * parallel::distributed::Triangulation object, the cell returned may in
+   * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+   * GlossGhostCell). If so, many of the operations one may want to do on this
+   * cell (e.g., evaluating the solution) may not be possible and you will
+   * have to decide what to do in that case.
    */
   template <int dim, int spacedim>
   std::pair<typename hp::DoFHandler<dim, spacedim>::active_cell_iterator, Point<dim> >
@@ -589,27 +492,21 @@ namespace GridTools
                                  const Point<spacedim>     &p);
 
   /**
-   * Return a list of all descendants of
-   * the given cell that are active. For
-   * example, if the current cell is once
-   * refined but none of its children are
-   * any further refined, then the returned
-   * list will contain all its children.
-   *
-   * If the current cell is already active,
-   * then the returned list is empty
-   * (because the cell has no children that
-   * may be active).
-   *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
-   * @param cell An iterator pointing to a cell of the mesh container.
-   * @return A list of active descendants of the given cell
-   *
-   * @note Since in C++ the type of the Container
-   * template argument can
-   * not be deduced from a function call,
-   * you will have to specify it after the
+   * Return a list of all descendants of the given cell that are active. For
+   * example, if the current cell is once refined but none of its children are
+   * any further refined, then the returned list will contain all its
+   * children.
+   *
+   * If the current cell is already active, then the returned list is empty
+   * (because the cell has no children that may be active).
+   *
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer).
+   * @param cell An iterator pointing to a cell of the mesh container. @return
+   * A list of active descendants of the given cell
+   *
+   * @note Since in C++ the type of the Container template argument can not be
+   * deduced from a function call, you will have to specify it after the
    * function name, as for example in
    * @code
    *   GridTools::get_active_child_cells<DoFHandler<dim> > (cell)
@@ -620,14 +517,14 @@ namespace GridTools
   get_active_child_cells (const typename Container::cell_iterator &cell);
 
   /**
-   * Extract the active cells around a given
-   * cell @p cell and return them in the
-   * vector @p active_neighbors.
+   * Extract the active cells around a given cell @p cell and return them in
+   * the vector @p active_neighbors.
    *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer).
    * @param cell[in] An iterator pointing to a cell of the mesh container.
-   * @param active_neighbors[out] A list of active descendants of the given cell
+   * @param active_neighbors[out] A list of active descendants of the given
+   * cell
    */
   template <class Container>
   void
@@ -636,19 +533,16 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Partitions and subdomains of triangulations
+   * @name Partitions and subdomains of triangulations
    */
   /*@{*/
 
   /**
-   * Produce a sparsity pattern in which
-   * nonzero entries indicate that two
-   * cells are connected via a common
-   * face. The diagonal entries of the
+   * Produce a sparsity pattern in which nonzero entries indicate that two
+   * cells are connected via a common face. The diagonal entries of the
    * sparsity pattern are also set.
    *
-   * The rows and columns refer to the
-   * cells as they are traversed in their
+   * The rows and columns refer to the cells as they are traversed in their
    * natural order using cell iterators.
    */
   template <int dim, int spacedim>
@@ -657,24 +551,16 @@ namespace GridTools
                                   SparsityPattern                    &connectivity);
 
   /**
-   * Use the METIS partitioner to generate
-   * a partitioning of the active cells
-   * making up the entire domain. After
-   * calling this function, the subdomain
-   * ids of all active cells will have
-   * values between zero and
-   * @p n_partitions-1. You can access the
-   * subdomain id of a cell by using
+   * Use the METIS partitioner to generate a partitioning of the active cells
+   * making up the entire domain. After calling this function, the subdomain
+   * ids of all active cells will have values between zero and @p
+   * n_partitions-1. You can access the subdomain id of a cell by using
    * <tt>cell-@>subdomain_id()</tt>.
    *
-   * This function will generate an error
-   * if METIS is not installed unless
-   * @p n_partitions is one. I.e., you can
-   * write a program so that it runs in the
-   * single-processor single-partition case
-   * without METIS installed, and only
-   * requires METIS when multiple
-   * partitions are required.
+   * This function will generate an error if METIS is not installed unless @p
+   * n_partitions is one. I.e., you can write a program so that it runs in the
+   * single-processor single-partition case without METIS installed, and only
+   * requires METIS when multiple partitions are required.
    */
   template <int dim, int spacedim>
   void
@@ -682,80 +568,46 @@ namespace GridTools
                            Triangulation<dim, spacedim> &triangulation);
 
   /**
-   * This function does the same as the
-   * previous one, i.e. it partitions a
-   * triangulation using METIS into a
-   * number of subdomains identified by the
-   * <code>cell-@>subdomain_id()</code>
-   * flag.
-   *
-   * The difference to the previous
-   * function is the second argument, a
-   * sparsity pattern that represents the
-   * connectivity pattern between cells.
-   *
-   * While the function above builds it
-   * directly from the triangulation by
-   * considering which cells neighbor each
-   * other, this function can take a more
-   * refined connectivity graph. The
-   * sparsity pattern needs to be of size
-   * $N\times N$, where $N$ is the number
-   * of active cells in the
-   * triangulation. If the sparsity pattern
-   * contains an entry at position $(i,j)$,
-   * then this means that cells $i$ and $j$
-   * (in the order in which they are
-   * traversed by active cell iterators)
-   * are to be considered connected; METIS
-   * will then try to partition the domain
-   * in such a way that (i) the subdomains
-   * are of roughly equal size, and (ii) a
-   * minimal number of connections are
-   * broken.
-   *
-   * This function is mainly useful in
-   * cases where connections between cells
-   * exist that are not present in the
-   * triangulation alone (otherwise the
-   * previous function would be the simpler
-   * one to use). Such connections may
-   * include that certain parts of the
-   * boundary of a domain are coupled
-   * through symmetric boundary conditions
-   * or integrals (e.g. friction contact
-   * between the two sides of a crack in
-   * the domain), or if a numerical scheme
-   * is used that not only connects
-   * immediate neighbors but a larger
-   * neighborhood of cells (e.g. when
-   * solving integral equations).
-   *
-   * In addition, this function may be
-   * useful in cases where the default
-   * sparsity pattern is not entirely
-   * sufficient. This can happen because
-   * the default is to just consider face
-   * neighbors, not neighboring cells that
-   * are connected by edges or
-   * vertices. While the latter couple when
-   * using continuous finite elements, they
-   * are typically still closely connected
-   * in the neighborship graph, and METIS
-   * will not usually cut important
-   * connections in this case. However, if
-   * there are vertices in the mesh where
-   * many cells (many more than the common
-   * 4 or 6 in 2d and 3d, respectively)
-   * come together, then there will be a
-   * significant number of cells that are
-   * connected across a vertex, but several
-   * degrees removed in the connectivity
-   * graph built only using face
-   * neighbors. In a case like this, METIS
-   * may sometimes make bad decisions and
-   * you may want to build your own
-   * connectivity graph.
+   * This function does the same as the previous one, i.e. it partitions a
+   * triangulation using METIS into a number of subdomains identified by the
+   * <code>cell-@>subdomain_id()</code> flag.
+   *
+   * The difference to the previous function is the second argument, a
+   * sparsity pattern that represents the connectivity pattern between cells.
+   *
+   * While the function above builds it directly from the triangulation by
+   * considering which cells neighbor each other, this function can take a
+   * more refined connectivity graph. The sparsity pattern needs to be of size
+   * $N\times N$, where $N$ is the number of active cells in the
+   * triangulation. If the sparsity pattern contains an entry at position
+   * $(i,j)$, then this means that cells $i$ and $j$ (in the order in which
+   * they are traversed by active cell iterators) are to be considered
+   * connected; METIS will then try to partition the domain in such a way that
+   * (i) the subdomains are of roughly equal size, and (ii) a minimal number
+   * of connections are broken.
+   *
+   * This function is mainly useful in cases where connections between cells
+   * exist that are not present in the triangulation alone (otherwise the
+   * previous function would be the simpler one to use). Such connections may
+   * include that certain parts of the boundary of a domain are coupled
+   * through symmetric boundary conditions or integrals (e.g. friction contact
+   * between the two sides of a crack in the domain), or if a numerical scheme
+   * is used that not only connects immediate neighbors but a larger
+   * neighborhood of cells (e.g. when solving integral equations).
+   *
+   * In addition, this function may be useful in cases where the default
+   * sparsity pattern is not entirely sufficient. This can happen because the
+   * default is to just consider face neighbors, not neighboring cells that
+   * are connected by edges or vertices. While the latter couple when using
+   * continuous finite elements, they are typically still closely connected in
+   * the neighborship graph, and METIS will not usually cut important
+   * connections in this case. However, if there are vertices in the mesh
+   * where many cells (many more than the common 4 or 6 in 2d and 3d,
+   * respectively) come together, then there will be a significant number of
+   * cells that are connected across a vertex, but several degrees removed in
+   * the connectivity graph built only using face neighbors. In a case like
+   * this, METIS may sometimes make bad decisions and you may want to build
+   * your own connectivity graph.
    */
   template <int dim, int spacedim>
   void
@@ -764,19 +616,14 @@ namespace GridTools
                            Triangulation<dim,spacedim>    &triangulation);
 
   /**
-   * For each active cell, return in the
-   * output array to which subdomain (as
-   * given by the <tt>cell->subdomain_id()</tt>
-   * function) it belongs. The output array
-   * is supposed to have the right size
-   * already when calling this function.
-   *
-   * This function returns the association
-   * of each cell with one subdomain. If
-   * you are looking for the association of
-   * each @em DoF with a subdomain, use the
-   * <tt>DoFTools::get_subdomain_association</tt>
+   * For each active cell, return in the output array to which subdomain (as
+   * given by the <tt>cell->subdomain_id()</tt> function) it belongs. The
+   * output array is supposed to have the right size already when calling this
    * function.
+   *
+   * This function returns the association of each cell with one subdomain. If
+   * you are looking for the association of each @em DoF with a subdomain, use
+   * the <tt>DoFTools::get_subdomain_association</tt> function.
    */
   template <int dim, int spacedim>
   void
@@ -784,25 +631,17 @@ namespace GridTools
                              std::vector<types::subdomain_id> &subdomain);
 
   /**
-   * Count how many cells are uniquely
-   * associated with the given @p subdomain
+   * Count how many cells are uniquely associated with the given @p subdomain
    * index.
    *
-   * This function may return zero
-   * if there are no cells with the
-   * given @p subdomain index. This
-   * can happen, for example, if
-   * you try to partition a coarse
-   * mesh into more partitions (one
-   * for each processor) than there
-   * are cells in the mesh.
-   *
-   * This function returns the number of
-   * cells associated with one
-   * subdomain. If you are looking for the
-   * association of @em DoFs with this
-   * subdomain, use the
-   * <tt>DoFTools::count_dofs_with_subdomain_association</tt>
+   * This function may return zero if there are no cells with the given @p
+   * subdomain index. This can happen, for example, if you try to partition a
+   * coarse mesh into more partitions (one for each processor) than there are
+   * cells in the mesh.
+   *
+   * This function returns the number of cells associated with one subdomain.
+   * If you are looking for the association of @em DoFs with this subdomain,
+   * use the <tt>DoFTools::count_dofs_with_subdomain_association</tt>
    * function.
    */
   template <int dim, int spacedim>
@@ -815,15 +654,14 @@ namespace GridTools
    * For a triangulation, return a mask that represents which of its vertices
    * are "owned" by the current process in the same way as we talk about
    * locally owned cells or degrees of freedom (see @ref GlossLocallyOwnedCell
-   * and @ref GlossLocallyOwnedDof). For the purpose of this function,
-   * we define a locally owned vertex as follows: a vertex is owned by
-   * that processor with the smallest subdomain id (which equals the MPI
-   * rank of that processor) among all owners of cells adjacent to this vertex.
-   * In other words, vertices that are in the interior of a partition
-   * of the triangulation are owned by the owner of this partition; for
-   * vertices that lie on the boundary between two or more partitions,
-   * the owner is the processor with the least subdomain_id among all
-   * adjacent subdomains.
+   * and @ref GlossLocallyOwnedDof). For the purpose of this function, we
+   * define a locally owned vertex as follows: a vertex is owned by that
+   * processor with the smallest subdomain id (which equals the MPI rank of
+   * that processor) among all owners of cells adjacent to this vertex. In
+   * other words, vertices that are in the interior of a partition of the
+   * triangulation are owned by the owner of this partition; for vertices that
+   * lie on the boundary between two or more partitions, the owner is the
+   * processor with the least subdomain_id among all adjacent subdomains.
    *
    * For sequential triangulations (as opposed to, for example,
    * parallel::distributed::Triangulation), every user vertex is of course
@@ -833,10 +671,10 @@ namespace GridTools
    * returns.
    *
    * @param triangulation The triangulation of which the function evaluates
-   *   which vertices are locally owned.
-   * @return The subset of vertices, as described above. The length of the
-   *   returned array equals Triangulation.n_vertices() and may, consequently,
-   *   be larger than Triangulation::n_used_vertices().
+   * which vertices are locally owned. @return The subset of vertices, as
+   * described above. The length of the returned array equals
+   * Triangulation.n_vertices() and may, consequently, be larger than
+   * Triangulation::n_used_vertices().
    */
   template <int dim, int spacedim>
   std::vector<bool>
@@ -844,68 +682,37 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Comparing different meshes
+   * @name Comparing different meshes
    */
   /*@{*/
 
   /**
-   * Given two mesh containers
-   * (i.e. objects of type
-   * Triangulation, DoFHandler,
-   * hp::DoFHandler, or
-   * MGDoFHandler) that are based
-   * on the same coarse mesh, this
-   * function figures out a set of
-   * cells that are matched between
-   * the two meshes and where at
-   * most one of the meshes is more
-   * refined on this cell. In other
-   * words, it finds the smallest
-   * cells that are common to both
-   * meshes, and that together
-   * completely cover the domain.
-   *
-   * This function is useful, for
-   * example, in time-dependent or
-   * nonlinear application, where
-   * one has to integrate a
-   * solution defined on one mesh
-   * (e.g., the one from the
-   * previous time step or
-   * nonlinear iteration) against
-   * the shape functions of another
-   * mesh (the next time step, the
-   * next nonlinear iteration). If,
-   * for example, the new mesh is
-   * finer, then one has to obtain
-   * the solution on the coarse
-   * mesh (mesh_1) and interpolate
-   * it to the children of the
-   * corresponding cell of
-   * mesh_2. Conversely, if the new
-   * mesh is coarser, one has to
-   * express the coarse cell shape
-   * function by a linear
-   * combination of fine cell shape
-   * functions. In either case, one
-   * needs to loop over the finest
-   * cells that are common to both
-   * triangulations. This function
-   * returns a list of pairs of
-   * matching iterators to cells in
-   * the two meshes that can be
-   * used to this end.
-   *
-   * Note that the list of these
-   * iterators is not necessarily
-   * ordered, and does also not
-   * necessarily coincide with the
-   * order in which cells are
-   * traversed in one, or both, of
-   * the meshes given as arguments.
-   *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * Given two mesh containers (i.e. objects of type Triangulation,
+   * DoFHandler, hp::DoFHandler, or MGDoFHandler) that are based on the same
+   * coarse mesh, this function figures out a set of cells that are matched
+   * between the two meshes and where at most one of the meshes is more
+   * refined on this cell. In other words, it finds the smallest cells that
+   * are common to both meshes, and that together completely cover the domain.
+   *
+   * This function is useful, for example, in time-dependent or nonlinear
+   * application, where one has to integrate a solution defined on one mesh
+   * (e.g., the one from the previous time step or nonlinear iteration)
+   * against the shape functions of another mesh (the next time step, the next
+   * nonlinear iteration). If, for example, the new mesh is finer, then one
+   * has to obtain the solution on the coarse mesh (mesh_1) and interpolate it
+   * to the children of the corresponding cell of mesh_2. Conversely, if the
+   * new mesh is coarser, one has to express the coarse cell shape function by
+   * a linear combination of fine cell shape functions. In either case, one
+   * needs to loop over the finest cells that are common to both
+   * triangulations. This function returns a list of pairs of matching
+   * iterators to cells in the two meshes that can be used to this end.
+   *
+   * Note that the list of these iterators is not necessarily ordered, and
+   * does also not necessarily coincide with the order in which cells are
+   * traversed in one, or both, of the meshes given as arguments.
+   *
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer).
    */
   template <typename Container>
   std::list<std::pair<typename Container::cell_iterator,
@@ -914,18 +721,13 @@ namespace GridTools
                                const Container &mesh_2);
 
   /**
-   * Return true if the two
-   * triangulations are based on
-   * the same coarse mesh. This is
-   * determined by checking whether
-   * they have the same number of
-   * cells on the coarsest level,
-   * and then checking that they
-   * have the same vertices.
-   *
-   * The two meshes may have
-   * different refinement histories
-   * beyond the coarse mesh.
+   * Return true if the two triangulations are based on the same coarse mesh.
+   * This is determined by checking whether they have the same number of cells
+   * on the coarsest level, and then checking that they have the same
+   * vertices.
+   *
+   * The two meshes may have different refinement histories beyond the coarse
+   * mesh.
    */
   template <int dim, int spacedim>
   bool
@@ -933,20 +735,13 @@ namespace GridTools
                          const Triangulation<dim, spacedim> &mesh_2);
 
   /**
-   * The same function as above,
-   * but working on arguments of
-   * type DoFHandler,
-   * hp::DoFHandler, or
-   * MGDoFHandler. This function is
-   * provided to allow calling
-   * have_same_coarse_mesh for all
-   * types of containers
-   * representing triangulations or
-   * the classes built on
-   * triangulations.
-   *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * The same function as above, but working on arguments of type DoFHandler,
+   * hp::DoFHandler, or MGDoFHandler. This function is provided to allow
+   * calling have_same_coarse_mesh for all types of containers representing
+   * triangulations or the classes built on triangulations.
+   *
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer).
    */
   template <typename Container>
   bool
@@ -964,34 +759,23 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Dealing with distorted cells
+   * @name Dealing with distorted cells
    */
   /*@{*/
 
   /**
-   * Given a triangulation and a
-   * list of cells whose children
-   * have become distorted as a
-   * result of mesh refinement, try
-   * to fix these cells up by
+   * Given a triangulation and a list of cells whose children have become
+   * distorted as a result of mesh refinement, try to fix these cells up by
    * moving the center node around.
    *
-   * The function returns a list of
-   * cells with distorted children
-   * that couldn't be fixed up for
-   * whatever reason. The returned
-   * list is therefore a subset of
-   * the input argument.
-   *
-   * For a definition of the
-   * concept of distorted cells,
-   * see the
-   * @ref GlossDistorted "glossary entry".
-   * The first argument passed to the
-   * current function is typically
-   * the exception thrown by the
-   * Triangulation::execute_coarsening_and_refinement
-   * function.
+   * The function returns a list of cells with distorted children that
+   * couldn't be fixed up for whatever reason. The returned list is therefore
+   * a subset of the input argument.
+   *
+   * For a definition of the concept of distorted cells, see the @ref
+   * GlossDistorted "glossary entry". The first argument passed to the current
+   * function is typically the exception thrown by the
+   * Triangulation::execute_coarsening_and_refinement function.
    */
   template <int dim, int spacedim>
   typename Triangulation<dim,spacedim>::DistortedCellList
@@ -1000,7 +784,7 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Extracting and creating patches of cells surrounding a single cell
+   * @name Extracting and creating patches of cells surrounding a single cell
    */
   /*@{*/
 
@@ -1011,29 +795,29 @@ namespace GridTools
    * part of a face in common with the given cell, but not edge (in 3d) or
    * vertex neighbors (in 2d and 3d).
    *
-   * The first element of the returned list is the cell provided as
-   * argument. The remaining ones are neighbors: The function loops over all
-   * faces of that given cell and checks if that face is not on the boundary of
-   * the domain. Then, if the neighbor cell does not have any children (i.e., it
+   * The first element of the returned list is the cell provided as argument.
+   * The remaining ones are neighbors: The function loops over all faces of
+   * that given cell and checks if that face is not on the boundary of the
+   * domain. Then, if the neighbor cell does not have any children (i.e., it
    * is either at the same refinement level as the current cell, or coarser)
    * then this neighbor cell is added to the list of cells. Otherwise, if the
    * neighbor cell is refined and therefore has children, then this function
    * loops over all subfaces of current face adds the neighbors behind these
    * sub-faces to the list to be returned.
    *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
-   *   In C++, the compiler can not determine the type of <code>Container</code>
-   *   from the function call. You need to specify it as an explicit template
-   *   argument following the function name.
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer). In C++, the compiler can not
+   * determine the type of <code>Container</code> from the function call. You
+   * need to specify it as an explicit template argument following the
+   * function name.
    * @param cell[in] An iterator pointing to a cell of the mesh container.
    * @return A list of active cells that form the patch around the given cell
    *
-   * @note Patches are often used in defining error estimators that require the
-   * solution of a local problem on the patch surrounding each of the cells of
-   * the mesh. This also requires manipulating the degrees of freedom associated
-   * with the cells of a patch. To this end, there are further functions working
-   * on patches in namespace DoFTools.
+   * @note Patches are often used in defining error estimators that require
+   * the solution of a local problem on the patch surrounding each of the
+   * cells of the mesh. This also requires manipulating the degrees of freedom
+   * associated with the cells of a patch. To this end, there are further
+   * functions working on patches in namespace DoFTools.
    *
    * @note In the context of a parallel distributed computation, it only makes
    * sense to call this function on locally owned cells. This is because the
@@ -1051,7 +835,7 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Lower-dimensional meshes for parts of higher-dimensional meshes
+   * @name Lower-dimensional meshes for parts of higher-dimensional meshes
    */
   /*@{*/
 
@@ -1090,14 +874,14 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Dealing with periodic domains
+   * @name Dealing with periodic domains
    */
   /*@{*/
 
   /**
-   * Data type that provides all information necessary to create
-   * periodicity constraints and a periodic p4est forest with respect to
-   * two 'periodic' cell faces.
+   * Data type that provides all information necessary to create periodicity
+   * constraints and a periodic p4est forest with respect to two 'periodic'
+   * cell faces.
    */
   template<typename CellIterator>
   struct PeriodicFacePair
@@ -1108,30 +892,29 @@ namespace GridTools
     CellIterator cell[2];
 
     /**
-     * The local face indices (with respect to the specified cells) of the
-     * two 'periodic' faces.
+     * The local face indices (with respect to the specified cells) of the two
+     * 'periodic' faces.
      */
     unsigned int face_idx[2];
 
     /**
-     * The relative orientation of the first face with respect to the
-     * second face as described in orthogonal_equality() and
+     * The relative orientation of the first face with respect to the second
+     * face as described in orthogonal_equality() and
      * make_periodicity_constraints() (and stored as a bitset).
      */
     std::bitset<3> orientation;
 
     /**
-     * A matrix that describes how vector valued DoFs of the first face
-     * should be modified prior to constraining to the DoFs of the second
-     * face. If the std::vector first_vector_components is non empty the
-     * matrix is interpreted as a @p dim $\times$ @p dim rotation matrix
-     * that is applied to all vector valued blocks listed in
-     * @p first_vector_components of the FESystem. If
-     * @p first_vector_components is empty the matrix is interpreted as an
-     * interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
-     * For more details see make_periodicity_constraints() and the glossary
-     * @ref GlossPeriodicConstraints "glossary entry on periodic boundary
-     * conditions".
+     * A matrix that describes how vector valued DoFs of the first face should
+     * be modified prior to constraining to the DoFs of the second face. If
+     * the std::vector first_vector_components is non empty the matrix is
+     * interpreted as a @p dim $\times$ @p dim rotation matrix that is applied
+     * to all vector valued blocks listed in @p first_vector_components of the
+     * FESystem. If @p first_vector_components is empty the matrix is
+     * interpreted as an interpolation matrix with size no_face_dofs $\times$
+     * no_face_dofs. For more details see make_periodicity_constraints() and
+     * the glossary @ref GlossPeriodicConstraints "glossary entry on periodic
+     * boundary conditions".
      */
     FullMatrix<double> matrix;
 
@@ -1147,18 +930,16 @@ namespace GridTools
    * An orthogonal equality test for faces.
    *
    * @p face1 and @p face2 are considered equal, if a one to one matching
-   * between its vertices can be achieved via an orthogonal equality
-   * relation.
+   * between its vertices can be achieved via an orthogonal equality relation.
    *
-   * Hereby, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered
-   * equal, if $M\cdot v_1 + offset - v_2</code> is parallel to the unit
-   * vector in unit direction @p direction. If the parameter @p matrix
-   * is a reference to a spacedim x spacedim matrix, $M$ is set to @p
-   * matrix, otherwise $M$ is the identity matrix.
+   * Hereby, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered equal,
+   * if $M\cdot v_1 + offset - v_2</code> is parallel to the unit vector in
+   * unit direction @p direction. If the parameter @p matrix is a reference to
+   * a spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is
+   * the identity matrix.
    *
    * If the matching was successful, the _relative_ orientation of @p face1
-   * with respect to @p face2 is returned in the bitset @p orientation,
-   * where
+   * with respect to @p face2 is returned in the bitset @p orientation, where
    * @code
    * orientation[0] -> face_orientation
    * orientation[1] -> face_flip
@@ -1169,10 +950,9 @@ namespace GridTools
    * <tt>face_rotation</tt> is always <tt>false</tt>, and face_flip has the
    * meaning of <tt>line_flip</tt>. More precisely in 3d:
    *
-   * <tt>face_orientation</tt>:
-   * <tt>true</tt> if @p face1 and @p face2 have the same orientation.
-   * Otherwise, the vertex indices of @p face1 match the vertex indices of
-   * @p face2 in the following manner:
+   * <tt>face_orientation</tt>: <tt>true</tt> if @p face1 and @p face2 have
+   * the same orientation. Otherwise, the vertex indices of @p face1 match the
+   * vertex indices of @p face2 in the following manner:
    *
    * @code
    * face1:           face2:
@@ -1182,8 +962,8 @@ namespace GridTools
    * 0 - 2            0 - 1
    * @endcode
    *
-   * <tt>face_flip</tt>:
-   * <tt>true</tt> if the matched vertices are rotated by 180 degrees:
+   * <tt>face_flip</tt>: <tt>true</tt> if the matched vertices are rotated by
+   * 180 degrees:
    *
    * @code
    * face1:           face2:
@@ -1193,8 +973,8 @@ namespace GridTools
    * 3 - 2            0 - 1
    * @endcode
    *
-   * <tt>face_rotation</tt>: <tt>true</tt> if the matched vertices are
-   * rotated by 90 degrees counterclockwise:
+   * <tt>face_rotation</tt>: <tt>true</tt> if the matched vertices are rotated
+   * by 90 degrees counterclockwise:
    *
    * @code
    * face1:           face2:
@@ -1204,9 +984,8 @@ namespace GridTools
    * 1 - 3            0 - 1
    * @endcode
    *
-   * and any combination of that...
-   * More information on the topic can be found in the
-   * @ref GlossFaceOrientation "glossary" article.
+   * and any combination of that... More information on the topic can be found
+   * in the @ref GlossFaceOrientation "glossary" article.
    *
    * @author Matthias Maier, 2012
    */
@@ -1235,40 +1014,39 @@ namespace GridTools
 
 
   /**
-   * This function will collect periodic face pairs on the
-   * coarsest mesh level of the given @p container (a Triangulation or
-   * DoFHandler) and add them to the vector @p matched_pairs leaving the
-   * original contents intact.
+   * This function will collect periodic face pairs on the coarsest mesh level
+   * of the given @p container (a Triangulation or DoFHandler) and add them to
+   * the vector @p matched_pairs leaving the original contents intact.
    *
-   * Define a 'first' boundary as all boundary faces having boundary_id
-   * @p b_id1 and a 'second' boundary consisting of all faces belonging
-   * to @p b_id2.
+   * Define a 'first' boundary as all boundary faces having boundary_id @p
+   * b_id1 and a 'second' boundary consisting of all faces belonging to @p
+   * b_id2.
    *
-   * This function tries to match all faces belonging to the first
-   * boundary with faces belonging to the second boundary with the help
-   * of orthogonal_equality().
+   * This function tries to match all faces belonging to the first boundary
+   * with faces belonging to the second boundary with the help of
+   * orthogonal_equality().
    *
    * The bitset that is returned inside of PeriodicFacePair encodes the
-   * _relative_ orientation of the first face with respect to the second
-   * face, see the documentation of orthogonal_equality() for further details.
+   * _relative_ orientation of the first face with respect to the second face,
+   * see the documentation of orthogonal_equality() for further details.
    *
-   * The @p direction refers to the space direction in which periodicity
-   * is enforced.
+   * The @p direction refers to the space direction in which periodicity is
+   * enforced.
    *
    * The @p offset is a vector tangential to the faces that is added to the
    * location of vertices of the 'first' boundary when attempting to match
-   * them to the corresponding vertices of the 'second' boundary. This can
-   * be used to implement conditions such as $u(0,y)=u(1,y+1)$.
-   *
-   * Optionally a (dim x dim) rotation matrix @p matrix along with a vector
-   * @p first_vector_components can be specified that describes how vector
-   * valued DoFs of the first face should be modified prior to constraining
-   * to the DoFs of the second face. If @p first_vector_components is non
-   * empty the matrix is interpreted as a rotation matrix that is applied
-   * to all vector valued blocks listed in @p first_vector_components of
-   * the FESystem. For more details see make_periodicity_constraints() and
-   * the glossary
-   * @ref GlossPeriodicConstraints "glossary entry on periodic boundary conditions".
+   * them to the corresponding vertices of the 'second' boundary. This can be
+   * used to implement conditions such as $u(0,y)=u(1,y+1)$.
+   *
+   * Optionally a (dim x dim) rotation matrix @p matrix along with a vector @p
+   * first_vector_components can be specified that describes how vector valued
+   * DoFs of the first face should be modified prior to constraining to the
+   * DoFs of the second face. If @p first_vector_components is non empty the
+   * matrix is interpreted as a rotation matrix that is applied to all vector
+   * valued blocks listed in @p first_vector_components of the FESystem. For
+   * more details see make_periodicity_constraints() and the glossary @ref
+   * GlossPeriodicConstraints "glossary entry on periodic boundary
+   * conditions".
    *
    * @tparam Container A type that satisfies the requirements of a mesh
    * container (see @ref GlossMeshAsAContainer).
@@ -1299,35 +1077,34 @@ namespace GridTools
 
 
   /**
-   * This compatibility version of collect_periodic_face_pairs() only works
-   * on grids with cells in @ref GlossFaceOrientation "standard orientation".
+   * This compatibility version of collect_periodic_face_pairs() only works on
+   * grids with cells in @ref GlossFaceOrientation "standard orientation".
    *
-   * Instead of defining a 'first' and 'second' boundary with the help of
-   * two boundary_indicators this function defines a 'left' boundary as all
-   * faces with local face index <code>2*dimension</code> and boundary
-   * indicator @p b_id and, similarly, a 'right' boundary consisting of all
-   * face with local face index <code>2*dimension+1</code> and boundary
-   * indicator @p b_id.
+   * Instead of defining a 'first' and 'second' boundary with the help of two
+   * boundary_indicators this function defines a 'left' boundary as all faces
+   * with local face index <code>2*dimension</code> and boundary indicator @p
+   * b_id and, similarly, a 'right' boundary consisting of all face with local
+   * face index <code>2*dimension+1</code> and boundary indicator @p b_id.
    *
    * This function will collect periodic face pairs on the coarsest mesh level
    * and add them to @p matched_pairs leaving the original contents intact.
    *
-   * Optionally a rotation matrix @p matrix along with a vector
-   * @p first_vector_components can be specified that describes how vector
-   * valued DoFs of the first face should be modified prior to constraining
-   * to the DoFs of the second face. If @p first_vector_components is non
-   * empty the matrix is interpreted as a rotation matrix that is applied
-   * to all vector valued blocks listet in @p first_vector_components of
-   * the FESystem. For more details see make_periodicity_constraints() and
-   * the glossary @ref GlossPeriodicConstraints "glossary entry on periodic
-   * boundary conditions".
+   * Optionally a rotation matrix @p matrix along with a vector @p
+   * first_vector_components can be specified that describes how vector valued
+   * DoFs of the first face should be modified prior to constraining to the
+   * DoFs of the second face. If @p first_vector_components is non empty the
+   * matrix is interpreted as a rotation matrix that is applied to all vector
+   * valued blocks listet in @p first_vector_components of the FESystem. For
+   * more details see make_periodicity_constraints() and the glossary @ref
+   * GlossPeriodicConstraints "glossary entry on periodic boundary
+   * conditions".
    *
-   * @tparam Container A type that satisfies the
-   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @tparam Container A type that satisfies the requirements of a mesh
+   * container (see @ref GlossMeshAsAContainer).
    *
    * @note This version of collect_periodic_face_pairs() will not work on
-   * meshes with cells not in @ref GlossFaceOrientation
-   * "standard orientation".
+   * meshes with cells not in @ref GlossFaceOrientation "standard
+   * orientation".
    *
    * @author Daniel Arndt, Matthias Maier, 2013, 2014
    */
@@ -1345,7 +1122,7 @@ namespace GridTools
 
   /*@}*/
   /**
-   *  @name Exceptions
+   * @name Exceptions
    */
   /*@{*/
 
index 27bba0ead4dfb6065fccdb87591547dafa4a51c4..e8f52b897a92bf8a9b7c9e7320467add1b0403eb 100644 (file)
@@ -26,22 +26,20 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class provides a map between two grids which are derived from
- * the same coarse grid. For each cell iterator of the source map, it provides
- * the respective cell iterator on the destination map, through its
- * <tt>operator []</tt>.
+ * This class provides a map between two grids which are derived from the same
+ * coarse grid. For each cell iterator of the source map, it provides the
+ * respective cell iterator on the destination map, through its <tt>operator
+ * []</tt>.
  *
  * Usually, the two grids will be refined differently. Then, the value
  * returned for an iterator on the source grid will be either:
  * <ul>
- *   <li> The same cell on the destination grid, if it exists there;
- *   <li> The most refined cell of the destination grid from which the
- *      pendant of the source cell could be obtained by refinement. This
- *      cell is always active and has a refinement level less than that
- *      of the source cell.
+ * <li> The same cell on the destination grid, if it exists there;
+ * <li> The most refined cell of the destination grid from which the pendant
+ * of the source cell could be obtained by refinement. This cell is always
+ * active and has a refinement level less than that of the source cell.
  * </ul>
- * Keys for this map are all cells on the source grid, whether active or
- * not.
+ * Keys for this map are all cells on the source grid, whether active or not.
  *
  * For example, consider these two one-dimensional grids:
  * @verbatim
@@ -53,9 +51,9 @@ DEAL_II_NAMESPACE_OPEN
  *   x-----x-----x-----x-----x
  *      1     2     3     4
  * @endverbatim
- * (Cell numbers are only given as an example and will not correspond
- * to real cell iterator's indices.) The mapping from grid 1 to grid 2
- * will then be as follows:
+ * (Cell numbers are only given as an example and will not correspond to real
+ * cell iterator's indices.) The mapping from grid 1 to grid 2 will then be as
+ * follows:
  * @verbatim
  *    Cell on grid 1         Cell on grid 2
  *          1  ------------------>  1
@@ -68,16 +66,16 @@ DEAL_II_NAMESPACE_OPEN
  * valid keys. For example, the mapping for the mother cell of cells 1 and 2
  * on the first grid will point to cell 1 on the second grid.
  *
- * The implementation of this class is such that not only cell
- * iterators into triangulations can be mapped, but also iterators
- * into objects of type DoFHandler, hp::DoFHandler and
- * MGDoFHandler. The extension to other classes offering iterator
- * functions and some minor additional requirements is simple.
+ * The implementation of this class is such that not only cell iterators into
+ * triangulations can be mapped, but also iterators into objects of type
+ * DoFHandler, hp::DoFHandler and MGDoFHandler. The extension to other classes
+ * offering iterator functions and some minor additional requirements is
+ * simple.
  *
- * Note that this class could in principle be based on the C++ <tt>map<Key,Value></tt>
- * data type. Instead, it uses another data format which is more effective both
- * in terms of computing time for access as well as with regard to memory
- * consumpion.
+ * Note that this class could in principle be based on the C++
+ * <tt>map<Key,Value></tt> data type. Instead, it uses another data format
+ * which is more effective both in terms of computing time for access as well
+ * as with regard to memory consumpion.
  *
  *
  * <h3>Usage</h3>
@@ -108,9 +106,9 @@ DEAL_II_NAMESPACE_OPEN
  * @endverbatim
  *
  * Note that the template parameters to this class have to be given as
- * <tt>InterGridMap<DoFHandler<2> ></tt>, which here is DoFHandler
- * (and could equally well be Triangulation, PersistentTriangulation,
- * hp::DoFHandler or MGDoFHandler).
+ * <tt>InterGridMap<DoFHandler<2> ></tt>, which here is DoFHandler (and could
+ * equally well be Triangulation, PersistentTriangulation, hp::DoFHandler or
+ * MGDoFHandler).
  *
  * @ingroup grid
  * @author Wolfgang Bangerth, 1999
@@ -121,33 +119,25 @@ class InterGridMap : public Subscriptor
 public:
 
   /**
-   * Typedef to the iterator type of
-   * the grid class under consideration.
+   * Typedef to the iterator type of the grid class under consideration.
    */
   typedef typename GridClass::cell_iterator cell_iterator;
 
   /**
-   * Constructor setting the class
-   * name arguments in the
-   * SmartPointer members.
+   * Constructor setting the class name arguments in the SmartPointer members.
    */
   InterGridMap();
 
   /**
-   * Create the mapping between the two
-   * grids.
+   * Create the mapping between the two grids.
    */
   void make_mapping (const GridClass &source_grid,
                      const GridClass &destination_grid);
 
   /**
-   * Access operator: give a cell
-   * on the source grid and receive
-   * the respective cell on the
-   * other grid, or if that does not
-   * exist, the most refined cell
-   * of which the source cell would
-   * be created if it were further
+   * Access operator: give a cell on the source grid and receive the
+   * respective cell on the other grid, or if that does not exist, the most
+   * refined cell of which the source cell would be created if it were further
    * refined.
    */
   cell_iterator operator [] (const cell_iterator &source_cell) const;
@@ -158,21 +148,18 @@ public:
   void clear ();
 
   /**
-   * Return a pointer to the source
-   * grid.
+   * Return a pointer to the source grid.
    */
   const GridClass &get_source_grid () const;
 
   /**
-   * Return a pointer to the
-   * destination grid.
+   * Return a pointer to the destination grid.
    */
   const GridClass &get_destination_grid () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -190,8 +177,7 @@ public:
 
 private:
   /**
-   * The actual data. Hold one iterator
-   * for each cell on each level.
+   * The actual data. Hold one iterator for each cell on each level.
    */
   std::vector<std::vector<cell_iterator> > mapping;
 
@@ -206,25 +192,18 @@ private:
   SmartPointer<const GridClass,InterGridMap<GridClass> > destination_grid;
 
   /**
-   * Set the mapping for the pair of
-   * cells given. These shall match
-   * in level of refinement and all
-   * other properties.
+   * Set the mapping for the pair of cells given. These shall match in level
+   * of refinement and all other properties.
    */
   void set_mapping (const cell_iterator &src_cell,
                     const cell_iterator &dst_cell);
 
   /**
-   * Set the value of the key @p src_cell
-   * to @p dst_cell. Do so as well for
-   * all the children and their children
-   * of @p src_cell. This function is
-   * used for cells which are more
-   * refined on @p src_grid than on
-   * @p dst_grid; then all values of
-   * the hierarchy of cells and their
-   * children point to one cell on the
-   * @p dst_grid.
+   * Set the value of the key @p src_cell to @p dst_cell. Do so as well for
+   * all the children and their children of @p src_cell. This function is used
+   * for cells which are more refined on @p src_grid than on @p dst_grid; then
+   * all values of the hierarchy of cells and their children point to one cell
+   * on the @p dst_grid.
    */
   void set_entries_to_cell (const cell_iterator &src_cell,
                             const cell_iterator &dst_cell);
index a4efe94c9513ae35aaf9541e0afa143d7d7e1285..aac1e402bd2346757bb227980887ad5cc3195058 100644 (file)
@@ -32,18 +32,18 @@ template <int dim, int space_dim> class Triangulation;
 
 
 /**
- * We collect here some helper functions used in the
- * Manifold<dim,spacedim> classes.
+ * We collect here some helper functions used in the Manifold<dim,spacedim>
+ * classes.
  */
 namespace Manifolds
 {
   /**
-    * Given a general mesh iterator, construct a quadrature with the
-    * Laplace weights or with uniform weights according the parameter
-    * @p with_laplace, and with all relevant points of the iterator:
-    * vertices, line centers and/or face centers, which can be called
-    * when creating new vertices in the manifold routines.
-    */
+   * Given a general mesh iterator, construct a quadrature with the Laplace
+   * weights or with uniform weights according the parameter @p with_laplace,
+   * and with all relevant points of the iterator: vertices, line centers
+   * and/or face centers, which can be called when creating new vertices in
+   * the manifold routines.
+   */
   template <typename OBJECT>
   Quadrature<OBJECT::AccessorType::space_dimension>
   get_default_quadrature(const OBJECT &obj, bool with_laplace = false);
@@ -51,32 +51,30 @@ namespace Manifolds
 
 
 /**
- *   This class is used to represent a manifold to a triangulation.
- *   When a triangulation creates a new vertex on this manifold, it
- *   determines the new vertex' coordinates through the following
- *   function:
+ * This class is used to represent a manifold to a triangulation. When a
+ * triangulation creates a new vertex on this manifold, it determines the new
+ * vertex' coordinates through the following function:
  *
  *   @code
  *     ...
  *     Point<spacedim> new_vertex = manifold.get_new_point (quadrature);
  *     ...
  *   @endcode
- *   @p quadrature is a Quadrature<spacedim> object, which contains a
- *   collection of points in @p spacedim dimension, and a collection of
- *   weights (Note that unlike almost all other cases in the library,
- *   we here interpret the points in the quadrature object to be in
- *   real space, not on the reference cell.)
+ * @p quadrature is a Quadrature<spacedim> object, which contains a collection
+ * of points in @p spacedim dimension, and a collection of weights (Note that
+ * unlike almost all other cases in the library, we here interpret the points
+ * in the quadrature object to be in real space, not on the reference cell.)
  *
- *   Internaly, the get_new_point() function calls the
- *   project_to_manifold() function after computing the weighted
- *   average of the quadrature points. This allows end users to only
- *   overload project_to_manifold() for simple situations.
+ * Internaly, the get_new_point() function calls the project_to_manifold()
+ * function after computing the weighted average of the quadrature points.
+ * This allows end users to only overload project_to_manifold() for simple
+ * situations.
  *
- *   Should a finer control be necessary, then get_new_point() can be
- *   overloaded.
+ * Should a finer control be necessary, then get_new_point() can be
+ * overloaded.
  *
- *   FlatManifold is the specialization from which StraigthBoundary is
- *   derived, where the project_to_manifold() function is the identity.
+ * FlatManifold is the specialization from which StraigthBoundary is derived,
+ * where the project_to_manifold() function is the identity.
  *
  * @ingroup manifold
  * @author Luca Heltai, 2014
@@ -94,100 +92,91 @@ public:
   virtual ~Manifold ();
 
   /**
-   * Return the point which shall become the new vertex surrounded by
-   * the given points which make up the quadrature. We use a
-   * quadrature object, which should be filled with the surrounding
-   * points together with appropriate weights.
+   * Return the point which shall become the new vertex surrounded by the
+   * given points which make up the quadrature. We use a quadrature object,
+   * which should be filled with the surrounding points together with
+   * appropriate weights.
    *
    * In its default implementation it calls internally the function
-   * project_to_manifold. User classes can get away by simply
-   * implementing that method.
+   * project_to_manifold. User classes can get away by simply implementing
+   * that method.
    */
   virtual
   Point<spacedim>
   get_new_point(const Quadrature<spacedim> &quad) const;
 
   /**
-   * Given a point which lies close to the given manifold, it modifies
-   * it and projects it to manifold itself.
+   * Given a point which lies close to the given manifold, it modifies it and
+   * projects it to manifold itself.
    *
    * This class is used by the default implementation of the function
-   * get_new_point(). It should be made pure virtual, but for
-   * historical reason, derived classes like Boundary<dim, spacedim>
-   * do not implement it. The default behavior of this class, however,
-   * is to throw an exception when called.
+   * get_new_point(). It should be made pure virtual, but for historical
+   * reason, derived classes like Boundary<dim, spacedim> do not implement it.
+   * The default behavior of this class, however, is to throw an exception
+   * when called.
    *
-   * If your manifold is simple, you could implement this function
-   * only, and the default behavior should work out of the box.
+   * If your manifold is simple, you could implement this function only, and
+   * the default behavior should work out of the box.
    */
   virtual
   Point<spacedim> project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
                                        const Point<spacedim> &candidate) const;
 
   /**
-   * Backward compatibility interface.  Return the point which shall
-   * become the new middle vertex of the two children of a regular
-   * line. In 2D, this line is a line at the boundary, while in 3d, it
-   * is bounding a face at the boundary (the lines therefore is also
-   * on the boundary).
+   * Backward compatibility interface.  Return the point which shall become
+   * the new middle vertex of the two children of a regular line. In 2D, this
+   * line is a line at the boundary, while in 3d, it is bounding a face at the
+   * boundary (the lines therefore is also on the boundary).
    *
-   * The default implementation of this function
-   * passes its argument to the Manifolds::get_default_quadrature()
-   * function, and then calls the
-   * Manifold<dim,spacedim>::get_new_point() function. User derived
-   * classes can overload Manifold<dim,spacedim>::get_new_point() or
-   * Manifold<dim,spacedim>::project_to_surface(), which is called by
-   * the default implementation of
-   * Manifold<dim,spacedim>::get_new_point().
+   * The default implementation of this function passes its argument to the
+   * Manifolds::get_default_quadrature() function, and then calls the
+   * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+   * can overload Manifold<dim,spacedim>::get_new_point() or
+   * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+   * default implementation of Manifold<dim,spacedim>::get_new_point().
    */
   virtual
   Point<spacedim>
   get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
 
   /**
-   * Backward compatibility interface. Return the point which shall
-   * become the common point of the four children of a quad at the
-   * boundary in three or more spatial dimensions. This function
-   * therefore is only useful in at least three dimensions and should
-   * not be called for lower dimensions.
+   * Backward compatibility interface. Return the point which shall become the
+   * common point of the four children of a quad at the boundary in three or
+   * more spatial dimensions. This function therefore is only useful in at
+   * least three dimensions and should not be called for lower dimensions.
    *
    * This function is called after the four lines bounding the given @p quad
    * are refined, so you may want to use the information provided by
    * <tt>quad->line(i)->child(j)</tt>, <tt>i=0...3</tt>, <tt>j=0,1</tt>.
    *
-   * The default implementation of this function passes its argument
-   * to the Manifolds::get_default_quadrature() function, and then
-   * calls the Manifold<dim,spacedim>::get_new_point() function. User
-   * derived classes can overload
-   * Manifold<dim,spacedim>::get_new_point() or
-   * Manifold<dim,spacedim>::project_to_surface(), which is called by
-   * the default implementation of
-   * Manifold<dim,spacedim>::get_new_point().
+   * The default implementation of this function passes its argument to the
+   * Manifolds::get_default_quadrature() function, and then calls the
+   * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+   * can overload Manifold<dim,spacedim>::get_new_point() or
+   * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+   * default implementation of Manifold<dim,spacedim>::get_new_point().
    */
   virtual
   Point<spacedim>
   get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
 
   /**
-   * Backward compatibility interface.  Return the point which shall
-   * become the common point of the eight children of a hex in three
-   * or spatial dimensions. This function therefore is only useful in
-   * at least three dimensions and should not be called for lower
-   * dimensions.
+   * Backward compatibility interface.  Return the point which shall become
+   * the common point of the eight children of a hex in three or spatial
+   * dimensions. This function therefore is only useful in at least three
+   * dimensions and should not be called for lower dimensions.
    *
-   * This function is called after the all the bounding objects of the
-   * given @p hex are refined, so you may want to use the information
-   * provided by <tt>hex->quad(i)->line(j)->child(k)</tt>,
-   * <tt>i=0...5</tt>, <tt>j=0...3</tt>, <tt>k=0,1</tt>.
+   * This function is called after the all the bounding objects of the given
+   * @p hex are refined, so you may want to use the information provided by
+   * <tt>hex->quad(i)->line(j)->child(k)</tt>, <tt>i=0...5</tt>,
+   * <tt>j=0...3</tt>, <tt>k=0,1</tt>.
    *
-   * The default implementation of this function passes its argument
-   * to the Manifolds::get_default_quadrature() function, and then
-   * calls the Manifold<dim,spacedim>::get_new_point() function. User
-   * derived classes can overload
-   * Manifold<dim,spacedim>::get_new_point() or
-   * Manifold<dim,spacedim>::project_to_surface(), which is called by
-   * the default implementation of
-   * Manifold<dim,spacedim>::get_new_point().
+   * The default implementation of this function passes its argument to the
+   * Manifolds::get_default_quadrature() function, and then calls the
+   * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+   * can overload Manifold<dim,spacedim>::get_new_point() or
+   * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+   * default implementation of Manifold<dim,spacedim>::get_new_point().
    */
   virtual
   Point<spacedim>
@@ -196,10 +185,9 @@ public:
 
   /**
    * Backward compatibility interface. Depending on <tt>dim=2</tt> or
-   * <tt>dim=3</tt> this function calls the get_new_point_on_line or
-   * the get_new_point_on_quad function. It throws an exception for
-   * <tt>dim=1</tt>. This wrapper allows dimension independent
-   * programming.
+   * <tt>dim=3</tt> this function calls the get_new_point_on_line or the
+   * get_new_point_on_quad function. It throws an exception for
+   * <tt>dim=1</tt>. This wrapper allows dimension independent programming.
    */
   Point<spacedim>
   get_new_point_on_face (const typename Triangulation<dim,spacedim>::face_iterator &face) const;
@@ -208,9 +196,8 @@ public:
   /**
    * Backward compatibility interface.  Depending on <tt>dim=1</tt>,
    * <tt>dim=2</tt> or <tt>dim=3</tt> this function calls the
-   * get_new_point_on_line, get_new_point_on_quad or the
-   * get_new_point_on_hex function. This wrapper allows dimension
-   * independent programming.
+   * get_new_point_on_line, get_new_point_on_quad or the get_new_point_on_hex
+   * function. This wrapper allows dimension independent programming.
    */
   Point<spacedim>
   get_new_point_on_cell (const typename Triangulation<dim,spacedim>::cell_iterator &cell) const;
@@ -218,49 +205,45 @@ public:
 
 
 /**
- *   Specialization of Manifold<dim,spacedim>, which represent a
- *   possibly periodic Euclidean space of dimension @p dim embedded in
- *   the Euclidean space of @p spacedim dimensions. The main
- *   characteristic of this Manifold is the fact that the function
- *   FlatManifold<dim,spacedim>::project_to_manifold() is the identity
- *   function.
+ * Specialization of Manifold<dim,spacedim>, which represent a possibly
+ * periodic Euclidean space of dimension @p dim embedded in the Euclidean
+ * space of @p spacedim dimensions. The main characteristic of this Manifold
+ * is the fact that the function
+ * FlatManifold<dim,spacedim>::project_to_manifold() is the identity function.
  *
- *   @ingroup manifold
+ * @ingroup manifold
  *
- *   @author Luca Heltai, 2014
+ * @author Luca Heltai, 2014
  */
 template <int dim, int spacedim=dim>
 class FlatManifold: public Manifold<dim, spacedim>
 {
 public:
   /**
-   * Default constructor. The optional argument can be used to specify
-   * the periodicity of the spacedim-dimensional manifold (one period
-   * per direction). A periodicity value of zero means that along that
-   * direction there is no periodicity. By default no periodicity is
-   * assumed.
+   * Default constructor. The optional argument can be used to specify the
+   * periodicity of the spacedim-dimensional manifold (one period per
+   * direction). A periodicity value of zero means that along that direction
+   * there is no periodicity. By default no periodicity is assumed.
    *
-   * Periodicity affects the way a middle point is computed. It is
-   * assumed that if two points are more than half period distant,
-   * then the distance should be computed by crossing the periodicity
-   * boundary, i.e., the average is computed by adding a full period
-   * to the sum of the two. For example, if along direction 0 we have
-   * 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not
-   * pi, but 2*pi (or zero), since, on a periodic manifold, these two
-   * points are at distance 2*eps and not (2*pi-eps). Special cases
-   * are taken into account, to ensure that the behavior is always as
-   * expected. The third argument is used as a relative tolerance when
-   * computing distances.
+   * Periodicity affects the way a middle point is computed. It is assumed
+   * that if two points are more than half period distant, then the distance
+   * should be computed by crossing the periodicity boundary, i.e., the
+   * average is computed by adding a full period to the sum of the two. For
+   * example, if along direction 0 we have 2*pi periodicity, then the average
+   * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on a
+   * periodic manifold, these two points are at distance 2*eps and not (2*pi-
+   * eps). Special cases are taken into account, to ensure that the behavior
+   * is always as expected. The third argument is used as a relative tolerance
+   * when computing distances.
    *
    * Periodicity will be intended in the following way: the domain is
-   * considered to be the box contained in [Point<spacedim>(),
-   * periodicity) where the right extreme is excluded. If any of the
-   * components of this box has zero length, then no periodicity is
-   * computed in that direction. Whenever a function that tries to
-   * compute averages is called, an exception will be thrown if one of
-   * the points which you are using for the average lies outside the
-   * periodicity box. The return points are garanteed to lie in the
-   * perodicity box plus or minus tolerance*periodicity.norm().
+   * considered to be the box contained in [Point<spacedim>(), periodicity)
+   * where the right extreme is excluded. If any of the components of this box
+   * has zero length, then no periodicity is computed in that direction.
+   * Whenever a function that tries to compute averages is called, an
+   * exception will be thrown if one of the points which you are using for the
+   * average lies outside the periodicity box. The return points are garanteed
+   * to lie in the perodicity box plus or minus tolerance*periodicity.norm().
    */
   FlatManifold (const Point<spacedim> periodicity=Point<spacedim>(),
                 const double tolerance=1e-10);
@@ -268,53 +251,51 @@ public:
   /**
    * Let the new point be the average sum of surrounding vertices.
    *
-   * This particular implementation constructs the weighted average of
-   * the surrounding points, and then calls internally the function
-   * project_to_manifold. The reason why we do it this way, is to
-   * allow lazy programmers to implement only the project_to_manifold
-   * function for their own Manifold classes which are small (or
-   * trivial) perturbations of a flat manifold. This is the case
-   * whenever the coarse mesh is a decent approximation of the
-   * manifold geometry. In this case, the middle point of a cell is
-   * close to true middle point of the manifold, and a projection may
-   * suffice.
+   * This particular implementation constructs the weighted average of the
+   * surrounding points, and then calls internally the function
+   * project_to_manifold. The reason why we do it this way, is to allow lazy
+   * programmers to implement only the project_to_manifold function for their
+   * own Manifold classes which are small (or trivial) perturbations of a flat
+   * manifold. This is the case whenever the coarse mesh is a decent
+   * approximation of the manifold geometry. In this case, the middle point of
+   * a cell is close to true middle point of the manifold, and a projection
+   * may suffice.
    *
-   * For most simple geometries, it is possible to get reasonable
-   * results by deriving your own Manifold class from FlatManifold,
-   * and write a new interface only for the project_to_manifold
-   * function. You will have good approximations also with large
-   * deformations, as long as in the coarsest mesh size you are trying
-   * to refine, the middle point is not too far from the manifold mid
-   * point, i.e., as long as the coarse mesh size is small enough.
+   * For most simple geometries, it is possible to get reasonable results by
+   * deriving your own Manifold class from FlatManifold, and write a new
+   * interface only for the project_to_manifold function. You will have good
+   * approximations also with large deformations, as long as in the coarsest
+   * mesh size you are trying to refine, the middle point is not too far from
+   * the manifold mid point, i.e., as long as the coarse mesh size is small
+   * enough.
    */
   virtual Point<spacedim>
   get_new_point(const Quadrature<spacedim> &quad) const;
 
 
   /**
-   *  Project to FlatManifold. This is the identity function for flat,
-   *  Euclidean spaces. Note however that this function can be
-   *  overloaded by derived classes, which will then benefit from the
-   *  logic behind the get_new_point class which are often very
-   *  similar (if not identical) to the one implemented in this class.
+   * Project to FlatManifold. This is the identity function for flat,
+   * Euclidean spaces. Note however that this function can be overloaded by
+   * derived classes, which will then benefit from the logic behind the
+   * get_new_point class which are often very similar (if not identical) to
+   * the one implemented in this class.
    */
   virtual
   Point<spacedim> project_to_manifold (const std::vector<Point<spacedim> > &points,
                                        const Point<spacedim> &candidate) const;
 private:
   /**
-   * The periodicity of this Manifold. Periodicity affects the way a
-   * middle point is computed. It is assumed that if two points are
-   * more than half period distant, then the distance should be
-   * computed by crossing the periodicity boundary, i.e., the average
-   * is computed by adding a full period to the sum of the two. For
-   * example, if along direction 0 we have 2*pi periodicity, then the
-   * average of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero),
-   * since, on a periodic manifold, these two points are at distance
-   * 2*eps and not (2*pi-eps).
+   * The periodicity of this Manifold. Periodicity affects the way a middle
+   * point is computed. It is assumed that if two points are more than half
+   * period distant, then the distance should be computed by crossing the
+   * periodicity boundary, i.e., the average is computed by adding a full
+   * period to the sum of the two. For example, if along direction 0 we have
+   * 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not pi, but
+   * 2*pi (or zero), since, on a periodic manifold, these two points are at
+   * distance 2*eps and not (2*pi-eps).
    *
-   * A periodicity 0 along one direction means no periodicity. This is
-   * the default value for all directions.
+   * A periodicity 0 along one direction means no periodicity. This is the
+   * default value for all directions.
    */
   const Point<spacedim> periodicity;
 
@@ -324,115 +305,103 @@ private:
                  << ", " << arg3[arg4] << "), bailing out.");
 
   /**
-   * Relative tolerance. This tolerance is used to compute distances
-   * in double precision.
+   * Relative tolerance. This tolerance is used to compute distances in double
+   * precision.
    */
   const double tolerance;
 };
 
 
 /**
- *   This class describes mappings that can be expressed in terms
- *   of charts. Specifically, this class with its template arguments
- *   describes a chart of dimension chartdim, which is part of a
- *   Manifold<dim,spacedim> and is used in an object of type
- *   Triangulation<dim,spacedim>:  It specializes a Manifold of
- *   dimension chartdim embedded in a manifold of dimension spacedim,
- *   for which you have explicit pull_back() and push_forward()
- *   transformations. Its use is explained in great detail in step-53.
+ * This class describes mappings that can be expressed in terms of charts.
+ * Specifically, this class with its template arguments describes a chart of
+ * dimension chartdim, which is part of a Manifold<dim,spacedim> and is used
+ * in an object of type Triangulation<dim,spacedim>:  It specializes a
+ * Manifold of dimension chartdim embedded in a manifold of dimension
+ * spacedim, for which you have explicit pull_back() and push_forward()
+ * transformations. Its use is explained in great detail in step-53.
  *
- *   This is a helper class which is useful when you have an explicit
- *   map from an Euclidean space of dimension chartdim to an Euclidean
- *   space of dimension spacedim which represents your manifold, i.e.,
- *   when your manifold $\mathcal{M}$ can be represented by a map
- *   \f[
- *   F: \mathcal{B} \subset R^{\text{chartdim}} \mapsto \mathcal{M}
- *   \subset R^{\text{spacedim}}
- *   \f]
- *   (the push_forward() function)
- *   and that admits the inverse transformation
- *   \f[
- *   F^{-1}: \mathcal{M}
- *   \subset R^{\text{spacedim}} \mapsto
- *   \mathcal{B} \subset R^{\text{chartdim}}
- *   \f]
- *   (the pull_back() function).
+ * This is a helper class which is useful when you have an explicit map from
+ * an Euclidean space of dimension chartdim to an Euclidean space of dimension
+ * spacedim which represents your manifold, i.e., when your manifold
+ * $\mathcal{M}$ can be represented by a map \f[ F: \mathcal{B} \subset
+ * R^{\text{chartdim}} \mapsto \mathcal{M} \subset R^{\text{spacedim}} \f]
+ * (the push_forward() function) and that admits the inverse transformation
+ * \f[ F^{-1}: \mathcal{M} \subset R^{\text{spacedim}} \mapsto \mathcal{B}
+ * \subset R^{\text{chartdim}} \f] (the pull_back() function).
  *
- *   The get_new_point() function of the ChartManifold class is
- *   implemented by calling the pull_back() method for all
- *   #surrounding_points, computing their weighted average in the
- *   chartdim Euclidean space, and calling the push_forward() method
- *   with the resulting point, i.e., \f[ p^{\text{new}} = F(\sum_i w_i
- *   F^{-1}(p_i)).  \f]
+ * The get_new_point() function of the ChartManifold class is implemented by
+ * calling the pull_back() method for all #surrounding_points, computing their
+ * weighted average in the chartdim Euclidean space, and calling the
+ * push_forward() method with the resulting point, i.e., \f[ p^{\text{new}} =
+ * F(\sum_i w_i F^{-1}(p_i)).  \f]
  *
- *   Derived classes are required to implement the push_forward() and
- *   the pull_back() methods. All other functions required by mappings
- *   will then be provided by this class.
+ * Derived classes are required to implement the push_forward() and the
+ * pull_back() methods. All other functions required by mappings will then be
+ * provided by this class.
  *
- *   The dimension arguments #chartdim, #dim and #spacedim must
- *   satisfy the following relationships:
+ * The dimension arguments #chartdim, #dim and #spacedim must satisfy the
+ * following relationships:
  *   @code
  *      dim <= spacedim
  *      chartdim <= spacedim
  *   @endcode
- *   However, there is no a priori relationship between #dim and
- *   #chartdim. For example, if you want to describe a mapping
- *   for an edge (a 1d object) in a 2d triangulation embedded in
- *   3d space, you could do so by parameterizing it via a line
+ * However, there is no a priori relationship between #dim and #chartdim. For
+ * example, if you want to describe a mapping for an edge (a 1d object) in a
+ * 2d triangulation embedded in 3d space, you could do so by parameterizing it
+ * via a line
  *   @f[
  *      F: [0,1] \rightarrow {\mathbb R}^3
  *   @f]
- *   in which case #chartdim is 1. On the other hand, there is
- *   no reason why one can't describe this as a mapping
+ * in which case #chartdim is 1. On the other hand, there is no reason why one
+ * can't describe this as a mapping
  *   @f[
  *      F: {\mathbb R}^3 \rightarrow {\mathbb R}^3
  *   @f]
- *   in such a way that the line $[0,1]\times \{0\}\times \{0\}$ happens to be
- *   mapped onto the edge in question. Here, #chartdim is 3. This may seem
- *   cumbersome but satisfies the requirements of an invertible function $F$
- *   just fine as long as it is possible to get from the edge to the pull-back
- *   space and then back again. Finally, given that we are dealing with a 2d
- *   triangulation in 3d, one will often have a mapping from, say, the 2d unit
- *   square or unit disk to the domain in 3d space, and the edge in question
- *   may simply be the mapped edge of the unit domain in 2d space. In
- *   this case, #chartdim is 2.
+ * in such a way that the line $[0,1]\times \{0\}\times \{0\}$ happens to be
+ * mapped onto the edge in question. Here, #chartdim is 3. This may seem
+ * cumbersome but satisfies the requirements of an invertible function $F$
+ * just fine as long as it is possible to get from the edge to the pull-back
+ * space and then back again. Finally, given that we are dealing with a 2d
+ * triangulation in 3d, one will often have a mapping from, say, the 2d unit
+ * square or unit disk to the domain in 3d space, and the edge in question may
+ * simply be the mapped edge of the unit domain in 2d space. In this case,
+ * #chartdim is 2.
  *
- *   @ingroup manifold
+ * @ingroup manifold
  *
- *   @author Luca Heltai, 2013, 2014
+ * @author Luca Heltai, 2013, 2014
  */
 template <int dim, int spacedim=dim, int chartdim=dim>
 class ChartManifold: public Manifold<dim,spacedim>
 {
 public:
   /**
-   * Constructor. The optional argument can be used to specify the
-   * periodicity of the chartdim-dimensional manifold (one period per
-   * direction). A periodicity value of zero means that along that
-   * direction there is no periodicity. By default no periodicity is
-   * assumed.
+   * Constructor. The optional argument can be used to specify the periodicity
+   * of the chartdim-dimensional manifold (one period per direction). A
+   * periodicity value of zero means that along that direction there is no
+   * periodicity. By default no periodicity is assumed.
    *
-   * Periodicity affects the way a middle point is computed. It is
-   * assumed that if two points are more than half period distant,
-   * then the distance should be computed by crossing the periodicity
-   * boundary, i.e., then the average is computed by adding a full
-   * period to the sum of the two. For example, if along direction 0
-   * we have 2*pi periodicity, then the average of (2*pi-eps) and
-   * (eps) is not pi, but 2*pi (or zero), since, on the manifold,
-   * these two points are at distance 2*eps and not (2*pi-eps)
+   * Periodicity affects the way a middle point is computed. It is assumed
+   * that if two points are more than half period distant, then the distance
+   * should be computed by crossing the periodicity boundary, i.e., then the
+   * average is computed by adding a full period to the sum of the two. For
+   * example, if along direction 0 we have 2*pi periodicity, then the average
+   * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on the
+   * manifold, these two points are at distance 2*eps and not (2*pi-eps)
    */
   ChartManifold(const Point<chartdim> periodicity=Point<chartdim>());
 
   /**
-   * Destructor. Does nothing here, but needs to be declared to make
-   * it virtual.
+   * Destructor. Does nothing here, but needs to be declared to make it
+   * virtual.
    */
   virtual ~ChartManifold ();
 
 
   /**
-   * Refer to the general documentation of this class and the
-   * documentation of the base class for more information.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class for more information.
    */
   virtual Point<spacedim>
   get_new_point(const Quadrature<spacedim> &quad) const;
@@ -441,27 +410,24 @@ public:
    * Pull back the given point in spacedim to the Euclidean chartdim
    * dimensional space.
    *
-   * Refer to the general documentation of this class for more
-   * information.
+   * Refer to the general documentation of this class for more information.
    */
   virtual Point<chartdim>
   pull_back(const Point<spacedim> &space_point) const = 0;
 
   /**
-   * Given a point in the chartdim dimensional Euclidean space, this
-   * method returns a point on the manifold embedded in the spacedim
-   * Euclidean space.
+   * Given a point in the chartdim dimensional Euclidean space, this method
+   * returns a point on the manifold embedded in the spacedim Euclidean space.
    *
-   * Refer to the general documentation of this class for more
-   * information.
+   * Refer to the general documentation of this class for more information.
    */
   virtual Point<spacedim>
   push_forward(const Point<chartdim> &chart_point) const = 0;
 
 private:
   /**
-   * The sub_manifold object is used to compute the average of the
-   * points in the chart coordinates system.
+   * The sub_manifold object is used to compute the average of the points in
+   * the chart coordinates system.
    */
   const FlatManifold<dim,chartdim> sub_manifold;
 };
index e4fc1a9aa26b0a7cb78ca9ecda7fa869ac63830d..6d00bca7a348fd226ee6b38320e38d01bafcb421 100644 (file)
@@ -28,26 +28,24 @@ DEAL_II_NAMESPACE_OPEN
  * Manifold description for a spherical space coordinate system.
  *
  * You can use this Manifold object to describe any sphere, circle,
- * hypersphere or hyperdisc in two or three dimensions, both as a
- * co-dimension one manifold descriptor or as co-dimension zero
- * manifold descriptor.
+ * hypersphere or hyperdisc in two or three dimensions, both as a co-dimension
+ * one manifold descriptor or as co-dimension zero manifold descriptor.
  *
- * The two template arguments match the meaning of the two template
- * arguments in Triangulation<dim, spacedim>, however this Manifold
- * can be used to describe both thin and thick objects, and the
- * behavior is identical when dim <= spacedim, i.e., the functionality
- * of SphericalManifold<2,3> is identical to SphericalManifold<3,3>.
+ * The two template arguments match the meaning of the two template arguments
+ * in Triangulation<dim, spacedim>, however this Manifold can be used to
+ * describe both thin and thick objects, and the behavior is identical when
+ * dim <= spacedim, i.e., the functionality of SphericalManifold<2,3> is
+ * identical to SphericalManifold<3,3>.
  *
- * The two dimensional implementation of this class works by
- * transforming points to spherical coordinates, taking the average in
- * that coordinate system, and then transforming back the point to
- * Cartesian coordinates. For the three dimensional case, we use a
- * simpler approach: we take the average of the norm of the points,
- * and use this value to shift the average point along the radial
- * direction. In order for this manifold to work correctly, it cannot
- * be attached to cells containing the center of the coordinate
- * system. This point is a singular point of the coordinate
- * transformation, and there taking averages does not make any sense.
+ * The two dimensional implementation of this class works by transforming
+ * points to spherical coordinates, taking the average in that coordinate
+ * system, and then transforming back the point to Cartesian coordinates. For
+ * the three dimensional case, we use a simpler approach: we take the average
+ * of the norm of the points, and use this value to shift the average point
+ * along the radial direction. In order for this manifold to work correctly,
+ * it cannot be attached to cells containing the center of the coordinate
+ * system. This point is a singular point of the coordinate transformation,
+ * and there taking averages does not make any sense.
  *
  * @ingroup manifold
  *
@@ -58,28 +56,27 @@ class SphericalManifold : public ChartManifold<dim, spacedim, spacedim>
 {
 public:
   /**
-   * The Constructor takes the center of the spherical coordinates
-   * system. This class uses the pull_back and push_forward mechanism
-   * to transform from Cartesian to spherical coordinate systems,
-   * taking into account the periodicity of base Manifold in two
-   * dimensions, while in three dimensions it takes the middle point,
-   * and project it along the radius using the average radius of the
-   * surrounding points.
+   * The Constructor takes the center of the spherical coordinates system.
+   * This class uses the pull_back and push_forward mechanism to transform
+   * from Cartesian to spherical coordinate systems, taking into account the
+   * periodicity of base Manifold in two dimensions, while in three dimensions
+   * it takes the middle point, and project it along the radius using the
+   * average radius of the surrounding points.
    */
   SphericalManifold(const Point<spacedim> center = Point<spacedim>());
 
   /**
-   * Pull back the given point from the Euclidean space. Will return
-   * the polar coordinates associated with the point @p
-   * space_point. Only used when spacedim = 2.
+   * Pull back the given point from the Euclidean space. Will return the polar
+   * coordinates associated with the point @p space_point. Only used when
+   * spacedim = 2.
    */
   virtual Point<spacedim>
   pull_back(const Point<spacedim> &space_point) const;
 
   /**
-   * Given a point in the spherical coordinate system, this method
-   * returns the Euclidean coordinates associated to the polar
-   * coordinates @p chart_point. Only used when spacedim = 3.
+   * Given a point in the spherical coordinate system, this method returns the
+   * Euclidean coordinates associated to the polar coordinates @p chart_point.
+   * Only used when spacedim = 3.
    */
   virtual Point<spacedim>
   push_forward(const Point<spacedim> &chart_point) const;
@@ -88,8 +85,8 @@ public:
    * Let the new point be the average sum of surrounding vertices.
    *
    * In the two dimensional implementation, we use the pull_back and
-   * push_forward mechanism. For three dimensions, this does not work
-   * well, so we overload the get_new_point function directly.
+   * push_forward mechanism. For three dimensions, this does not work well, so
+   * we overload the get_new_point function directly.
    */
   virtual Point<spacedim>
   get_new_point(const Quadrature<spacedim> &quad) const;
@@ -100,25 +97,24 @@ public:
   const Point<spacedim> center;
 private:
 
-  /** Helper function which returns the periodicity associated with
-      this coordinate system, according to dim, chartdim, and
-      spacedim. */
+  /**
+   * Helper function which returns the periodicity associated with this
+   * coordinate system, according to dim, chartdim, and spacedim.
+   */
   static Point<spacedim> get_periodicity();
 };
 
 
 /**
  * Cylindrical Manifold description.  In three dimensions, points are
- * transformed using a cylindrical coordinate system along the
- * <tt>x-</tt>, <tt>y-</tt> or <tt>z</tt>-axis (when using the first
- * constructor of this class), or an arbitrarily oriented cylinder
- * described by the direction of its axis and a point located on the
- * axis.
+ * transformed using a cylindrical coordinate system along the <tt>x-</tt>,
+ * <tt>y-</tt> or <tt>z</tt>-axis (when using the first constructor of this
+ * class), or an arbitrarily oriented cylinder described by the direction of
+ * its axis and a point located on the axis.
  *
- * This class was developed to be used in conjunction with the @p
- * cylinder or @p cylinder_shell functions of GridGenerator. This
- * function will throw an exception whenever spacedim is not equal to
- * three.
+ * This class was developed to be used in conjunction with the @p cylinder or
+ * @p cylinder_shell functions of GridGenerator. This function will throw an
+ * exception whenever spacedim is not equal to three.
  *
  * @ingroup manifold
  *
@@ -129,32 +125,29 @@ class CylindricalManifold : public Manifold<dim,spacedim>
 {
 public:
   /**
-   * Constructor. Using default values for the constructor arguments
-   * yields a cylinder along the x-axis (<tt>axis=0</tt>). Choose
-   * <tt>axis=1</tt> or <tt>axis=2</tt> for a tube along the y- or
-   * z-axis, respectively. The tolerance value is used to determine
-   * if a point is on the axis.
+   * Constructor. Using default values for the constructor arguments yields a
+   * cylinder along the x-axis (<tt>axis=0</tt>). Choose <tt>axis=1</tt> or
+   * <tt>axis=2</tt> for a tube along the y- or z-axis, respectively. The
+   * tolerance value is used to determine if a point is on the axis.
    */
   CylindricalManifold (const unsigned int axis = 0,
                        const double tolerance = 1e-10);
 
   /**
-   * Constructor. If constructed with this constructor, the manifold
-   * described is a cylinder with an axis that points in direction
-   * #direction and goes through the given #point_on_axis. The
-   * direction may be arbitrarily scaled, and the given point may be
-   * any point on the axis. The tolerance value is used to determine
-   * if a point is on the axis.
+   * Constructor. If constructed with this constructor, the manifold described
+   * is a cylinder with an axis that points in direction #direction and goes
+   * through the given #point_on_axis. The direction may be arbitrarily
+   * scaled, and the given point may be any point on the axis. The tolerance
+   * value is used to determine if a point is on the axis.
    */
   CylindricalManifold (const Point<spacedim> &direction,
                        const Point<spacedim> &point_on_axis,
                        const double tolerance = 1e-10);
 
   /**
-    * Compute new points on the CylindricalManifold. See the documentation
-    * of the base class for a detailed description of what this
-    * function does.
-    */
+   * Compute new points on the CylindricalManifold. See the documentation of
+   * the base class for a detailed description of what this function does.
+   */
   virtual Point<spacedim>
   get_new_point(const Quadrature<spacedim> &quad) const;
 
@@ -187,13 +180,12 @@ private:
  * Function<spacedim> and Function<chartdim> objects describing the
  * push_forward() and pull_back() functions.
  *
- * You can use this Manifold object to describe any arbitray shape
- * domain, as long as you can express it in terms of an invertible
- * map, for which you provide both the forward expression, and the
- * inverse expression.
+ * You can use this Manifold object to describe any arbitray shape domain, as
+ * long as you can express it in terms of an invertible map, for which you
+ * provide both the forward expression, and the inverse expression.
  *
- * In debug mode, a check is performed to verify that the
- * tranformations are actually one the inverse of the other.
+ * In debug mode, a check is performed to verify that the tranformations are
+ * actually one the inverse of the other.
  *
  * @ingroup manifold
  *
@@ -204,13 +196,13 @@ class FunctionManifold : public ChartManifold<dim, spacedim, chartdim>
 {
 public:
   /**
-   * Explicit functions constructor. Takes a push_forward function of
-   * spacedim components, and a pull_back function of chartdim
-   * components. See the documentation of the base class ChartManifold
-   * for the meaning of the optional #periodicity argument.
+   * Explicit functions constructor. Takes a push_forward function of spacedim
+   * components, and a pull_back function of chartdim components. See the
+   * documentation of the base class ChartManifold for the meaning of the
+   * optional #periodicity argument.
    *
-   * The tolerance argument is used in debug mode to actually check
-   * that the two functions are one the inverse of the other.
+   * The tolerance argument is used in debug mode to actually check that the
+   * two functions are one the inverse of the other.
    */
   FunctionManifold(const Function<chartdim> &push_forward_function,
                    const Function<spacedim> &pull_back_function,
@@ -218,19 +210,18 @@ public:
                    const double tolerance=1e-10);
 
   /**
-   * Expressions constructor. Takes the expressions of the
-   * push_forward function of spacedim components, and of the
-   * pull_back function of chartdim components. See the documentation
-   * of the base class ChartManifold for the meaning of the optional
-   * #periodicity argument.
+   * Expressions constructor. Takes the expressions of the push_forward
+   * function of spacedim components, and of the pull_back function of
+   * chartdim components. See the documentation of the base class
+   * ChartManifold for the meaning of the optional #periodicity argument.
    *
-   * The strings should be the readable by the default constructor of
-   * the FunctionParser classes. You can specify custom variable
-   * expressions with the last two optional arguments. If you don't,
-   * the default names are used, i.e., "x,y,z".
+   * The strings should be the readable by the default constructor of the
+   * FunctionParser classes. You can specify custom variable expressions with
+   * the last two optional arguments. If you don't, the default names are
+   * used, i.e., "x,y,z".
    *
-   * The tolerance argument is used in debug mode to actually check
-   * that the two functions are one the inverse of the other.
+   * The tolerance argument is used in debug mode to actually check that the
+   * two functions are one the inverse of the other.
    */
   FunctionManifold(const std::string push_forward_expression,
                    const std::string pull_back_expression,
@@ -247,16 +238,16 @@ public:
 
   /**
    * Given a point in the chartdim coordinate system, uses the
-   * push_forward_function to compute the push_forward of points in
-   * #chardim space dimensions to #spacedim space dimensions.
+   * push_forward_function to compute the push_forward of points in #chardim
+   * space dimensions to #spacedim space dimensions.
    */
   virtual Point<spacedim>
   push_forward(const Point<chartdim> &chart_point) const;
 
   /**
    * Given a point in the spacedim coordinate system, uses the
-   * pull_back_function to compute the pull_back of points in
-   * #spacedim space dimensions to #chartdim space dimensions.
+   * pull_back_function to compute the pull_back of points in #spacedim space
+   * dimensions to #chartdim space dimensions.
    */
   virtual Point<chartdim>
   pull_back(const Point<spacedim> &space_point) const;
@@ -280,19 +271,18 @@ private:
                FunctionManifold<dim,spacedim,chartdim> > pull_back_function;
 
   /**
-   * Relative tolerance. In debug mode, we check that the two
-   * functions provided at construction time are actually one the
-   * inverse of the other. This value is used as relative tolerance in
-   * this check.
+   * Relative tolerance. In debug mode, we check that the two functions
+   * provided at construction time are actually one the inverse of the other.
+   * This value is used as relative tolerance in this check.
    */
   const double tolerance;
 
   /**
-   * Check ownership of the smart pointers. Indicates whether this
-   * class is the owner of the objects pointed to by the previous two
-   * member variables.  This value is set in the constructor of the
-   * class. If #true, then the destructor will delete the function
-   * objects pointed to be the two pointers.
+   * Check ownership of the smart pointers. Indicates whether this class is
+   * the owner of the objects pointed to by the previous two member variables.
+   * This value is set in the constructor of the class. If #true, then the
+   * destructor will delete the function objects pointed to be the two
+   * pointers.
    */
   const bool owns_pointers;
 };
index 7b428638b6b3890e1607064fa4f17137a744c3df..0c85fe3962baf89b1d104f7fcf3f82c54549725c 100644 (file)
@@ -26,38 +26,37 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * This class handles the history of a triangulation and can rebuild it after
- * it was deleted some time before. Its main purpose is support for
- * time-dependent problems where one frequently deletes a triangulation due
- * to memory pressure and later wants to rebuild it; this class has all the
- * information to rebuild it exactly as it was before including the mapping
- * of cell numbers to the geometrical cells.
+ * it was deleted some time before. Its main purpose is support for time-
+ * dependent problems where one frequently deletes a triangulation due to
+ * memory pressure and later wants to rebuild it; this class has all the
+ * information to rebuild it exactly as it was before including the mapping of
+ * cell numbers to the geometrical cells.
  *
- * Basically, this is a drop-in replacement for the triangulation. Since it
- * is derived from the Triangulation class, it shares all the
- * functionality, but it overrides some virtual functions and adds some
- * functions, too. The main change to the base class is that it overrides
- * the @p execute_coarsening_and_refinement function, where the new version
- * first stores all refinement and coarsening flags and only then calls the
- * respective function of the base class. The stored flags may later be
- * used to restore the grid just as it was before. Some other functions
- * have been extended slightly as well, see their documentation for more
- * information.
+ * Basically, this is a drop-in replacement for the triangulation. Since it is
+ * derived from the Triangulation class, it shares all the functionality, but
+ * it overrides some virtual functions and adds some functions, too. The main
+ * change to the base class is that it overrides the @p
+ * execute_coarsening_and_refinement function, where the new version first
+ * stores all refinement and coarsening flags and only then calls the
+ * respective function of the base class. The stored flags may later be used
+ * to restore the grid just as it was before. Some other functions have been
+ * extended slightly as well, see their documentation for more information.
  *
  * We note that since the triangulation is created in exactly the same state
  * as it was before, other objects working on it should result in the same
  * state as well. This holds in particular for the DoFHandler object, which
  * will assign the same degrees of freedom to the original cells and the ones
- * after reconstruction of the triangulation. You can therefore safely use data
- * vectors computed on the original grid on the reconstructed grid as well.
+ * after reconstruction of the triangulation. You can therefore safely use
+ * data vectors computed on the original grid on the reconstructed grid as
+ * well.
  *
  *
- * <h3>Usage</h3>
- * You can use objects of this class almost in the same way as objects of the
- * Triangulation class. One of the few differences is that you can only
- * construct such an object by giving a coarse grid to the constructor. The
- * coarse grid will be used to base the triangulation on, and therefore the
- * lifetime of the coarse grid has to be longer than the lifetime of the
- * object of this class.
+ * <h3>Usage</h3> You can use objects of this class almost in the same way as
+ * objects of the Triangulation class. One of the few differences is that you
+ * can only construct such an object by giving a coarse grid to the
+ * constructor. The coarse grid will be used to base the triangulation on, and
+ * therefore the lifetime of the coarse grid has to be longer than the
+ * lifetime of the object of this class.
  *
  * Basically, usage looks like this:
  * @code
@@ -91,14 +90,14 @@ DEAL_II_NAMESPACE_OPEN
  *     };
  * @endcode
  *
- * Note that initially, the PersistentTriangulation object does not
- * constitute a triangulation; it only becomes one after @p restore is first
- * called. Note also that the @p execute_coarsening_and_refinement stores
- * all necessary flags for later reconstruction using the @p restore function.
- * Triangulation::clear() resets the underlying triangulation to a
- * virgin state, but does not affect the stored refinement flags needed for
- * later reconstruction and does also not touch the coarse grid which is
- * used within restore().
+ * Note that initially, the PersistentTriangulation object does not constitute
+ * a triangulation; it only becomes one after @p restore is first called. Note
+ * also that the @p execute_coarsening_and_refinement stores all necessary
+ * flags for later reconstruction using the @p restore function.
+ * Triangulation::clear() resets the underlying triangulation to a virgin
+ * state, but does not affect the stored refinement flags needed for later
+ * reconstruction and does also not touch the coarse grid which is used within
+ * restore().
  *
  * @ingroup grid
  * @author Wolfgang Bangerth, 1999
@@ -108,35 +107,26 @@ class PersistentTriangulation : public Triangulation<dim, spacedim>
 {
 public:
   /**
-   * Make the dimension available
-   * in function templates.
+   * Make the dimension available in function templates.
    */
   static const unsigned int dimension = dim;
   static const unsigned int spacedimension = spacedim;
 
   /**
-   * Build up the triangulation from the
-   * coarse grid in future. Copy smoothing
-   * flags, etc from that grid as well.
-   * Note that the initial state of the
-   * triangulation is empty, until
-   * @p restore_grid is called for the
-   * first time.
+   * Build up the triangulation from the coarse grid in future. Copy smoothing
+   * flags, etc from that grid as well. Note that the initial state of the
+   * triangulation is empty, until @p restore_grid is called for the first
+   * time.
    *
-   * The coarse grid must persist until
-   * the end of this object, since it will
-   * be used upon reconstruction of the
-   * grid.
+   * The coarse grid must persist until the end of this object, since it will
+   * be used upon reconstruction of the grid.
    */
   PersistentTriangulation (const Triangulation<dim, spacedim> &coarse_grid);
 
   /**
-   * Copy constructor. This operation
-   * is only allowed, if the triangulation
-   * underlying the object to be copied
-   * is presently empty. Refinement flags
-   * as well as the pointer to the
-   * coarse grid are copied, however.
+   * Copy constructor. This operation is only allowed, if the triangulation
+   * underlying the object to be copied is presently empty. Refinement flags
+   * as well as the pointer to the coarse grid are copied, however.
    */
   PersistentTriangulation (const PersistentTriangulation<dim, spacedim> &old_tria);
 
@@ -146,84 +136,56 @@ public:
   virtual ~PersistentTriangulation ();
 
   /**
-   * Overloaded version of the same
-   * function in the base class which
-   * stores the refinement and coarsening
-   * flags for later reconstruction of the
-   * triangulation and after that calls
-   * the respective function of the
-   * base class.
+   * Overloaded version of the same function in the base class which stores
+   * the refinement and coarsening flags for later reconstruction of the
+   * triangulation and after that calls the respective function of the base
+   * class.
    */
   virtual void execute_coarsening_and_refinement ();
 
   /**
-   * Restore the grid according to
-   * the saved data. For this, the
-   * coarse grid is copied and the
-   * grid is stepwise rebuilt using
-   * the saved flags.
+   * Restore the grid according to the saved data. For this, the coarse grid
+   * is copied and the grid is stepwise rebuilt using the saved flags.
    *
-   * Note that this function will result in
-   * an error if the underlying
-   * triangulation is not empty, i.e. it
-   * will only succeed if this object is
-   * newly created or the <tt>clear()</tt>
-   * function of the base class was called
-   * on it before.
+   * Note that this function will result in an error if the underlying
+   * triangulation is not empty, i.e. it will only succeed if this object is
+   * newly created or the <tt>clear()</tt> function of the base class was
+   * called on it before.
    *
-   * Repeatedly calls the
-   * <tt>restore(unsigned int)</tt>
-   * function in a loop over all
-   * refinement steps.
+   * Repeatedly calls the <tt>restore(unsigned int)</tt> function in a loop
+   * over all refinement steps.
    */
   void restore ();
 
   /**
-   * Differential restore. Performs
-   * the @p step_noth local
-   * refinement and coarsening step.
-   * Step 0 stands for the copying
-   * of the coarse grid.
+   * Differential restore. Performs the @p step_noth local refinement and
+   * coarsening step. Step 0 stands for the copying of the coarse grid.
    *
-   * This function will only
-   * succeed if the triangulation
-   * is in just the state it were
-   * if restore would have been
-   * called from
+   * This function will only succeed if the triangulation is in just the state
+   * it were if restore would have been called from
    * <tt>step=0...step_no-1</tt> before.
    */
   void restore (const unsigned int step_no);
 
   /**
-   * Returns the number of
-   * refinement and coarsening
-   * steps. This is given by the
-   * size of the @p refine_flags
-   * vector.
+   * Returns the number of refinement and coarsening steps. This is given by
+   * the size of the @p refine_flags vector.
    */
   unsigned int n_refinement_steps () const;
 
   /**
-   * Overload this function to use
-   * @p tria as a new coarse grid. The
-   * present triangulation and all
-   * refinement and coarsening flags
-   * storing its history are deleted,
-   * and the state of the underlying
-   * triangulation is reset to be
-   * empty, until @p restore_grid is
-   * called the next time.
+   * Overload this function to use @p tria as a new coarse grid. The present
+   * triangulation and all refinement and coarsening flags storing its history
+   * are deleted, and the state of the underlying triangulation is reset to be
+   * empty, until @p restore_grid is called the next time.
    *
-   * The coarse grid must persist until
-   * the end of this object, since it will
-   * be used upon reconstruction of the
-   * grid.
+   * The coarse grid must persist until the end of this object, since it will
+   * be used upon reconstruction of the grid.
    */
   virtual void copy_triangulation (const Triangulation<dim, spacedim> &tria);
 
   /**
-   * Throw an error, since this function
-   * is not useful in the context of this
+   * Throw an error, since this function is not useful in the context of this
    * class.
    */
   virtual void create_triangulation (const std::vector<Point<spacedim> >    &vertices,
@@ -231,11 +193,9 @@ public:
                                      const SubCellData                 &subcelldata);
 
   /**
-   * An overload of the respective function
-   * of the base class.
+   * An overload of the respective function of the base class.
    *
-   * Throw an error, since this function
-   * is not useful in the context of this
+   * Throw an error, since this function is not useful in the context of this
    * class.
    */
   virtual void create_triangulation_compatibility (
@@ -244,31 +204,25 @@ public:
     const SubCellData                 &subcelldata);
 
   /**
-   * Writes all refine and coarsen
-   * flags to the ostream @p out.
+   * Writes all refine and coarsen flags to the ostream @p out.
    */
   virtual void write_flags(std::ostream &out) const;
 
   /**
-   * Reads all refine and coarsen flags
-   * that previously were written by
-   * <tt>write_flags(...)</tt>. This is especially
-   * useful for rebuilding the triangulation
-   * after the end or breakdown of a program
-   * and its restart.
+   * Reads all refine and coarsen flags that previously were written by
+   * <tt>write_flags(...)</tt>. This is especially useful for rebuilding the
+   * triangulation after the end or breakdown of a program and its restart.
    */
   virtual void read_flags(std::istream &in);
 
   /**
-   * Clears all flags. Retains the
-   * same coarse grid.
+   * Clears all flags. Retains the same coarse grid.
    */
   virtual void clear_flags();
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   virtual std::size_t memory_consumption () const;
 
@@ -283,17 +237,14 @@ public:
 
 private:
   /**
-   * This grid shall be used as coarse
-   * grid.
+   * This grid shall be used as coarse grid.
    */
   SmartPointer<const Triangulation<dim,spacedim>,PersistentTriangulation<dim,spacedim> > coarse_grid;
 
   /**
-   * Vectors holding the refinement and
-   * coarsening flags of the different
-   * sweeps on this time level. The
-   * vectors therefore hold the history
-   * of the grid.
+   * Vectors holding the refinement and coarsening flags of the different
+   * sweeps on this time level. The vectors therefore hold the history of the
+   * grid.
    */
   std::vector<std::vector<bool> >   refine_flags;
 
index 2f0a5ed09ff0ee4b0b58adcb372c21efb8e6e12b..0ec6080db4fbf2a844a21a999f533bd5cd82ab91 100644 (file)
@@ -58,10 +58,8 @@ namespace internal
     template <typename> class TriaObjects;
 
     /**
-     * Forward declaration of a class into
-     * which we put much of the
-     * implementation of the Triangulation
-     * class. See the .cc file for more
+     * Forward declaration of a class into which we put much of the
+     * implementation of the Triangulation class. See the .cc file for more
      * information.
      */
     struct Implementation;
@@ -85,17 +83,16 @@ template <int dim, int spacedim> class MGDoFHandler;
 
 /**
  * A structure to describe individual cells and passed as argument to
- * Triangulation::create_triangulation(). It
- * contains all data needed to construct a cell, namely the indices of the
- * vertices, the material or boundary indicator (depending on whether it
- * represents a cell or a face), and a manifold id to describe the manifold
- * this object belongs to.
+ * Triangulation::create_triangulation(). It contains all data needed to
+ * construct a cell, namely the indices of the vertices, the material or
+ * boundary indicator (depending on whether it represents a cell or a face),
+ * and a manifold id to describe the manifold this object belongs to.
  *
  * This structure is also used to represent data for faces and edge as part of
  * the SubCellData class. In that case the #vertices array needs to represent
  * the vertices of a face or edge of a cell listed in the argument to
- * Triangulation::create_triangulation() that denotes the faces. It can be used
- * to attach boundary indicators to faces.
+ * Triangulation::create_triangulation() that denotes the faces. It can be
+ * used to attach boundary indicators to faces.
  *
  * @ingroup grid
  */
@@ -103,22 +100,17 @@ template <int structdim>
 struct CellData
 {
   /**
-   * Indices of the vertices of
-   * this cell.
+   * Indices of the vertices of this cell.
    */
   unsigned int vertices[GeometryInfo<structdim>::vertices_per_cell];
 
   /**
-   * Material or boundary indicator
-   * of this cell. The material_id
-   * may be used to denote
-   * different coefficients, etc.
+   * Material or boundary indicator of this cell. The material_id may be used
+   * to denote different coefficients, etc.
    *
-   * Note that if this object is part of a
-   * SubCellData object, then it represents
-   * a face or edge of a cell. In this case
-   * one should use the field boundary_id
-   * instead of material_id.
+   * Note that if this object is part of a SubCellData object, then it
+   * represents a face or edge of a cell. In this case one should use the
+   * field boundary_id instead of material_id.
    */
   union
   {
@@ -127,18 +119,18 @@ struct CellData
   };
 
   /**
-   * Manifold identificator of this object. This identificator should
-   * be used to identify the manifold to which this object belongs,
-   * and from which this object will collect information on how to add
-   * points upon refinement.
+   * Manifold identificator of this object. This identificator should be used
+   * to identify the manifold to which this object belongs, and from which
+   * this object will collect information on how to add points upon
+   * refinement.
    */
   types::manifold_id manifold_id;
 
   /**
-   * Default constructor. Sets the member variables to the following values:
-   * - vertex indices to invalid values
-   * - boundary or material id zero (the default for boundary or material ids)
-   * - manifold id to numbers::invalid_manifold_id
+   * Default constructor. Sets the member variables to the following values: -
+   * vertex indices to invalid values - boundary or material id zero (the
+   * default for boundary or material ids) - manifold id to
+   * numbers::invalid_manifold_id
    */
   CellData ();
 };
@@ -146,58 +138,51 @@ struct CellData
 
 
 /**
- *  Structure to be passed to Triangulation::create_triangulation function to
- *  describe boundary information.
- *
- *  This structure is the same for all dimensions, since we use an input
- *  function which is the same for all dimensions. The content of objects
- *  of this structure varies with the dimensions, however.
- *
- *  Since in one dimension, there is no boundary information apart
- *  from the two end points of the interval, this structure does not contain
- *  anything and exists only for consistency, to allow a common interface
- *  for all space dimensions. All fields should always be empty.
- *
- *  Boundary data in 2D consists
- *  of a list of lines which belong to a given boundary component. A
- *  boundary component is a list of lines which are given a common
- *  number describing the boundary condition to hold on this part of the
- *  boundary. The triangulation creation function gives lines not in this
- *  list either the boundary indicator zero (if on the boundary) or
- *  numbers::internal_face_boundary_id (if in the interior). Explicitely giving a
- *  line the indicator numbers::internal_face_boundary_id will result in an error, as well as giving
- *  an interior line a boundary indicator.
+ * Structure to be passed to Triangulation::create_triangulation function to
+ * describe boundary information.
+ *
+ * This structure is the same for all dimensions, since we use an input
+ * function which is the same for all dimensions. The content of objects of
+ * this structure varies with the dimensions, however.
+ *
+ * Since in one dimension, there is no boundary information apart from the two
+ * end points of the interval, this structure does not contain anything and
+ * exists only for consistency, to allow a common interface for all space
+ * dimensions. All fields should always be empty.
+ *
+ * Boundary data in 2D consists of a list of lines which belong to a given
+ * boundary component. A boundary component is a list of lines which are given
+ * a common number describing the boundary condition to hold on this part of
+ * the boundary. The triangulation creation function gives lines not in this
+ * list either the boundary indicator zero (if on the boundary) or
+ * numbers::internal_face_boundary_id (if in the interior). Explicitely giving
+ * a line the indicator numbers::internal_face_boundary_id will result in an
+ * error, as well as giving an interior line a boundary indicator.
  *
  * @ingroup grid
  */
 struct SubCellData
 {
   /**
-   * Each record of this vector describes
-   * a line on the boundary and its boundary
-   * indicator.
+   * Each record of this vector describes a line on the boundary and its
+   * boundary indicator.
    */
   std::vector<CellData<1> > boundary_lines;
 
   /**
-   * Each record of this vector describes
-   * a quad on the boundary and its boundary
-   * indicator.
+   * Each record of this vector describes a quad on the boundary and its
+   * boundary indicator.
    */
   std::vector<CellData<2> > boundary_quads;
 
   /**
-   * This function checks whether the vectors
-   * which may not be used in a given
-   * dimension are really empty. I.e.,
-   * whether the <tt>boundary_*</tt> arrays are
-   * empty when in one space dimension
-   * and whether the @p boundary_quads
+   * This function checks whether the vectors which may not be used in a given
+   * dimension are really empty. I.e., whether the <tt>boundary_*</tt> arrays
+   * are empty when in one space dimension and whether the @p boundary_quads
    * array is empty when in two dimensions.
    *
-   * Since this structure is the same for all
-   * dimensions, the actual dimension has
-   * to be given as a parameter.
+   * Since this structure is the same for all dimensions, the actual dimension
+   * has to be given as a parameter.
    */
   bool check_consistency (const unsigned int dim) const;
 };
@@ -209,23 +194,22 @@ struct SubCellData
 namespace internal
 {
   /**
-   * A namespace for classes internal to the
-   * triangulation classes and helpers.
+   * A namespace for classes internal to the triangulation classes and
+   * helpers.
    */
   namespace Triangulation
   {
 
     /**
-     * Cache class used to store the number of used and active elements
-     * (lines or quads etc) within the levels of a triangulation. This
-     * is only the declaration of the template, concrete instantiations
-     * are below.
+     * Cache class used to store the number of used and active elements (lines
+     * or quads etc) within the levels of a triangulation. This is only the
+     * declaration of the template, concrete instantiations are below.
      *
-     * In the old days, whenever one wanted to access one of these
-     * numbers, one had to perform a loop over all lines, e.g., and count
-     * the elements until we hit the end iterator. This is time consuming
-     * and since access to the number of lines etc is a rather frequent
-     * operation, this was not an optimal solution.
+     * In the old days, whenever one wanted to access one of these numbers,
+     * one had to perform a loop over all lines, e.g., and count the elements
+     * until we hit the end iterator. This is time consuming and since access
+     * to the number of lines etc is a rather frequent operation, this was not
+     * an optimal solution.
      *
      * @author Wolfgang Bangerth, 1999
      */
@@ -235,15 +219,15 @@ namespace internal
     };
 
     /**
-     * Cache class used to store the number of used and active elements
-     * (lines or quads etc) within the levels of a triangulation. This
-     * specialization stores the numbers of lines.
+     * Cache class used to store the number of used and active elements (lines
+     * or quads etc) within the levels of a triangulation. This specialization
+     * stores the numbers of lines.
      *
-     * In the old days, whenever one wanted to access one of these
-     * numbers, one had to perform a loop over all lines, e.g., and count
-     * the elements until we hit the end iterator. This is time consuming
-     * and since access to the number of lines etc is a rather frequent
-     * operation, this was not an optimal solution.
+     * In the old days, whenever one wanted to access one of these numbers,
+     * one had to perform a loop over all lines, e.g., and count the elements
+     * until we hit the end iterator. This is time consuming and since access
+     * to the number of lines etc is a rather frequent operation, this was not
+     * an optimal solution.
      *
      * @author Wolfgang Bangerth, 1999
      */
@@ -251,52 +235,44 @@ namespace internal
     struct NumberCache<1>
     {
       /**
-       * The number of levels on
-       * which we have used
-       * objects.
+       * The number of levels on which we have used objects.
        */
       unsigned int n_levels;
 
       /**
-       * Number of used lines in the whole
-       * triangulation.
+       * Number of used lines in the whole triangulation.
        */
       unsigned int n_lines;
 
       /**
-       * Array holding the number of used
-       * lines on each level.
+       * Array holding the number of used lines on each level.
        */
       std::vector<unsigned int> n_lines_level;
 
       /**
-       * Number of active lines in the
-       * whole triangulation.
+       * Number of active lines in the whole triangulation.
        */
       unsigned int n_active_lines;
 
       /**
-       * Array holding the number of active
-       * lines on each level.
+       * Array holding the number of active lines on each level.
        */
       std::vector<unsigned int> n_active_lines_level;
 
       /**
-       * Constructor. Set values to zero
-       * by default.
+       * Constructor. Set values to zero by default.
        */
       NumberCache ();
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize (Archive &ar,
@@ -305,17 +281,16 @@ namespace internal
 
 
     /**
-     * Cache class used to store the number of used and active elements
-     * (lines or quads etc) within the levels of a triangulation. This
-     * specialization stores the numbers of quads. Due to the inheritance
-     * from the base class NumberCache<1>, the numbers of lines
-     * are also within this class.
+     * Cache class used to store the number of used and active elements (lines
+     * or quads etc) within the levels of a triangulation. This specialization
+     * stores the numbers of quads. Due to the inheritance from the base class
+     * NumberCache<1>, the numbers of lines are also within this class.
      *
-     * In the old days, whenever one wanted to access one of these
-     * numbers, one had to perform a loop over all lines, e.g., and count
-     * the elements until we hit the end iterator. This is time consuming
-     * and since access to the number of lines etc is a rather frequent
-     * operation, this was not an optimal solution.
+     * In the old days, whenever one wanted to access one of these numbers,
+     * one had to perform a loop over all lines, e.g., and count the elements
+     * until we hit the end iterator. This is time consuming and since access
+     * to the number of lines etc is a rather frequent operation, this was not
+     * an optimal solution.
      *
      * @author Wolfgang Bangerth, 1999
      */
@@ -323,45 +298,39 @@ namespace internal
     struct NumberCache<2> : public NumberCache<1>
     {
       /**
-       * Number of used quads in the whole
-       * triangulation.
+       * Number of used quads in the whole triangulation.
        */
       unsigned int n_quads;
 
       /**
-       * Array holding the number of used
-       * quads on each level.
+       * Array holding the number of used quads on each level.
        */
       std::vector<unsigned int> n_quads_level;
 
       /**
-       * Number of active quads in the
-       * whole triangulation.
+       * Number of active quads in the whole triangulation.
        */
       unsigned int n_active_quads;
 
       /**
-       * Array holding the number of active
-       * quads on each level.
+       * Array holding the number of active quads on each level.
        */
       std::vector<unsigned int> n_active_quads_level;
 
       /**
-       * Constructor. Set values to zero
-       * by default.
+       * Constructor. Set values to zero by default.
        */
       NumberCache ();
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize (Archive &ar,
@@ -370,17 +339,17 @@ namespace internal
 
 
     /**
-     * Cache class used to store the number of used and active elements
-     * (lines or quads etc) within the levels of a triangulation. This
-     * specialization stores the numbers of hexes. Due to the inheritance
-     * from the base class NumberCache<2>, the numbers of lines
-     * and quads are also within this class.
+     * Cache class used to store the number of used and active elements (lines
+     * or quads etc) within the levels of a triangulation. This specialization
+     * stores the numbers of hexes. Due to the inheritance from the base class
+     * NumberCache<2>, the numbers of lines and quads are also within this
+     * class.
      *
-     * In the old days, whenever one wanted to access one of these
-     * numbers, one had to perform a loop over all lines, e.g., and count
-     * the elements until we hit the end . This is time consuming
-     * and since access to the number of lines etc is a rather frequent
-     * operation, this was not an optimal solution.
+     * In the old days, whenever one wanted to access one of these numbers,
+     * one had to perform a loop over all lines, e.g., and count the elements
+     * until we hit the end . This is time consuming and since access to the
+     * number of lines etc is a rather frequent operation, this was not an
+     * optimal solution.
      *
      * @author Wolfgang Bangerth, 1999
      */
@@ -388,45 +357,39 @@ namespace internal
     struct NumberCache<3> : public NumberCache<2>
     {
       /**
-       * Number of used hexes in the whole
-       * triangulation.
+       * Number of used hexes in the whole triangulation.
        */
       unsigned int n_hexes;
 
       /**
-       * Array holding the number of used
-       * hexes on each level.
+       * Array holding the number of used hexes on each level.
        */
       std::vector<unsigned int> n_hexes_level;
 
       /**
-       * Number of active hexes in the
-       * whole triangulation.
+       * Number of active hexes in the whole triangulation.
        */
       unsigned int n_active_hexes;
 
       /**
-       * Array holding the number of active
-       * hexes on each level.
+       * Array holding the number of active hexes on each level.
        */
       std::vector<unsigned int> n_active_hexes_level;
 
       /**
-       * Constructor. Set values to zero
-       * by default.
+       * Constructor. Set values to zero by default.
        */
       NumberCache ();
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize (Archive &ar,
@@ -440,57 +403,57 @@ namespace internal
 
 
 /**
- *  Triangulations denote a hierarchy of levels of elements which together
- *  form a @p dim -dimensional manifold in @p spacedim spatial dimensions
- *  (if spacedim is not specified it takes the default value @p spacedim=dim).
- *
- *  Thus, for example, an object of type @p Triangulation<1,1> (or simply
- *  @p Triangulation<1> since @p spacedim==dim by default) is used to represent
- *  and handle the usual one-dimensional triangulation used in the finite
- *  element method (so, segments on a straight line). On the other hand,
- *  objects such as @p Triangulation<1,2> or @p Triangulation<2,3> (that
- *  are associated with curves in 2D or surfaces in 3D)
- *  are the ones one wants to use in the boundary element method.
- *
- *  This class is written to be as independent of the dimension as possible
- *  (thus the complex construction of the dealii::internal::Triangulation::TriaLevel
- *  classes) to allow code-sharing, to allow reducing the need to mirror
- *  changes in the code for one dimension to the code for other
- *  dimensions. Nonetheless, some of the functions are dependent of the
- *  dimension and there only exist specialized versions for distinct
- *  dimensions.
- *
- *  This class satisfies the requirements outlined in
- *  @ref GlossMeshAsAContainer "Meshes as containers".
- *
- *
- *  <h3>Structure and iterators</h3>
- *
- *  The actual data structure of a Triangulation object is rather complex
- *  and quite inconvenient if one attempted to operate on it directly, since
- *  data is spread over quite a lot of arrays and other places. However,
- *  there are ways powerful enough to work on these data structures
- *  without knowing their exact relations. This is done through the
- *  concept of iterators (see the STL documentation and TriaIterator).
- *  In order to make things as easy and dimension independent as possible,
- *  use of class local typedefs is made, see below.
- *
- *  The Triangulation class provides iterator which enable looping over all
- *  cells without knowing the exact representation used to
- *  describe them. Their names are typedefs imported from the Iterators
- *  class (thus making them local types to this class) and are as follows:
- *
- *  <ul>
- *  <li> <tt>cell_iterator</tt>: loop over all cells used in the Triangulation
- *  <li> <tt>active_cell_iterator</tt>: loop over all active cells
- *  </ul>
- *
- *  For <tt>dim==1</tt>, these iterators are mapped as follows:
+ * Triangulations denote a hierarchy of levels of elements which together form
+ * a @p dim -dimensional manifold in @p spacedim spatial dimensions (if
+ * spacedim is not specified it takes the default value @p spacedim=dim).
+ *
+ * Thus, for example, an object of type @p Triangulation<1,1> (or simply @p
+ * Triangulation<1> since @p spacedim==dim by default) is used to represent
+ * and handle the usual one-dimensional triangulation used in the finite
+ * element method (so, segments on a straight line). On the other hand,
+ * objects such as @p Triangulation<1,2> or @p Triangulation<2,3> (that are
+ * associated with curves in 2D or surfaces in 3D) are the ones one wants to
+ * use in the boundary element method.
+ *
+ * This class is written to be as independent of the dimension as possible
+ * (thus the complex construction of the
+ * dealii::internal::Triangulation::TriaLevel classes) to allow code-sharing,
+ * to allow reducing the need to mirror changes in the code for one dimension
+ * to the code for other dimensions. Nonetheless, some of the functions are
+ * dependent of the dimension and there only exist specialized versions for
+ * distinct dimensions.
+ *
+ * This class satisfies the requirements outlined in @ref
+ * GlossMeshAsAContainer "Meshes as containers".
+ *
+ *
+ * <h3>Structure and iterators</h3>
+ *
+ * The actual data structure of a Triangulation object is rather complex and
+ * quite inconvenient if one attempted to operate on it directly, since data
+ * is spread over quite a lot of arrays and other places. However, there are
+ * ways powerful enough to work on these data structures without knowing their
+ * exact relations. This is done through the concept of iterators (see the STL
+ * documentation and TriaIterator). In order to make things as easy and
+ * dimension independent as possible, use of class local typedefs is made, see
+ * below.
+ *
+ * The Triangulation class provides iterator which enable looping over all
+ * cells without knowing the exact representation used to describe them. Their
+ * names are typedefs imported from the Iterators class (thus making them
+ * local types to this class) and are as follows:
+ *
+ * <ul>
+ * <li> <tt>cell_iterator</tt>: loop over all cells used in the Triangulation
+ * <li> <tt>active_cell_iterator</tt>: loop over all active cells
+ * </ul>
+ *
+ * For <tt>dim==1</tt>, these iterators are mapped as follows:
  *  @code
  *    typedef line_iterator        cell_iterator;
  *    typedef active_line_iterator active_cell_iterator;
  *  @endcode
- *  while for @p dim==2 we have the additional face iterator:
+ * while for @p dim==2 we have the additional face iterator:
  *  @code
  *    typedef quad_iterator        cell_iterator;
  *    typedef active_quad_iterator active_cell_iterator;
@@ -499,22 +462,23 @@ namespace internal
  *    typedef active_line_iterator active_face_iterator;
  *  @endcode
  *
- *  By using the cell iterators, you can write code independent of
- *  the spatial dimension. The same applies for substructure iterators,
- *  where a substructure is defined as a face of a cell. The face of a
- *  cell is a vertex in 1D and a line in 2D; however, vertices are
- *  handled in a different way and therefore lines have no faces.
- *
- *  The Triangulation class offers functions like begin_active() which gives
- *  you an iterator to the first active cell. There are quite a lot of functions
- *  returning iterators. Take a look at the class doc to get an overview.
- *
- *  Usage of these iterators works mostly like with the STL iterators. Some
- *  examples taken from the Triangulation source code follow (notice that in the last
- *  two examples the template parameter @p spacedim has been omitted, so it takes
- *  the default value <code>dim</code>).
- *  <ul>
- *  <li> <em>Counting the number of cells on a specific level</em>
+ * By using the cell iterators, you can write code independent of the spatial
+ * dimension. The same applies for substructure iterators, where a
+ * substructure is defined as a face of a cell. The face of a cell is a vertex
+ * in 1D and a line in 2D; however, vertices are handled in a different way
+ * and therefore lines have no faces.
+ *
+ * The Triangulation class offers functions like begin_active() which gives
+ * you an iterator to the first active cell. There are quite a lot of
+ * functions returning iterators. Take a look at the class doc to get an
+ * overview.
+ *
+ * Usage of these iterators works mostly like with the STL iterators. Some
+ * examples taken from the Triangulation source code follow (notice that in
+ * the last two examples the template parameter @p spacedim has been omitted,
+ * so it takes the default value <code>dim</code>).
+ * <ul>
+ * <li> <em>Counting the number of cells on a specific level</em>
  *    @code
  *     template <int dim, int spacedim>
  *     int Triangulation<dim, spacedim>::n_cells (const int level) const {
@@ -526,7 +490,7 @@ namespace internal
  *        return n;
  *      };
  *    @endcode
- *    Another way which uses the STL @p distance function would be to write
+ * Another way which uses the STL @p distance function would be to write
  *    @code
  *      template <int dim>
  *      int Triangulation<dim>::n_cells (const int level) const {
@@ -540,7 +504,7 @@ namespace internal
  *      };
  *    @endcode
  *
- *  <li> <em>Refining all cells of a triangulation</em>
+ * <li> <em>Refining all cells of a triangulation</em>
  *    @code
  *      template <int dim>
  *      void Triangulation<dim>::refine_global () {
@@ -552,13 +516,13 @@ namespace internal
  *        execute_coarsening_and_refinement ();
  *      };
  *    @endcode
- *  </ul>
+ * </ul>
  *
  *
- *  <h3>Usage</h3>
+ * <h3>Usage</h3>
  *
- *  Usage of a Triangulation is mainly done through the use of iterators.
- *  An example probably shows best how to use it:
+ * Usage of a Triangulation is mainly done through the use of iterators. An
+ * example probably shows best how to use it:
  *  @code
  *  void main () {
  *    Triangulation<2> tria;
@@ -599,250 +563,231 @@ namespace internal
  *  @endcode
  *
  *
- *  <h3>Creating a triangulation</h3>
- *
- *  There are several possibilities to create a triangulation:
- *  <ul>
- *    <li> The most common domains, such as hypercubes (i.e. lines, squares,
- *       cubes, etc), hyper-balls (circles, balls, ...) and some other, more
- *       weird domains such as the L-shape region and higher dimensional
- *       generalizations and others, are provided by the GridGenerator
- *       class which takes a triangulation and fills it by a division
- *       of the required domain.
- *
- *     <li> Reading in a triangulation: By using an object of the GridIn
- *        class, you can read in fairly general triangulations. See there for
- *        more information. The mentioned class uses the interface described
- *        directly below to transfer the data into the triangulation.
- *
- *     <li> Explicitly creating a triangulation: you can create a triangulation
- *        by providing a list of vertices and a list of cells. Each such cell
- *        consists of a vector storing the indices of the vertices of this cell
- *        in the vertex list. To see how this works, you can take a look at the
- *        GridIn<dim>::read_* functions. The appropriate function to be
- *        called is create_triangulation().
- *
- *        Creating the hierarchical information needed for this
- *        library from cells storing only vertex information can be
- *        quite a complex task.  For example in 2D, we have to create
- *        lines between vertices (but only once, though there are two
- *        cells which link these two vertices) and we have to create
- *        neighborhood information. Grids being read in should
- *        therefore not be too large, reading refined grids would be
- *        inefficient (although there is technically no problem in
- *        reading grids with several 10.000 or 100.000 cells; the
- *        library can handle this without much problems). Apart from
- *        the performance aspect, refined grids do not lend too well
- *        to multigrid algorithms, since solving on the coarsest level
- *        is expensive. It is wiser in any case to read in a grid as
- *        coarse as possible and then do the needed refinement steps.
- *
- *        It is your duty to guarantee that cells have the correct orientation.
- *        To guarantee this, in the input vector keeping the cell list, the
- *        vertex indices for each cell have to be in a defined order, see the
- *        documentation of GeometryInfo<dim>. In one dimension, the first vertex
- *        index must refer to that vertex with the lower coordinate value. In 2D
- *        and 3D, the corresponding conditions are not easy to verify and no
- *        full attempt to do so is made.
- *        If you violate this condition, you may end up with matrix entries
- *        having the wrong sign (clockwise vertex numbering, which results in
- *        a negative area element) of with wrong matrix elements (twisted
- *        quadrilaterals, i.e. two vertices interchanged; this results in
- *        a wrong area element).
- *
- *        There are more subtle conditions which must be imposed upon
- *        the vertex numbering within cells. They do not only hold for
- *        the data read from an UCD or any other input file, but also
- *        for the data passed to create_triangulation().
- *        See the documentation for the GridIn class
- *        for more details on this, and above all to the
- *        GridReordering class that explains many of the
- *        problems and an algorithm to reorder cells such that they
- *        satisfy the conditions outlined above.
- *
- *     <li> Copying a triangulation: when computing on time dependent meshes
- *        or when using adaptive refinement, you will often want to create a
- *        new triangulation to be the same as another one. This is facilitated
- *        by the @p copy_triangulation function.
- *
- *        It is guaranteed that vertex, line or cell numbers in the two
- *        triangulations are the same and that two iterators walking on the
- *        two triangulations visit matching cells if they are incremented in
- *        parallel. It may be conceivable to implement a clean-up in the copy
- *        operation, which eliminates holes of unused memory, re-joins
- *        scattered data and so on. In principle this would be a useful
- *        operation but guaranteeing some parallelism in the two triangulations
- *        seems more important since usually data will have to be transferred
- *        between the grids.
- *   </ul>
- *
- *   Finally, there is a special function for folks who like bad grids:
- *   distort_random(). It moves all the vertices in the
- *   grid a bit around by a random value, leaving behind a distorted mesh.
- *   Note that you should apply this function to the final mesh, since
- *   refinement smoothes the mesh a bit.
- *
- *   The function will make sure that vertices on restricted faces (hanging
- *   nodes) will end up in the correct place, i.e. in the middle of the two
- *   other vertices of the mother line, and the analogue in higher space
- *   dimensions (vertices on the boundary are not corrected, so don't distort
- *   boundary vertices in more than two space dimension, i.e. in dimensions
- *   where boundary vertices can be hanging nodes). Applying the algorithm
- *   has another drawback related to the
- *   placement of cells, however: the children of a cell will not occupy the
- *   same region of the domain as the mother cell does. While this is the
- *   usual behavior with cells at the boundary, here you may get into trouble
- *   when using multigrid algorithms or when transferring solutions from coarse
- *   to fine grids and back. In general, the use of this function is only safe
- *   if you only use the most refined level of the triangulation for
- *   computations.
- *
- *
- *
- *   <h3>Refinement and coarsening of a triangulation</h3>
- *
- *   Refinement of a triangulation may be done through several ways. The most
- *   low-level way is directly through iterators: let @p i be an iterator to
- *   an active cell (i.e. the cell pointed to has no children), then the
- *   function call <tt>i->set_refine_flag()</tt> marks the respective cell for
- *   refinement. Marking non-active cells results in an error.
- *
- *   After all the cells you wanted to mark for refinement, call
- *   execute_coarsening_and_refinement() to actually perform
- *   the refinement. This function itself first calls the
- *   @p prepare_coarsening_and_refinement function to regularize the resulting
- *   triangulation: since a face between two adjacent cells may only
- *   be subdivided once (i.e. the levels of two adjacent cells may
- *   differ by one at most; it is not possible to have a cell refined
- *   twice while the neighboring one is not refined), some additional
- *   cells are flagged for refinement to smooth the grid. This
- *   enlarges the number of resulting cells but makes the grid more
- *   regular, thus leading to better approximation properties and,
- *   above all, making the handling of data structures and algorithms
- *   much much easier. To be honest, this is mostly an algorithmic
- *   step than one needed by the finite element method.
- *
- *   To coarsen a grid, the same way as above is possible by using
- *   <tt>i->set_coarsen_flag</tt> and calling execute_coarsening_and_refinement().
- *
- *   The reason for first coarsening, then refining is that the
- *   refinement usually adds some additional cells to keep the triangulation
- *   regular and thus satisfies all refinement requests, while the coarsening
- *   does not delete cells not requested for; therefore the refinement will
- *   often revert some effects of coarsening while the opposite is not true.
- *   The stated order of coarsening before refinement will thus normally
- *   lead to a result closer to the intended one.
- *
- *   Marking cells for refinement 'by hand' through iterators is one way to
- *   produce a new grid, especially if you know what kind of grid you are
- *   looking for, e.g. if you want to have a grid successively refined
- *   towards the boundary or always at the center (see the example programs,
- *   they do exactly these things). There are more advanced functions,
- *   however, which are more suitable for automatic generation of hierarchical
- *   grids in the context of a posteriori error estimation and adaptive finite
- *   elements. These functions can be found in the GridRefinement class.
- *
- *
- *   <h3>Smoothing of a triangulation</h3>
- *
- *   Some degradation of approximation properties has been observed
- *   for grids which are too unstructured. Therefore,
- *   prepare_coarsening_and_refinement() which is automatically called
- *   by execute_coarsening_and_refinement() can do some
- *   smoothing of the triangulation. Note that mesh smoothing is only
- *   done for two or more space dimensions, no smoothing is available
- *   at present for one spatial dimension. In the following, let
- *   <tt>execute_*</tt> stand for execute_coarsening_and_refinement().
- *
- *   For the purpose of smoothing, the
- *   Triangulation constructor takes an argument specifying whether a
- *   smoothing step shall be performed on the grid each time <tt>execute_*</tt>
- *   is called. The default is that such a step not be done, since this results
- *   in additional cells being produced, which may not be necessary in all
- *   cases. If switched on, calling <tt>execute_*</tt> results in
- *   flagging additional cells for refinement to avoid
- *   vertices as the ones mentioned. The algorithms for both regularization
- *   and smoothing of triangulations are described below in the section on
- *   technical issues. The reason why this parameter must be given to the
- *   constructor rather than to <tt>execute_*</tt> is that it would result
- *   in algorithmic problems if you called <tt>execute_*</tt> once without
- *   and once with smoothing, since then in some refinement steps would need
- *   to be refined twice.
- *
- *   The parameter taken by the constructor is an integer which may be
- *   composed bitwise by the constants defined in the enum
- *   #MeshSmoothing (see there for the possibilities).
- *
- *   @note While it is possible to pass all of the flags in #MeshSmoothing to
- *   objects of type parallel::distributed::Triangulation, it is not always
- *   possible to honor all of these smoothing options if they would require
- *   knowledge of refinement/coarsening flags on cells not locally owned by
- *   this processor. As a consequence, for some of these flags, the ultimate
- *   number of cells of the parallel triangulation may depend on the number of
- *   processors into which it is partitioned.
- *
- *
- *   <h3>Material and boundary information</h3>
- *
- *   Each cell, face or edge stores information denoting the
- *   material or the part of the boundary that an object
- *   belongs to. The material of a cell may be used
- *   during matrix generation in order to implement different
- *   coefficients in different parts of the domain. It is not used by
- *   functions of the grid and dof handling libraries.
- *
- *   This material_id may be set upon construction of a
- *   triangulation (through the CellData data structure), or later
- *   through use of cell iterators. For a typical use of this
- *   functionality, see the step-28 tutorial
- *   program. The functions of the GridGenerator namespace typically
- *   set the material ID of all cells to zero. When reading a
- *   triangulation, the material id must be specified in the input
- *   file (UCD format) or is otherwise set to zero. Material IDs are
- *   inherited by child cells from their parent upon mesh refinement.
- *
- *   Boundary indicators on lower dimensional objects (these have no
- *   material id) indicate the number of a boundary component. These
- *   are used for two purposes: First, they specify a boundary
- *   curve. When a cell is refined, a function can be used to place
- *   new vertices on this curve. See the section on boundary
- *   approximation below. Furthermore, the weak formulation of the
- *   partial differential equation may have different boundary
- *   conditions on different parts of the boundary. The boundary
- *   indicator can be used in creating the matrix or the right hand
- *   side vector to indicate these different parts of the model (this
- *   use is like the material id of cells).
-
- *   Boundary indicators may be in the range from zero to
- *   numbers::internal_face_boundary_id-1. The value
- *   numbers::internal_face_boundary_id is reserved to denote interior lines (in 2D)
- *   and interior lines and quads (in 3D), which do not have a
- *   boundary indicator. This way, a program can easily
- *   determine, whether such an object is at the boundary or not.
- *   Material indicators may be in the range from zero to numbers::invalid_material_id-1.
- *
- *   Lines in two dimensions and quads in three dimensions inherit their
- *   boundary indicator to their children upon refinement. You should therefore
- *   make sure that if you have different boundary parts, the different parts
- *   are separated by a vertex (in 2D) or a line (in 3D) such that each boundary
- *   line or quad has a unique boundary indicator.
- *
- *   By default (unless otherwise specified during creation of a
- *   triangulation), all parts of the boundary have boundary indicator
- *   zero. As a historical wart, this isn't true for 1d meshes, however: For
- *   these, leftmost vertices have boundary indicator zero while rightmost
- *   vertices have boundary indicator one. In either case, the boundary
- *   indicator of a face can be changed using a call of the kind
- *   <code>cell-@>face(1)-@>set_boundary_indicator(42);</code>.
- *
- *   @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
- *
- *
- *   <h3>History of a triangulation</h3>
- *
- *   It is possible to reconstruct a grid from its refinement history, which
- *   can be stored and loaded through the @p save_refine_flags and
- *   @p load_refine_flags functions. Normally, the code will look like this:
+ * <h3>Creating a triangulation</h3>
+ *
+ * There are several possibilities to create a triangulation:
+ * <ul>
+ * <li> The most common domains, such as hypercubes (i.e. lines, squares,
+ * cubes, etc), hyper-balls (circles, balls, ...) and some other, more weird
+ * domains such as the L-shape region and higher dimensional generalizations
+ * and others, are provided by the GridGenerator class which takes a
+ * triangulation and fills it by a division of the required domain.
+ *
+ * <li> Reading in a triangulation: By using an object of the GridIn class,
+ * you can read in fairly general triangulations. See there for more
+ * information. The mentioned class uses the interface described directly
+ * below to transfer the data into the triangulation.
+ *
+ * <li> Explicitly creating a triangulation: you can create a triangulation by
+ * providing a list of vertices and a list of cells. Each such cell consists
+ * of a vector storing the indices of the vertices of this cell in the vertex
+ * list. To see how this works, you can take a look at the GridIn<dim>::read_*
+ * functions. The appropriate function to be called is create_triangulation().
+ *
+ * Creating the hierarchical information needed for this library from cells
+ * storing only vertex information can be quite a complex task.  For example
+ * in 2D, we have to create lines between vertices (but only once, though
+ * there are two cells which link these two vertices) and we have to create
+ * neighborhood information. Grids being read in should therefore not be too
+ * large, reading refined grids would be inefficient (although there is
+ * technically no problem in reading grids with several 10.000 or 100.000
+ * cells; the library can handle this without much problems). Apart from the
+ * performance aspect, refined grids do not lend too well to multigrid
+ * algorithms, since solving on the coarsest level is expensive. It is wiser
+ * in any case to read in a grid as coarse as possible and then do the needed
+ * refinement steps.
+ *
+ * It is your duty to guarantee that cells have the correct orientation. To
+ * guarantee this, in the input vector keeping the cell list, the vertex
+ * indices for each cell have to be in a defined order, see the documentation
+ * of GeometryInfo<dim>. In one dimension, the first vertex index must refer
+ * to that vertex with the lower coordinate value. In 2D and 3D, the
+ * corresponding conditions are not easy to verify and no full attempt to do
+ * so is made. If you violate this condition, you may end up with matrix
+ * entries having the wrong sign (clockwise vertex numbering, which results in
+ * a negative area element) of with wrong matrix elements (twisted
+ * quadrilaterals, i.e. two vertices interchanged; this results in a wrong
+ * area element).
+ *
+ * There are more subtle conditions which must be imposed upon the vertex
+ * numbering within cells. They do not only hold for the data read from an UCD
+ * or any other input file, but also for the data passed to
+ * create_triangulation(). See the documentation for the GridIn class for more
+ * details on this, and above all to the GridReordering class that explains
+ * many of the problems and an algorithm to reorder cells such that they
+ * satisfy the conditions outlined above.
+ *
+ * <li> Copying a triangulation: when computing on time dependent meshes or
+ * when using adaptive refinement, you will often want to create a new
+ * triangulation to be the same as another one. This is facilitated by the @p
+ * copy_triangulation function.
+ *
+ * It is guaranteed that vertex, line or cell numbers in the two
+ * triangulations are the same and that two iterators walking on the two
+ * triangulations visit matching cells if they are incremented in parallel. It
+ * may be conceivable to implement a clean-up in the copy operation, which
+ * eliminates holes of unused memory, re-joins scattered data and so on. In
+ * principle this would be a useful operation but guaranteeing some
+ * parallelism in the two triangulations seems more important since usually
+ * data will have to be transferred between the grids.
+ * </ul>
+ *
+ * Finally, there is a special function for folks who like bad grids:
+ * distort_random(). It moves all the vertices in the grid a bit around by a
+ * random value, leaving behind a distorted mesh. Note that you should apply
+ * this function to the final mesh, since refinement smoothes the mesh a bit.
+ *
+ * The function will make sure that vertices on restricted faces (hanging
+ * nodes) will end up in the correct place, i.e. in the middle of the two
+ * other vertices of the mother line, and the analogue in higher space
+ * dimensions (vertices on the boundary are not corrected, so don't distort
+ * boundary vertices in more than two space dimension, i.e. in dimensions
+ * where boundary vertices can be hanging nodes). Applying the algorithm has
+ * another drawback related to the placement of cells, however: the children
+ * of a cell will not occupy the same region of the domain as the mother cell
+ * does. While this is the usual behavior with cells at the boundary, here you
+ * may get into trouble when using multigrid algorithms or when transferring
+ * solutions from coarse to fine grids and back. In general, the use of this
+ * function is only safe if you only use the most refined level of the
+ * triangulation for computations.
+ *
+ *
+ *
+ * <h3>Refinement and coarsening of a triangulation</h3>
+ *
+ * Refinement of a triangulation may be done through several ways. The most
+ * low-level way is directly through iterators: let @p i be an iterator to an
+ * active cell (i.e. the cell pointed to has no children), then the function
+ * call <tt>i->set_refine_flag()</tt> marks the respective cell for
+ * refinement. Marking non-active cells results in an error.
+ *
+ * After all the cells you wanted to mark for refinement, call
+ * execute_coarsening_and_refinement() to actually perform the refinement.
+ * This function itself first calls the @p prepare_coarsening_and_refinement
+ * function to regularize the resulting triangulation: since a face between
+ * two adjacent cells may only be subdivided once (i.e. the levels of two
+ * adjacent cells may differ by one at most; it is not possible to have a cell
+ * refined twice while the neighboring one is not refined), some additional
+ * cells are flagged for refinement to smooth the grid. This enlarges the
+ * number of resulting cells but makes the grid more regular, thus leading to
+ * better approximation properties and, above all, making the handling of data
+ * structures and algorithms much much easier. To be honest, this is mostly an
+ * algorithmic step than one needed by the finite element method.
+ *
+ * To coarsen a grid, the same way as above is possible by using
+ * <tt>i->set_coarsen_flag</tt> and calling
+ * execute_coarsening_and_refinement().
+ *
+ * The reason for first coarsening, then refining is that the refinement
+ * usually adds some additional cells to keep the triangulation regular and
+ * thus satisfies all refinement requests, while the coarsening does not
+ * delete cells not requested for; therefore the refinement will often revert
+ * some effects of coarsening while the opposite is not true. The stated order
+ * of coarsening before refinement will thus normally lead to a result closer
+ * to the intended one.
+ *
+ * Marking cells for refinement 'by hand' through iterators is one way to
+ * produce a new grid, especially if you know what kind of grid you are
+ * looking for, e.g. if you want to have a grid successively refined towards
+ * the boundary or always at the center (see the example programs, they do
+ * exactly these things). There are more advanced functions, however, which
+ * are more suitable for automatic generation of hierarchical grids in the
+ * context of a posteriori error estimation and adaptive finite elements.
+ * These functions can be found in the GridRefinement class.
+ *
+ *
+ * <h3>Smoothing of a triangulation</h3>
+ *
+ * Some degradation of approximation properties has been observed for grids
+ * which are too unstructured. Therefore, prepare_coarsening_and_refinement()
+ * which is automatically called by execute_coarsening_and_refinement() can do
+ * some smoothing of the triangulation. Note that mesh smoothing is only done
+ * for two or more space dimensions, no smoothing is available at present for
+ * one spatial dimension. In the following, let <tt>execute_*</tt> stand for
+ * execute_coarsening_and_refinement().
+ *
+ * For the purpose of smoothing, the Triangulation constructor takes an
+ * argument specifying whether a smoothing step shall be performed on the grid
+ * each time <tt>execute_*</tt> is called. The default is that such a step not
+ * be done, since this results in additional cells being produced, which may
+ * not be necessary in all cases. If switched on, calling <tt>execute_*</tt>
+ * results in flagging additional cells for refinement to avoid vertices as
+ * the ones mentioned. The algorithms for both regularization and smoothing of
+ * triangulations are described below in the section on technical issues. The
+ * reason why this parameter must be given to the constructor rather than to
+ * <tt>execute_*</tt> is that it would result in algorithmic problems if you
+ * called <tt>execute_*</tt> once without and once with smoothing, since then
+ * in some refinement steps would need to be refined twice.
+ *
+ * The parameter taken by the constructor is an integer which may be composed
+ * bitwise by the constants defined in the enum #MeshSmoothing (see there for
+ * the possibilities).
+ *
+ * @note While it is possible to pass all of the flags in #MeshSmoothing to
+ * objects of type parallel::distributed::Triangulation, it is not always
+ * possible to honor all of these smoothing options if they would require
+ * knowledge of refinement/coarsening flags on cells not locally owned by this
+ * processor. As a consequence, for some of these flags, the ultimate number
+ * of cells of the parallel triangulation may depend on the number of
+ * processors into which it is partitioned.
+ *
+ *
+ * <h3>Material and boundary information</h3>
+ *
+ * Each cell, face or edge stores information denoting the material or the
+ * part of the boundary that an object belongs to. The material of a cell may
+ * be used during matrix generation in order to implement different
+ * coefficients in different parts of the domain. It is not used by functions
+ * of the grid and dof handling libraries.
+ *
+ * This material_id may be set upon construction of a triangulation (through
+ * the CellData data structure), or later through use of cell iterators. For a
+ * typical use of this functionality, see the step-28 tutorial program. The
+ * functions of the GridGenerator namespace typically set the material ID of
+ * all cells to zero. When reading a triangulation, the material id must be
+ * specified in the input file (UCD format) or is otherwise set to zero.
+ * Material IDs are inherited by child cells from their parent upon mesh
+ * refinement.
+ *
+ * Boundary indicators on lower dimensional objects (these have no material
+ * id) indicate the number of a boundary component. These are used for two
+ * purposes: First, they specify a boundary curve. When a cell is refined, a
+ * function can be used to place new vertices on this curve. See the section
+ * on boundary approximation below. Furthermore, the weak formulation of the
+ * partial differential equation may have different boundary conditions on
+ * different parts of the boundary. The boundary indicator can be used in
+ * creating the matrix or the right hand side vector to indicate these
+ * different parts of the model (this use is like the material id of cells).
+ * Boundary indicators may be in the range from zero to
+ * numbers::internal_face_boundary_id-1. The value
+ * numbers::internal_face_boundary_id is reserved to denote interior lines (in
+ * 2D) and interior lines and quads (in 3D), which do not have a boundary
+ * indicator. This way, a program can easily determine, whether such an object
+ * is at the boundary or not. Material indicators may be in the range from
+ * zero to numbers::invalid_material_id-1.
+ *
+ * Lines in two dimensions and quads in three dimensions inherit their
+ * boundary indicator to their children upon refinement. You should therefore
+ * make sure that if you have different boundary parts, the different parts
+ * are separated by a vertex (in 2D) or a line (in 3D) such that each boundary
+ * line or quad has a unique boundary indicator.
+ *
+ * By default (unless otherwise specified during creation of a triangulation),
+ * all parts of the boundary have boundary indicator zero. As a historical
+ * wart, this isn't true for 1d meshes, however: For these, leftmost vertices
+ * have boundary indicator zero while rightmost vertices have boundary
+ * indicator one. In either case, the boundary indicator of a face can be
+ * changed using a call of the kind
+ * <code>cell-@>face(1)-@>set_boundary_indicator(42);</code>.
+ *
+ * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
+ *
+ *
+ * <h3>History of a triangulation</h3>
+ *
+ * It is possible to reconstruct a grid from its refinement history, which can
+ * be stored and loaded through the @p save_refine_flags and @p
+ * load_refine_flags functions. Normally, the code will look like this:
  *   @code
  *                                 // open output file
  *     ofstream history("mesh.history");
@@ -856,7 +801,7 @@ namespace internal
  *     };
  *   @endcode
  *
- *   If you want to re-create the grid from the stored information, you write:
+ * If you want to re-create the grid from the stored information, you write:
  *   @code
  *                                 // open input file
  *     ifstream history("mesh.history");
@@ -867,65 +812,60 @@ namespace internal
  *     };
  *   @endcode
  *
- *   The same scheme is employed for coarsening and the coarsening flags.
- *
- *   You may write other information to the output file between different sets
- *   of refinement information, as long as you read it upon re-creation of the
- *   grid. You should make sure that the other information in the new
- *   triangulation which is to be created from the saved flags, matches that of
- *   the old triangulation, for example the smoothing level; if not, the
- *   cells actually created from the flags may be other ones, since smoothing
- *   adds additional cells, but their number may be depending on the smoothing
- *   level.
- *
- *   There actually are two sets of <tt>save_*_flags</tt> and <tt>load_*_flags</tt> functions.
- *   One takes a stream as argument and reads/writes the information from/to the
- *   stream, thus enabling storing flags to files. The other set takes an
- *   argument of type <tt>vector<bool></tt>. This enables the user to temporarily store
- *   some flags, e.g. if another function needs them, and restore them
- *   afterwards.
- *
- *
- *   <h3>User flags and data</h3>
- *
- *   A triangulation offers one bit per line, quad, etc for user flags.
- *   This field can be
- *   accessed as all other data using iterators. Normally, this user flag is
- *   used if an algorithm walks over all cells and needs information whether
- *   another cell, e.g. a neighbor, has already been processed.
- *   See @ref GlossUserFlags "the glossary for more information".
- *
- *   There is another set of user data, which can be either an
- *   <tt>unsigned int</tt> or a <tt>void *</tt>, for
- *   each line, quad, etc. You can access these through
- *   the functions listed under <tt>User data</tt> in
- *   the accessor classes.
- *   Again, see @ref GlossUserData "the glossary for more information".
- *
- *   The value of these user indices or pointers is @p NULL by default. Note that
- *   the pointers are not inherited to children upon
- *   refinement. Still, after a remeshing they are available on all
- *   cells, where they were set on the previous mesh.
- *
- *   The usual warning about the missing type safety of @p void pointers are
- *   obviously in place here; responsibility for correctness of types etc
- *   lies entirely with the user of the pointer.
- *
- *   @note User pointers and user indices are stored in the same
- *   place. In order to avoid unwanted conversions, Triangulation
- *   checks which one of them is in use and does not allow access to
- *   the other one, until clear_user_data() has been called.
- *
- *
- *   <h3>Boundary approximation</h3>
- *
- *   You can specify a boundary function for each boundary
- *   component. If a new vertex is created on a side or face at the
- *   boundary, this function is used to compute where it will be
- *   placed. The boundary indicator of the face will be used to
- *   determine the proper component. See Boundary for the
- *   details. Usage with the Triangulation object is then like this
- *   (let @p Ball be a class derived from Boundary<tt><2></tt>):
+ * The same scheme is employed for coarsening and the coarsening flags.
+ *
+ * You may write other information to the output file between different sets
+ * of refinement information, as long as you read it upon re-creation of the
+ * grid. You should make sure that the other information in the new
+ * triangulation which is to be created from the saved flags, matches that of
+ * the old triangulation, for example the smoothing level; if not, the cells
+ * actually created from the flags may be other ones, since smoothing adds
+ * additional cells, but their number may be depending on the smoothing level.
+ *
+ * There actually are two sets of <tt>save_*_flags</tt> and
+ * <tt>load_*_flags</tt> functions. One takes a stream as argument and
+ * reads/writes the information from/to the stream, thus enabling storing
+ * flags to files. The other set takes an argument of type
+ * <tt>vector<bool></tt>. This enables the user to temporarily store some
+ * flags, e.g. if another function needs them, and restore them afterwards.
+ *
+ *
+ * <h3>User flags and data</h3>
+ *
+ * A triangulation offers one bit per line, quad, etc for user flags. This
+ * field can be accessed as all other data using iterators. Normally, this
+ * user flag is used if an algorithm walks over all cells and needs
+ * information whether another cell, e.g. a neighbor, has already been
+ * processed. See @ref GlossUserFlags "the glossary for more information".
+ *
+ * There is another set of user data, which can be either an <tt>unsigned
+ * int</tt> or a <tt>void *</tt>, for each line, quad, etc. You can access
+ * these through the functions listed under <tt>User data</tt> in the accessor
+ * classes. Again, see @ref GlossUserData "the glossary for more information".
+ *
+ * The value of these user indices or pointers is @p NULL by default. Note
+ * that the pointers are not inherited to children upon refinement. Still,
+ * after a remeshing they are available on all cells, where they were set on
+ * the previous mesh.
+ *
+ * The usual warning about the missing type safety of @p void pointers are
+ * obviously in place here; responsibility for correctness of types etc lies
+ * entirely with the user of the pointer.
+ *
+ * @note User pointers and user indices are stored in the same place. In order
+ * to avoid unwanted conversions, Triangulation checks which one of them is in
+ * use and does not allow access to the other one, until clear_user_data() has
+ * been called.
+ *
+ *
+ * <h3>Boundary approximation</h3>
+ *
+ * You can specify a boundary function for each boundary component. If a new
+ * vertex is created on a side or face at the boundary, this function is used
+ * to compute where it will be placed. The boundary indicator of the face will
+ * be used to determine the proper component. See Boundary for the details.
+ * Usage with the Triangulation object is then like this (let @p Ball be a
+ * class derived from Boundary<tt><2></tt>):
  *
  *   @code
  *     void main () {
@@ -956,38 +896,35 @@ namespace internal
  *     };
  *   @endcode
  *
- *   You should take note of one caveat: if you have concave
- *   boundaries, you must make sure that a new boundary vertex does
- *   not lie too much inside the cell which is to be refined. The
- *   reason is that the center vertex is placed at the point which is
- *   the arithmetic mean of the vertices of the original cell.
- *   Therefore if your new boundary vertex is too near the center of
- *   the old quadrilateral or hexahedron, the distance to the midpoint
- *   vertex will become too small, thus generating distorted
- *   cells. This issue is discussed extensively in
- *   @ref GlossDistorted "distorted cells".
- *
- *
- *   <h3>Getting notice when a triangulation changes</h3>
- *
- *   There are cases where one object would like to know whenever a triangulation
- *   is being refined, copied, or modified in a number of other ways. This
- *   could of course be achieved if, in your user code, you tell every
- *   such object whenever you are about to refine the triangulation, but this
- *   will get tedious and is error prone. The Triangulation class implements
- *   a more elegant way to achieve this: signals.
- *
- *   In essence, a signal is an object (a member of the Triangulation class)
- *   that another object can connect to. A connection is in essence that
- *   the connecting object passes a function object taking a certain number
- *   and kind of arguments. Whenever the owner of the signal wants to
- *   indicate a certain kind of event, it 'triggers' the signal, which in
- *   turn means that all connections of the signal are triggered: in other
- *   word, the function objects are executed and can take the action that
- *   is necessary.
- *
- *   As a simple example, the following code will print something to the
- *   output every time the triangulation has just been refined:
+ * You should take note of one caveat: if you have concave boundaries, you
+ * must make sure that a new boundary vertex does not lie too much inside the
+ * cell which is to be refined. The reason is that the center vertex is placed
+ * at the point which is the arithmetic mean of the vertices of the original
+ * cell. Therefore if your new boundary vertex is too near the center of the
+ * old quadrilateral or hexahedron, the distance to the midpoint vertex will
+ * become too small, thus generating distorted cells. This issue is discussed
+ * extensively in @ref GlossDistorted "distorted cells".
+ *
+ *
+ * <h3>Getting notice when a triangulation changes</h3>
+ *
+ * There are cases where one object would like to know whenever a
+ * triangulation is being refined, copied, or modified in a number of other
+ * ways. This could of course be achieved if, in your user code, you tell
+ * every such object whenever you are about to refine the triangulation, but
+ * this will get tedious and is error prone. The Triangulation class
+ * implements a more elegant way to achieve this: signals.
+ *
+ * In essence, a signal is an object (a member of the Triangulation class)
+ * that another object can connect to. A connection is in essence that the
+ * connecting object passes a function object taking a certain number and kind
+ * of arguments. Whenever the owner of the signal wants to indicate a certain
+ * kind of event, it 'triggers' the signal, which in turn means that all
+ * connections of the signal are triggered: in other word, the function
+ * objects are executed and can take the action that is necessary.
+ *
+ * As a simple example, the following code will print something to the output
+ * every time the triangulation has just been refined:
  *   @code
  *     void f() {
  *       std::cout << "Triangulation has been refined." << std::endl;
@@ -999,21 +936,21 @@ namespace internal
  *       triangulation.signals.post_refinement.connect (&f);
  *       triangulation.refine_global (2);
  *   @endcode
- *   This code will produce output twice, once for each refinement cycle.
- *
- *   A more interesting application would be the following, akin to what
- *   the FEValues class does. This class stores a pointer to a triangulation
- *   and also an iterator to the cell last handled (so that it can compare
- *   the current cell with the previous one and, for example, decide that
- *   there is no need to re-compute the Jacobian matrix if the new cell
- *   is a simple translation of the previous one). However, whenever the
- *   triangulation is modified, the iterator to the previously handled
- *   cell needs to be invalidated since it now no longer points to any
- *   useful cell (or, at the very least, points to something that may not
- *   necessarily resemble the cells previously handled). The code would
- *   look something like this (the real code has some more error checking
- *   and has to handle the case that subsequent cells might actually belong to
- *   different triangulation, but that is of no concern to us here):
+ * This code will produce output twice, once for each refinement cycle.
+ *
+ * A more interesting application would be the following, akin to what the
+ * FEValues class does. This class stores a pointer to a triangulation and
+ * also an iterator to the cell last handled (so that it can compare the
+ * current cell with the previous one and, for example, decide that there is
+ * no need to re-compute the Jacobian matrix if the new cell is a simple
+ * translation of the previous one). However, whenever the triangulation is
+ * modified, the iterator to the previously handled cell needs to be
+ * invalidated since it now no longer points to any useful cell (or, at the
+ * very least, points to something that may not necessarily resemble the cells
+ * previously handled). The code would look something like this (the real code
+ * has some more error checking and has to handle the case that subsequent
+ * cells might actually belong to different triangulation, but that is of no
+ * concern to us here):
  *   @code
  *     template <int dim>
  *     class FEValues {
@@ -1050,182 +987,174 @@ namespace internal
  *       previous_cell = Triangulation<dim>::active_cell_iterator();
  *     }
  *   @endcode
- *   Here, whenever the triangulation is refined, it triggers the post-refinement
- *   signal which calls the function object attached to it. This function object
- *   is the member function <code>FEValues<dim>::invalidate_previous_cell</code>
- *   where we have bound the single argument (the <code>this</code> pointer of
- *   a member function that otherwise takes no arguments) to the <code>this</code>
- *   pointer of the FEValues object. Note how here there is no need for the code
- *   that owns the triangulation and the FEValues object to inform the latter if
- *   the former is refined. (In practice, the function would want to connect to
- *   some of the other signals that the triangulation offers as well, in particular
- *   to creation and deletion signals.)
- *
- *   The Triangulation class has a variety of signals that indicate different
- *   actions by which the triangulation can modify itself and potentially
- *   require follow-up action elsewhere:
- *   - creation: This signal is triggered whenever the
- *     Triangulation::create_triangulation or Triangulation::copy_triangulation
- *     is called. This signal is also triggered when loading a
- *     triangulation from an archive via Triangulation::load.
- *   - pre-refinement: This signal is triggered at the beginning
- *     of execution of the Triangulation::execute_coarsening_and_refinement
- *     function (which is itself called by other functions such as
- *     Triangulation::refine_global). At the time this signal is triggered,
- *     the triangulation is still unchanged.
- *   - post-refinement: This signal is triggered at the end
- *     of execution of the Triangulation::execute_coarsening_and_refinement
- *     function when the triangulation has reached its final state
- *   - copy: This signal is triggered whenever the triangulation owning
- *     the signal is copied by another triangulation using
- *     Triangulation::copy_triangulation (i.e. it is triggered on the <i>old</i>
- *     triangulation, but the new one is passed as a argument).
- *   - clear: This signal is triggered whenever the Triangulation::clear
- *     function is called. This signal is also triggered when loading a
- *     triangulation from an archive via Triangulation::load as the previous
- *     content of the triangulation is first destroyed.
- *   - any_change: This is a catch-all signal that is triggered whenever the
- *     create, post_refinement, or clear signals are triggered. In effect, it
- *     can be used to indicate to an object connected to the signal that the
- *     triangulation has been changed, whatever the exact cause of the change.
- *
- *
- *   <h3>Serializing (loading or storing) triangulations</h3>
- *
- *   Like many other classes in deal.II, the Triangulation class can stream
- *   its contents to an archive using BOOST's serialization facilities. The
- *   data so stored can later be retrieved again from the archive to restore
- *   the contents of this object. This facility is frequently used to save the
- *   state of a program to disk for possible later resurrection, often in the
- *   context of checkpoint/restart strategies for long running computations or
- *   on computers that aren't very reliable (e.g. on very large clusters where
- *   individual nodes occasionally fail and then bring down an entire MPI
- *   job).
- *
- *   For technical reasons, writing and restoring a Triangulation object is
- *   not-trivial. The primary reason is that unlike many other objects,
- *   triangulations rely on many other objects to which they store pointers or
- *   with which they interace; for example, triangulations store pointers to
- *   objects describing boundaries and manifolds, and they have signals that
- *   store pointers to other objects so they can be notified of changes in the
- *   triangulation (see the section on signals in this introduction). As
- *   objects that are re-loaded at a later time do not usually end up at the
- *   same location in memory as they were when they were saved, dealing with
- *   pointers to other objects is difficult.
- *
- *   For these reasons, saving a triangulation to an archive does not store
- *   all information, but only certain parts. More specifically, the
- *   information that is stored is everything that defines the mesh such as
- *   vertex locations, vertex indices, how vertices are connected to cells,
- *   boundary indicators, subdomain ids, material ids, etc. On the other hand,
- *   the following information is not stored:
- *   - signals
- *   - pointers to boundary objects previously set using
- *     Triangulation::set_boundary
- *   On the other hand, since these are objects that are usually set in
- *   user code, they can typically easily be set again in that part of your
- *   code in which you re-load triangulations.
- *
- *   In a sense, this approach to serialization means that re-loading a
- *   triangulation is more akin to calling the
- *   Triangulation::create_triangulation function and filling it with some
- *   additional content, as that function also does not touch the signals and
- *   boundary objects that belong to this triangulation. In keeping with this
- *   analogy, the Triangulation::load function also triggers the same kinds of
- *   signal as Triangulation::create_triangulation.
- *
- *
- *   <h3>Technical details</h3>
- *
- *   <h4>Algorithms for mesh regularization and smoothing upon refinement</h4>
- *
- *   We chose an inductive point of view: since upon creation of the
- *   triangulation all cells are on the same level, all regularity assumptions
- *   regarding the maximum difference in level of cells sharing a common face,
- *   edge or vertex hold. Since we use the regularization and smoothing in
- *   each step of the mesh history, when coming to the point of refining it
- *   further the assumptions also hold.
- *
- *   The regularization and smoothing is done in the
- *   @p prepare_coarsening_and_refinement function, which is called by
- *   @p execute_coarsening_and_refinement at the very beginning.  It
- *   decides which additional cells to flag for refinement by looking
- *   at the old grid and the refinement flags for each cell.
- *
- *   <ul>
- *   <li> <em>Regularization:</em> The algorithm walks over all cells checking
- *     whether the present cell is flagged for refinement and a neighbor of the
- *     present cell is refined once less than the present one. If so, flag the
- *     neighbor for refinement. Because of the induction above, there may be no
- *     neighbor with level two less than the present one.
- *
- *     The neighbor thus flagged for refinement may induce more cells which need
- *     to be refined. However, such cells which need additional refinement always
- *     are on one level lower than the present one, so we can get away with only
- *     one sweep over all cells if we do the loop in the reverse way, starting
- *     with those on the highest level. This way, we may flag additional cells
- *     on lower levels, but if these induce more refinement needed, this is
- *     performed later on when we visit them in out backward running loop.
- *
- *   <li> <em>Smoothing:</em>
- *     <ul>
- *     <li> @p limit_level_difference_at_vertices:
- *       First a list is set up which stores for each vertex
- *       the highest level one of the adjacent cells belongs to. Now, since we did
- *       smoothing in the previous refinement steps also, each cell may only have
- *       vertices with levels at most one greater than the level of the present
- *       cell.
- *
- *       However, if we store the level plus one for cells marked for refinement,
- *       we may end up with cells which have vertices of level two greater than
- *       the cells level. We need to refine this cell also, and need thus also
- *       update the levels of its vertices. This itself may lead to cells needing
- *       refinement, but these are on lower levels, as above, which is why we
- *       may do all kinds of additional flagging in one loop only.
- *
- *     <li> @p eliminate_unrefined_islands:
- *       For each cell we count the number of neighbors which are refined or
- *       flagged for refinement. If this exceeds the number of neighbors
- *       which are not refined and not flagged for refinement, then the current
- *       cell is flagged for
- *       refinement. Since this may lead to cells on the same level which also
- *       will need refinement, we will need additional loops of regularization
- *       and smoothing over all cells until nothing changes any more.
- *
- *     <li> <tt>eliminate_refined_*_islands</tt>:
- *       This one does much the same as the above one, but for coarsening. If
- *       a cell is flagged for refinement or if all of its children are active
- *       and if the number of neighbors which are either active and not flagged
- *       for refinement, or not active but all children flagged for coarsening
- *       equals the total number of neighbors, then this cell's children
- *       are flagged for coarsening or (if this cell was flagged for refinement)
- *       the refine flag is cleared.
- *
- *       For a description of the distinction between the two versions of the
- *       flag see above in the section about mesh smoothing in the general part
- *       of this classes description.
- *
- *       The same applies as above: several loops may be necessary.
- *     </ul>
- *   </ul>
- *
- *   Regularization and smoothing are a bit complementary in that we check
- *   whether we need to set additional refinement flags when being on a cell
- *   flagged for refinement (regularization) or on a cell not flagged for
- *   refinement. This makes readable programming easier.
- *
- *   All the described algorithms apply only for more than one space dimension,
- *   since for one dimension no restrictions apply. It may be necessary to
- *   apply some smoothing for multigrid algorithms, but this has to be decided
- *   upon later.
- *
- *
- *   <h3>Warning</h3>
- *
- *   It seems impossible to preserve @p constness of a triangulation through
- *   iterator usage. Thus, if you declare pointers to a @p const triangulation
- *   object, you should be well aware that you might involuntarily alter the
- *   data stored in the triangulation.
+ * Here, whenever the triangulation is refined, it triggers the post-
+ * refinement signal which calls the function object attached to it. This
+ * function object is the member function
+ * <code>FEValues<dim>::invalidate_previous_cell</code> where we have bound
+ * the single argument (the <code>this</code> pointer of a member function
+ * that otherwise takes no arguments) to the <code>this</code> pointer of the
+ * FEValues object. Note how here there is no need for the code that owns the
+ * triangulation and the FEValues object to inform the latter if the former is
+ * refined. (In practice, the function would want to connect to some of the
+ * other signals that the triangulation offers as well, in particular to
+ * creation and deletion signals.)
+ *
+ * The Triangulation class has a variety of signals that indicate different
+ * actions by which the triangulation can modify itself and potentially
+ * require follow-up action elsewhere: - creation: This signal is triggered
+ * whenever the Triangulation::create_triangulation or
+ * Triangulation::copy_triangulation is called. This signal is also triggered
+ * when loading a triangulation from an archive via Triangulation::load. -
+ * pre-refinement: This signal is triggered at the beginning of execution of
+ * the Triangulation::execute_coarsening_and_refinement function (which is
+ * itself called by other functions such as Triangulation::refine_global). At
+ * the time this signal is triggered, the triangulation is still unchanged. -
+ * post-refinement: This signal is triggered at the end of execution of the
+ * Triangulation::execute_coarsening_and_refinement function when the
+ * triangulation has reached its final state - copy: This signal is triggered
+ * whenever the triangulation owning the signal is copied by another
+ * triangulation using Triangulation::copy_triangulation (i.e. it is triggered
+ * on the <i>old</i> triangulation, but the new one is passed as a argument).
+ * - clear: This signal is triggered whenever the Triangulation::clear
+ * function is called. This signal is also triggered when loading a
+ * triangulation from an archive via Triangulation::load as the previous
+ * content of the triangulation is first destroyed. - any_change: This is a
+ * catch-all signal that is triggered whenever the create, post_refinement, or
+ * clear signals are triggered. In effect, it can be used to indicate to an
+ * object connected to the signal that the triangulation has been changed,
+ * whatever the exact cause of the change.
+ *
+ *
+ * <h3>Serializing (loading or storing) triangulations</h3>
+ *
+ * Like many other classes in deal.II, the Triangulation class can stream its
+ * contents to an archive using BOOST's serialization facilities. The data so
+ * stored can later be retrieved again from the archive to restore the
+ * contents of this object. This facility is frequently used to save the state
+ * of a program to disk for possible later resurrection, often in the context
+ * of checkpoint/restart strategies for long running computations or on
+ * computers that aren't very reliable (e.g. on very large clusters where
+ * individual nodes occasionally fail and then bring down an entire MPI job).
+ *
+ * For technical reasons, writing and restoring a Triangulation object is not-
+ * trivial. The primary reason is that unlike many other objects,
+ * triangulations rely on many other objects to which they store pointers or
+ * with which they interace; for example, triangulations store pointers to
+ * objects describing boundaries and manifolds, and they have signals that
+ * store pointers to other objects so they can be notified of changes in the
+ * triangulation (see the section on signals in this introduction). As objects
+ * that are re-loaded at a later time do not usually end up at the same
+ * location in memory as they were when they were saved, dealing with pointers
+ * to other objects is difficult.
+ *
+ * For these reasons, saving a triangulation to an archive does not store all
+ * information, but only certain parts. More specifically, the information
+ * that is stored is everything that defines the mesh such as vertex
+ * locations, vertex indices, how vertices are connected to cells, boundary
+ * indicators, subdomain ids, material ids, etc. On the other hand, the
+ * following information is not stored: - signals - pointers to boundary
+ * objects previously set using Triangulation::set_boundary On the other hand,
+ * since these are objects that are usually set in user code, they can
+ * typically easily be set again in that part of your code in which you re-
+ * load triangulations.
+ *
+ * In a sense, this approach to serialization means that re-loading a
+ * triangulation is more akin to calling the
+ * Triangulation::create_triangulation function and filling it with some
+ * additional content, as that function also does not touch the signals and
+ * boundary objects that belong to this triangulation. In keeping with this
+ * analogy, the Triangulation::load function also triggers the same kinds of
+ * signal as Triangulation::create_triangulation.
+ *
+ *
+ * <h3>Technical details</h3>
+ *
+ * <h4>Algorithms for mesh regularization and smoothing upon refinement</h4>
+ *
+ * We chose an inductive point of view: since upon creation of the
+ * triangulation all cells are on the same level, all regularity assumptions
+ * regarding the maximum difference in level of cells sharing a common face,
+ * edge or vertex hold. Since we use the regularization and smoothing in each
+ * step of the mesh history, when coming to the point of refining it further
+ * the assumptions also hold.
+ *
+ * The regularization and smoothing is done in the @p
+ * prepare_coarsening_and_refinement function, which is called by @p
+ * execute_coarsening_and_refinement at the very beginning.  It decides which
+ * additional cells to flag for refinement by looking at the old grid and the
+ * refinement flags for each cell.
+ *
+ * <ul>
+ * <li> <em>Regularization:</em> The algorithm walks over all cells checking
+ * whether the present cell is flagged for refinement and a neighbor of the
+ * present cell is refined once less than the present one. If so, flag the
+ * neighbor for refinement. Because of the induction above, there may be no
+ * neighbor with level two less than the present one.
+ *
+ * The neighbor thus flagged for refinement may induce more cells which need
+ * to be refined. However, such cells which need additional refinement always
+ * are on one level lower than the present one, so we can get away with only
+ * one sweep over all cells if we do the loop in the reverse way, starting
+ * with those on the highest level. This way, we may flag additional cells on
+ * lower levels, but if these induce more refinement needed, this is performed
+ * later on when we visit them in out backward running loop.
+ *
+ * <li> <em>Smoothing:</em>
+ * <ul>
+ * <li> @p limit_level_difference_at_vertices: First a list is set up which
+ * stores for each vertex the highest level one of the adjacent cells belongs
+ * to. Now, since we did smoothing in the previous refinement steps also, each
+ * cell may only have vertices with levels at most one greater than the level
+ * of the present cell.
+ *
+ * However, if we store the level plus one for cells marked for refinement, we
+ * may end up with cells which have vertices of level two greater than the
+ * cells level. We need to refine this cell also, and need thus also update
+ * the levels of its vertices. This itself may lead to cells needing
+ * refinement, but these are on lower levels, as above, which is why we may do
+ * all kinds of additional flagging in one loop only.
+ *
+ * <li> @p eliminate_unrefined_islands: For each cell we count the number of
+ * neighbors which are refined or flagged for refinement. If this exceeds the
+ * number of neighbors which are not refined and not flagged for refinement,
+ * then the current cell is flagged for refinement. Since this may lead to
+ * cells on the same level which also will need refinement, we will need
+ * additional loops of regularization and smoothing over all cells until
+ * nothing changes any more.
+ *
+ * <li> <tt>eliminate_refined_*_islands</tt>: This one does much the same as
+ * the above one, but for coarsening. If a cell is flagged for refinement or
+ * if all of its children are active and if the number of neighbors which are
+ * either active and not flagged for refinement, or not active but all
+ * children flagged for coarsening equals the total number of neighbors, then
+ * this cell's children are flagged for coarsening or (if this cell was
+ * flagged for refinement) the refine flag is cleared.
+ *
+ * For a description of the distinction between the two versions of the flag
+ * see above in the section about mesh smoothing in the general part of this
+ * classes description.
+ *
+ * The same applies as above: several loops may be necessary.
+ * </ul>
+ * </ul>
+ *
+ * Regularization and smoothing are a bit complementary in that we check
+ * whether we need to set additional refinement flags when being on a cell
+ * flagged for refinement (regularization) or on a cell not flagged for
+ * refinement. This makes readable programming easier.
+ *
+ * All the described algorithms apply only for more than one space dimension,
+ * since for one dimension no restrictions apply. It may be necessary to apply
+ * some smoothing for multigrid algorithms, but this has to be decided upon
+ * later.
+ *
+ *
+ * <h3>Warning</h3>
+ *
+ * It seems impossible to preserve @p constness of a triangulation through
+ * iterator usage. Thus, if you declare pointers to a @p const triangulation
+ * object, you should be well aware that you might involuntarily alter the
+ * data stored in the triangulation.
  *
  * @ingroup grid aniso
  * @author Wolfgang Bangerth, 1998; Ralf Hartmann, 2005
@@ -1236,194 +1165,186 @@ class Triangulation : public Subscriptor
 private:
 
   /**
-   * An internal typedef to make
-   * the definition of the iterator
-   * classes simpler.
+   * An internal typedef to make the definition of the iterator classes
+   * simpler.
    */
   typedef dealii::internal::Triangulation::Iterators<dim, spacedim> IteratorSelector;
 
 public:
   /**
-   * Default manifold object. This is used
-   * for those objects for which no
-   * boundary description has been explicitly
-   * set using set_manifold().
+   * Default manifold object. This is used for those objects for which no
+   * boundary description has been explicitly set using set_manifold().
    */
   static const StraightBoundary<dim,spacedim> straight_boundary;
 
   /**
-   * Declare some symbolic names
-   * for mesh smoothing
-   * algorithms. The meaning of
-   * these flags is documented in
-   * the Triangulation class.
+   * Declare some symbolic names for mesh smoothing algorithms. The meaning of
+   * these flags is documented in the Triangulation class.
    */
   enum MeshSmoothing
   {
     /**
-     * No mesh smoothing at all, except that meshes have to remain one-irregular.
+     * No mesh smoothing at all, except that meshes have to remain one-
+     * irregular.
      */
     none                               = 0x0,
     /**
-     *     It can be shown, that degradation of approximation occurs if the
-     *     triangulation contains vertices which are member of cells with levels
-     *     differing by more than one. One such example is the following:
+     * It can be shown, that degradation of approximation occurs if the
+     * triangulation contains vertices which are member of cells with levels
+     * differing by more than one. One such example is the following:
      *
-     *     @image html limit_level_difference_at_vertices.png ""
+     * @image html limit_level_difference_at_vertices.png ""
      *
-     *     It would seem that in two space dimensions, the maximum jump in levels
-     *     between cells sharing a common vertex is two (as in the example
-     *     above). However, this is not true if more than four cells meet at a
-     *     vertex. It is not uncommon that a coarse (initial) mesh contains
-     *     vertices at which six or even eight cells meet, when small features of
-     *     the domain have to be resolved even on the coarsest mesh. In that case,
-     *     the maximum difference in levels is three or four, respectively. The
-     *     problem gets even worse in three space dimensions.
+     * It would seem that in two space dimensions, the maximum jump in levels
+     * between cells sharing a common vertex is two (as in the example above).
+     * However, this is not true if more than four cells meet at a vertex. It
+     * is not uncommon that a coarse (initial) mesh contains vertices at which
+     * six or even eight cells meet, when small features of the domain have to
+     * be resolved even on the coarsest mesh. In that case, the maximum
+     * difference in levels is three or four, respectively. The problem gets
+     * even worse in three space dimensions.
      *
-     *     Looking at an interpolation of the second derivative of the finite
-     *     element solution (assuming bilinear finite elements), one sees that the
-     *     numerical solution is almost totally wrong, compared with the true
-     *     second derivative. Indeed, on regular meshes, there exist sharp
-     *     estimations that the H<sup>2</sup>-error is only of order one, so we should not be
-     *     surprised; however, the numerical solution may show a value for the
-     *     second derivative which may be a factor of ten away from the true
-     *     value. These problems are located on the small cell adjacent to the
-     *     center vertex, where cells of non-subsequent levels meet, as well as on
-     *     the upper and right neighbor of this cell (but with a less degree of
-     *     deviation from the true value).
+     * Looking at an interpolation of the second derivative of the finite
+     * element solution (assuming bilinear finite elements), one sees that the
+     * numerical solution is almost totally wrong, compared with the true
+     * second derivative. Indeed, on regular meshes, there exist sharp
+     * estimations that the H<sup>2</sup>-error is only of order one, so we
+     * should not be surprised; however, the numerical solution may show a
+     * value for the second derivative which may be a factor of ten away from
+     * the true value. These problems are located on the small cell adjacent
+     * to the center vertex, where cells of non-subsequent levels meet, as
+     * well as on the upper and right neighbor of this cell (but with a less
+     * degree of deviation from the true value).
      *
-     *     If the smoothing indicator given to the constructor contains the bit for
-     *     #limit_level_difference_at_vertices, situations as the above one are
-     *     eliminated by also marking the lower left cell for refinement.
+     * If the smoothing indicator given to the constructor contains the bit
+     * for #limit_level_difference_at_vertices, situations as the above one
+     * are eliminated by also marking the lower left cell for refinement.
      *
-     *     In case of anisotropic refinement, the level of a cell is not linked to
-     *     the refinement of a cell as directly as in case of isotropic
-     *     refinement. Furthermore, a cell can be strongly refined in one
-     *     direction and not or at least much less refined in another. Therefore,
-     *     it is very difficult to decide, which cases should be excluded from the
-     *     refinement process. As a consequence, when using anisotropic
-     *     refinement, the #limit_level_difference_at_vertices flag must not be
-     *     set. On the other hand, the implementation of multigrid methods in
-     *     deal.II requires that this bit be set.
+     * In case of anisotropic refinement, the level of a cell is not linked to
+     * the refinement of a cell as directly as in case of isotropic
+     * refinement. Furthermore, a cell can be strongly refined in one
+     * direction and not or at least much less refined in another. Therefore,
+     * it is very difficult to decide, which cases should be excluded from the
+     * refinement process. As a consequence, when using anisotropic
+     * refinement, the #limit_level_difference_at_vertices flag must not be
+     * set. On the other hand, the implementation of multigrid methods in
+     * deal.II requires that this bit be set.
      */
     limit_level_difference_at_vertices = 0x1,
     /**
-     *     Single cells which are not refined and are surrounded by cells which are
-     *     refined usually also lead to a sharp decline in approximation properties
-     *     locally. The reason is that the nodes on the faces between unrefined and
-     *     refined cells are not real degrees of freedom but carry constraints. The
-     *     patch without additional degrees of freedom is thus significantly larger
-     *     then the unrefined cell itself. If in the parameter passed to the
-     *     constructor the bit for #eliminate_unrefined_islands is set, all cells
-     *     which are not flagged for refinement but which are surrounded by more
-     *     refined cells than unrefined cells are flagged for refinement. Cells
-     *     which are not yet refined but flagged for that are accounted for the
-     *     number of refined neighbors. Cells on the boundary are not accounted for
-     *     at all. An unrefined island is, by this definition
-     *     also a cell which (in 2D) is surrounded by three refined cells and one
-     *     unrefined one, or one surrounded by two refined cells, one unrefined one
-     *     and is at the boundary on one side. It is thus not a true island, as the
-     *     name of the flag may indicate. However, no better name came to mind to
-     *     the author by now.
-      */
+     * Single cells which are not refined and are surrounded by cells which
+     * are refined usually also lead to a sharp decline in approximation
+     * properties locally. The reason is that the nodes on the faces between
+     * unrefined and refined cells are not real degrees of freedom but carry
+     * constraints. The patch without additional degrees of freedom is thus
+     * significantly larger then the unrefined cell itself. If in the
+     * parameter passed to the constructor the bit for
+     * #eliminate_unrefined_islands is set, all cells which are not flagged
+     * for refinement but which are surrounded by more refined cells than
+     * unrefined cells are flagged for refinement. Cells which are not yet
+     * refined but flagged for that are accounted for the number of refined
+     * neighbors. Cells on the boundary are not accounted for at all. An
+     * unrefined island is, by this definition also a cell which (in 2D) is
+     * surrounded by three refined cells and one unrefined one, or one
+     * surrounded by two refined cells, one unrefined one and is at the
+     * boundary on one side. It is thus not a true island, as the name of the
+     * flag may indicate. However, no better name came to mind to the author
+     * by now.
+     */
     eliminate_unrefined_islands        = 0x2,
     /**
-     *     A triangulation of patch level 1 consists of patches, i.e. of
-     *     cells that are refined once. This flag ensures that a mesh of
-     *     patch level 1 is still of patch level 1 after coarsening and
-     *     refinement. It is, however, the user's responsibility to ensure
-     *     that the mesh is of patch level 1 before calling
-     *     Triangulation::execute_coarsening_and_refinement() the first time. The easiest
-     *     way to achieve this is by calling global_refine(1) straight
-     *     after creation of the triangulation.  It follows that if at
-     *     least one of the children of a cell is or will be refined than
-     *     all children need to be refined. If the #patch_level_1 flag
-     *     is set, than the flags #eliminate_unrefined_islands,
-     *     #eliminate_refined_inner_islands and
-     *     #eliminate_refined_boundary_islands will be ignored as they will
-     *     be fulfilled automatically.
+     * A triangulation of patch level 1 consists of patches, i.e. of cells
+     * that are refined once. This flag ensures that a mesh of patch level 1
+     * is still of patch level 1 after coarsening and refinement. It is,
+     * however, the user's responsibility to ensure that the mesh is of patch
+     * level 1 before calling
+     * Triangulation::execute_coarsening_and_refinement() the first time. The
+     * easiest way to achieve this is by calling global_refine(1) straight
+     * after creation of the triangulation.  It follows that if at least one
+     * of the children of a cell is or will be refined than all children need
+     * to be refined. If the #patch_level_1 flag is set, than the flags
+     * #eliminate_unrefined_islands, #eliminate_refined_inner_islands and
+     * #eliminate_refined_boundary_islands will be ignored as they will be
+     * fulfilled automatically.
      */
     patch_level_1                      = 0x4,
     /**
-     *     Each coarse grid cell is refined at least once, i.e. the
-     *     triangulation might have active cells on level 1 but not on
-     *     level 0. This flag ensures that a mesh which has
-     *     coarsest_level_1 has still coarsest_level_1 after coarsening
-     *     and refinement. It is, however, the user's responsibility to
-     *     ensure that the mesh has coarsest_level_1 before calling
-     *     execute_coarsening_and_refinement the first time. The easiest
-     *     way to achieve this is by calling global_refine(1) straight
-     *     after creation of the triangulation. It follows that active
-     *     cells on level 1 may not be coarsenend.
+     * Each coarse grid cell is refined at least once, i.e. the triangulation
+     * might have active cells on level 1 but not on level 0. This flag
+     * ensures that a mesh which has coarsest_level_1 has still
+     * coarsest_level_1 after coarsening and refinement. It is, however, the
+     * user's responsibility to ensure that the mesh has coarsest_level_1
+     * before calling execute_coarsening_and_refinement the first time. The
+     * easiest way to achieve this is by calling global_refine(1) straight
+     * after creation of the triangulation. It follows that active cells on
+     * level 1 may not be coarsenend.
      *
-     *     The main use of this flag is to ensure that each cell has at least one
-     *     neighbor in each coordinate direction (i.e. each cell has at least a
-     *     left or right, and at least an upper or lower neighbor in 2d). This is
-     *     a necessary precondition for some algorihms that compute finite
-     *     differences between cells. The DerivativeApproximation class is one of
-     *     these algorithms that require that a triangulation is coarsest_level_1
-     *     unless all cells already have at least one neighbor in each coordinate
-     *     direction on the coarsest level.
+     * The main use of this flag is to ensure that each cell has at least one
+     * neighbor in each coordinate direction (i.e. each cell has at least a
+     * left or right, and at least an upper or lower neighbor in 2d). This is
+     * a necessary precondition for some algorihms that compute finite
+     * differences between cells. The DerivativeApproximation class is one of
+     * these algorithms that require that a triangulation is coarsest_level_1
+     * unless all cells already have at least one neighbor in each coordinate
+     * direction on the coarsest level.
      */
     coarsest_level_1                   = 0x8,
     /**
-     *     This flag is not included in @p maximum_smoothing. The flag is
-     *     concerned with the following case: consider the case that an
-     *     unrefined and a refined cell share a common face and that one
-     *     of the children of the refined cell along the common face is
-     *     flagged for further refinement. In that case, the resulting
-     *     mesh would have more than one hanging node along one or more of
-     *     the edges of the triangulation, a situation that is not
-     *     allowed. Consequently, in order to perform the refinement, the
-     *     coarser of the two original cells is also going to be refined.
+     * This flag is not included in @p maximum_smoothing. The flag is
+     * concerned with the following case: consider the case that an unrefined
+     * and a refined cell share a common face and that one of the children of
+     * the refined cell along the common face is flagged for further
+     * refinement. In that case, the resulting mesh would have more than one
+     * hanging node along one or more of the edges of the triangulation, a
+     * situation that is not allowed. Consequently, in order to perform the
+     * refinement, the coarser of the two original cells is also going to be
+     * refined.
      *
-     *     However, in many cases it is sufficient to refine the coarser
-     *     of the two original cells in an anisotropic way to avoid the
-     *     case of multiple hanging vertices on a single edge. Doing only
-     *     the minimal anisotropic refinement can save cells and degrees
-     *     of freedom. By specifying this flag, the library can produce
-     *     these anisotropic refinements.
+     * However, in many cases it is sufficient to refine the coarser of the
+     * two original cells in an anisotropic way to avoid the case of multiple
+     * hanging vertices on a single edge. Doing only the minimal anisotropic
+     * refinement can save cells and degrees of freedom. By specifying this
+     * flag, the library can produce these anisotropic refinements.
      *
-     *     The flag is not included by default since it may lead to
-     *     anisotropically refined meshes even though no cell has ever
-     *     been refined anisotropically explicitly by a user command. This
-     *     surprising fact may lead to programs that do the wrong thing
-     *     since they are not written for the additional cases that can
-     *     happen with anisotropic meshes, see the discussion in the
-     *     introduction to step-30.
+     * The flag is not included by default since it may lead to
+     * anisotropically refined meshes even though no cell has ever been
+     * refined anisotropically explicitly by a user command. This surprising
+     * fact may lead to programs that do the wrong thing since they are not
+     * written for the additional cases that can happen with anisotropic
+     * meshes, see the discussion in the introduction to step-30.
      */
     allow_anisotropic_smoothing        = 0x10,
     /**
-     *     This algorithm seeks for isolated cells which are refined or flagged
-     *     for refinement. This definition is unlike that for
-     *     #eliminate_unrefined_islands, which would mean that an island is
-     *     defined as a cell which
-     *     is refined but more of its neighbors are not refined than are refined.
-     *     For example, in 2D, a cell's refinement would be reverted if at most
-     *     one of its neighbors is also refined (or refined but flagged for
-     *     coarsening).
+     * This algorithm seeks for isolated cells which are refined or flagged
+     * for refinement. This definition is unlike that for
+     * #eliminate_unrefined_islands, which would mean that an island is
+     * defined as a cell which is refined but more of its neighbors are not
+     * refined than are refined. For example, in 2D, a cell's refinement would
+     * be reverted if at most one of its neighbors is also refined (or refined
+     * but flagged for coarsening).
      *
-     *     The reason for the change in definition of an island is, that this
-     *     option would be a bit dangerous, since if you consider a
-     *     chain of refined cells (e.g. along a kink in the solution), the cells
-     *     at the two ends would be coarsened, after which the next outermost cells
-     *     would need to be coarsened. Therefore, only one loop of flagging cells
-     *     like this could be done to avoid eating up the whole chain of refined
-     *     cells (`chain reaction'...).
+     * The reason for the change in definition of an island is, that this
+     * option would be a bit dangerous, since if you consider a chain of
+     * refined cells (e.g. along a kink in the solution), the cells at the two
+     * ends would be coarsened, after which the next outermost cells would
+     * need to be coarsened. Therefore, only one loop of flagging cells like
+     * this could be done to avoid eating up the whole chain of refined cells
+     * (`chain reaction'...).
      *
-     *     This algorithm also takes into account cells which are not actually
-     *     refined but are flagged for refinement. If necessary, it takes away the
-     *     refinement flag.
+     * This algorithm also takes into account cells which are not actually
+     * refined but are flagged for refinement. If necessary, it takes away the
+     * refinement flag.
      *
-     *     Actually there are two versions of this flag,
-     *     #eliminate_refined_inner_islands and #eliminate_refined_boundary_islands.
-     *     There first eliminates islands defined by the definition above which are
-     *     in the interior of the domain, while the second eliminates only those
-     *     islands if the cell is at the boundary. The reason for this split of
-     *     flags is that one often wants to eliminate such islands in the interior
-     *     while those at the boundary may well be wanted, for example if one
-     *     refines the mesh according to a criterion associated with a boundary
-     *     integral or if one has rough boundary data.
+     * Actually there are two versions of this flag,
+     * #eliminate_refined_inner_islands and
+     * #eliminate_refined_boundary_islands. There first eliminates islands
+     * defined by the definition above which are in the interior of the
+     * domain, while the second eliminates only those islands if the cell is
+     * at the boundary. The reason for this split of flags is that one often
+     * wants to eliminate such islands in the interior while those at the
+     * boundary may well be wanted, for example if one refines the mesh
+     * according to a criterion associated with a boundary integral or if one
+     * has rough boundary data.
      */
     eliminate_refined_inner_islands    = 0x100,
     /**
@@ -1432,66 +1353,63 @@ public:
      */
     eliminate_refined_boundary_islands = 0x200,
     /**
-     *     This flag prevents the occurrence of unrefined islands. In more detail:
-     *     It prohibits the coarsening of a cell if 'most of the neighbors' will
-     *     be refined after the step.
+     * This flag prevents the occurrence of unrefined islands. In more detail:
+     * It prohibits the coarsening of a cell if 'most of the neighbors' will
+     * be refined after the step.
      */
     do_not_produce_unrefined_islands   = 0x400,
 
     /**
-     *     This flag sums up all smoothing algorithms which may be performed upon
-     *     refinement by flagging some more cells for refinement.
+     * This flag sums up all smoothing algorithms which may be performed upon
+     * refinement by flagging some more cells for refinement.
      */
     smoothing_on_refinement            = (limit_level_difference_at_vertices |
                                           eliminate_unrefined_islands),
     /**
-     *     This flag sums up all smoothing algorithms which may be performed upon
-     *     coarsening by flagging some more cells for coarsening.
+     * This flag sums up all smoothing algorithms which may be performed upon
+     * coarsening by flagging some more cells for coarsening.
      */
     smoothing_on_coarsening            = (eliminate_refined_inner_islands |
                                           eliminate_refined_boundary_islands |
                                           do_not_produce_unrefined_islands),
 
     /**
-     *     This flag includes all the above ones and therefore combines all
-     *     smoothing algorithms implemented with the exception of
-     *     anisotropic smoothening.
+     * This flag includes all the above ones and therefore combines all
+     * smoothing algorithms implemented with the exception of anisotropic
+     * smoothening.
      */
     maximum_smoothing                  = 0xffff ^ allow_anisotropic_smoothing
   };
 
   /**
-   * A typedef that is used to to identify cell iterators. The
-   * concept of iterators is discussed at length in the
-   * @ref Iterators "iterators documentation module".
+   * A typedef that is used to to identify cell iterators. The concept of
+   * iterators is discussed at length in the @ref Iterators "iterators
+   * documentation module".
    *
-   * The current typedef identifies cells in a triangulation. The
-   * TriaIterator class works like a pointer that when you
-   * dereference it yields an object of type CellAccessor.
-   * CellAccessor is a class that identifies properties that
-   * are specific to cells in a triangulation, but it is derived
-   * (and consequently inherits) from TriaAccessor that describes
-   * what you can ask of more general objects (lines, faces, as
-   * well as cells) in a triangulation.
+   * The current typedef identifies cells in a triangulation. The TriaIterator
+   * class works like a pointer that when you dereference it yields an object
+   * of type CellAccessor. CellAccessor is a class that identifies properties
+   * that are specific to cells in a triangulation, but it is derived (and
+   * consequently inherits) from TriaAccessor that describes what you can ask
+   * of more general objects (lines, faces, as well as cells) in a
+   * triangulation.
    *
    * @ingroup Iterators
    */
   typedef TriaIterator      <CellAccessor<dim,spacedim>         > cell_iterator;
 
   /**
-   * A typedef that is used to to identify
-   * @ref GlossActive "active cell iterators". The
-   * concept of iterators is discussed at length in the
-   * @ref Iterators "iterators documentation module".
+   * A typedef that is used to to identify @ref GlossActive "active cell
+   * iterators". The concept of iterators is discussed at length in the @ref
+   * Iterators "iterators documentation module".
    *
    * The current typedef identifies active cells in a triangulation. The
-   * TriaActiveIterator class works like a pointer to active objects that when you
-   * dereference it yields an object of type CellAccessor.
-   * CellAccessor is a class that identifies properties that
-   * are specific to cells in a triangulation, but it is derived
-   * (and consequently inherits) from TriaAccessor that describes
-   * what you can ask of more general objects (lines, faces, as
-   * well as cells) in a triangulation.
+   * TriaActiveIterator class works like a pointer to active objects that when
+   * you dereference it yields an object of type CellAccessor. CellAccessor is
+   * a class that identifies properties that are specific to cells in a
+   * triangulation, but it is derived (and consequently inherits) from
+   * TriaAccessor that describes what you can ask of more general objects
+   * (lines, faces, as well as cells) in a triangulation.
    *
    * @ingroup Iterators
    */
@@ -1510,17 +1428,13 @@ public:
   typedef typename IteratorSelector::active_hex_iterator  active_hex_iterator;
 
   /**
-   *  Base class for refinement listeners.
-   *  Other classes, which need to be
-   *  informed about refinements of the
-   *  Triangulation,
-   *  can be derived from
-   *  RefinementListener.
+   * Base class for refinement listeners. Other classes, which need to be
+   * informed about refinements of the Triangulation, can be derived from
+   * RefinementListener.
    *
-   * @note The use of this class has been
-   * superseded by the signals mechanism.
-   * See the general documentation of the
-   * Triangulation class for more information.
+   * @note The use of this class has been superseded by the signals mechanism.
+   * See the general documentation of the Triangulation class for more
+   * information.
    *
    * @deprecated
    */
@@ -1528,30 +1442,25 @@ public:
   {
   public:
     /**
-     * Destructor. Does nothing, but is
-     * declared virtual because this
-     * class also has virtual functions.
+     * Destructor. Does nothing, but is declared virtual because this class
+     * also has virtual functions.
      *
-     * @note The use of this class has been
-     * superseded by the signals mechanism.
-     * See the general documentation of the
-     * Triangulation class for more information.
+     * @note The use of this class has been superseded by the signals
+     * mechanism. See the general documentation of the Triangulation class for
+     * more information.
      *
      * @deprecated
      */
     virtual ~RefinementListener ();
 
     /**
-     * Before refinement is actually
-     * performed, the triangulation class
-     * calls this method on all objects
-     * derived from this class and
-     * registered with the triangulation.
+     * Before refinement is actually performed, the triangulation class calls
+     * this method on all objects derived from this class and registered with
+     * the triangulation.
      *
-     * @note The use of this class has been
-     * superseded by the signals mechanism.
-     * See the general documentation of the
-     * Triangulation class for more information.
+     * @note The use of this class has been superseded by the signals
+     * mechanism. See the general documentation of the Triangulation class for
+     * more information.
      *
      * @deprecated
      */
@@ -1560,16 +1469,13 @@ public:
     pre_refinement_notification (const Triangulation<dim, spacedim> &tria);
 
     /**
-     * After refinement is actually
-     * performed, the triangulation class
-     * calls this method on all objects
-     * derived from this class and
-     * registered with the triangulation.
+     * After refinement is actually performed, the triangulation class calls
+     * this method on all objects derived from this class and registered with
+     * the triangulation.
      *
-     * @note The use of this class has been
-     * superseded by the signals mechanism.
-     * See the general documentation of the
-     * Triangulation class for more information.
+     * @note The use of this class has been superseded by the signals
+     * mechanism. See the general documentation of the Triangulation class for
+     * more information.
      *
      * @deprecated
      */
@@ -1578,23 +1484,16 @@ public:
     post_refinement_notification (const Triangulation<dim, spacedim> &tria);
 
     /**
-     * At the end of a call to
-     * copy_triangulation() the
-     * Triangulation class calls this
-     * method on all objects derived from
-     * this class and registered with the
-     * original Triangulation @p old_tria
-     * so that they might subscribe to the
-     * copied one @p new_tria as well, if
-     * that is desired. By default this
-     * method does nothing, a different
-     * behavior has to be implemented in
-     * derived classes.
+     * At the end of a call to copy_triangulation() the Triangulation class
+     * calls this method on all objects derived from this class and registered
+     * with the original Triangulation @p old_tria so that they might
+     * subscribe to the copied one @p new_tria as well, if that is desired. By
+     * default this method does nothing, a different behavior has to be
+     * implemented in derived classes.
      *
-     * @note The use of this class has been
-     * superseded by the signals mechanism.
-     * See the general documentation of the
-     * Triangulation class for more information.
+     * @note The use of this class has been superseded by the signals
+     * mechanism. See the general documentation of the Triangulation class for
+     * more information.
      *
      * @deprecated
      */
@@ -1604,20 +1503,14 @@ public:
                        const Triangulation<dim, spacedim> &new_tria);
 
     /**
-     * At the end of a call to
-     * create_triangulation() the
-     * Triangulation class calls this
-     * method on all objects derived from
-     * this class and registered with the
-     * current Triangulation object. By
-     * default this method does nothing,
-     * a different behavior has to be
-     * implemented in derived classes.
+     * At the end of a call to create_triangulation() the Triangulation class
+     * calls this method on all objects derived from this class and registered
+     * with the current Triangulation object. By default this method does
+     * nothing, a different behavior has to be implemented in derived classes.
      *
-     * @note The use of this class has been
-     * superseded by the signals mechanism.
-     * See the general documentation of the
-     * Triangulation class for more information.
+     * @note The use of this class has been superseded by the signals
+     * mechanism. See the general documentation of the Triangulation class for
+     * more information.
      *
      * @deprecated
      */
@@ -1627,60 +1520,35 @@ public:
   };
 
   /**
-   * A structure that is used as an
-   * exception object by the
-   * create_triangulation() function to
-   * indicate which cells among the coarse
-   * mesh cells are inverted or severely
-   * distorted (see the entry on
-   * @ref GlossDistorted "distorted cells"
-   * in the glossary).
-   *
-   * Objects of this kind are
-   * thrown by the
-   * create_triangulation() and
-   * execute_coarsening_and_refinement()
-   * functions, and they can be
-   * caught in user code if this
-   * condition is to be
-   * ignored. Note, however, that
-   * such exceptions are only
-   * produced if the necessity for
-   * this check was indicated when
-   * calling the constructor of the
-   * Triangulation class.
-   *
-   * A cell is called
-   * <i>deformed</i> if the
-   * determinant of the Jacobian of
-   * the mapping from reference
-   * cell to real cell is negative
-   * at least at one vertex. This
-   * computation is done using the
-   * GeometryInfo::jacobian_determinants_at_vertices
-   * function.
+   * A structure that is used as an exception object by the
+   * create_triangulation() function to indicate which cells among the coarse
+   * mesh cells are inverted or severely distorted (see the entry on @ref
+   * GlossDistorted "distorted cells" in the glossary).
+   *
+   * Objects of this kind are thrown by the create_triangulation() and
+   * execute_coarsening_and_refinement() functions, and they can be caught in
+   * user code if this condition is to be ignored. Note, however, that such
+   * exceptions are only produced if the necessity for this check was
+   * indicated when calling the constructor of the Triangulation class.
+   *
+   * A cell is called <i>deformed</i> if the determinant of the Jacobian of
+   * the mapping from reference cell to real cell is negative at least at one
+   * vertex. This computation is done using the
+   * GeometryInfo::jacobian_determinants_at_vertices function.
    */
   struct DistortedCellList : public dealii::ExceptionBase
   {
     /**
-     * Destructor. Empty, but needed
-     * for the sake of exception
-     * specification, since the base
-     * class has this exception
-     * specification and the
-     * automatically generated
-     * destructor would have a
-     * different one due to member
-     * objects.
+     * Destructor. Empty, but needed for the sake of exception specification,
+     * since the base class has this exception specification and the
+     * automatically generated destructor would have a different one due to
+     * member objects.
      */
     virtual ~DistortedCellList () throw();
 
     /**
-     * A list of those cells
-     * among the coarse mesh
-     * cells that are deformed or
-     * whose children are
-     * deformed.
+     * A list of those cells among the coarse mesh cells that are deformed or
+     * whose children are deformed.
      */
     std::list<typename Triangulation<dim,spacedim>::cell_iterator>
     distorted_cells;
@@ -1688,141 +1556,98 @@ public:
 
 
   /**
-   * Make the dimension available
-   * in function templates.
+   * Make the dimension available in function templates.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Make the space-dimension available
-   * in function templates.
+   * Make the space-dimension available in function templates.
    */
   static const unsigned int space_dimension = spacedim;
 
   /**
-   *  Create an empty
-   *  triangulation. Do not create
-   *  any cells.
+   * Create an empty triangulation. Do not create any cells.
    *
-   * @param smooth_grid Determines
-   * the level of smoothness of the
-   * mesh size function that should
-   * be enforced upon mesh
-   * refinement.
+   * @param smooth_grid Determines the level of smoothness of the mesh size
+   * function that should be enforced upon mesh refinement.
    *
-   * @param
-   * check_for_distorted_cells
-   * Determines whether the
-   * triangulation should check
-   * whether any of the cells that
-   * are created by
-   * create_triangulation() or
-   * execute_coarsening_and_refinement()
-   * are distorted (see
-   * @ref GlossDistorted "distorted cells").
-   * If set, these two
-   * functions may throw an
-   * exception if they encounter
-   * distorted cells.
+   * @param check_for_distorted_cells Determines whether the triangulation
+   * should check whether any of the cells that are created by
+   * create_triangulation() or execute_coarsening_and_refinement() are
+   * distorted (see @ref GlossDistorted "distorted cells"). If set, these two
+   * functions may throw an exception if they encounter distorted cells.
    */
   Triangulation (const MeshSmoothing smooth_grid = none,
                  const bool check_for_distorted_cells = false);
 
   /**
-   *  Copy constructor.
-   *
-   *  You should really use the @p
-   *  copy_triangulation function,
-   *  so we declare this function
-   *  but let it throw an internal
-   *  error. The reason for this is
-   *  that we may want to use
-   *  triangulation objects in
-   *  collections. However, C++
-   *  containers require that the
-   *  objects stored in them are
-   *  copyable, so we need to
-   *  provide a copy
-   *  constructor. On the other
-   *  hand, copying triangulations
-   *  is so expensive that we do
-   *  not want such objects copied
-   *  by accident, for example in
-   *  compiler-generated temporary
-   *  objects. By defining a copy
-   *  constructor but throwing an
-   *  error, we satisfy the formal
-   *  requirements of containers,
-   *  but at the same time disallow
-   *  actual copies. Finally,
-   *  through the exception, one
-   *  easily finds the places where
-   *  code has to be changed to
-   *  avoid copies.
+   * Copy constructor.
+   *
+   * You should really use the @p copy_triangulation function, so we declare
+   * this function but let it throw an internal error. The reason for this is
+   * that we may want to use triangulation objects in collections. However,
+   * C++ containers require that the objects stored in them are copyable, so
+   * we need to provide a copy constructor. On the other hand, copying
+   * triangulations is so expensive that we do not want such objects copied by
+   * accident, for example in compiler-generated temporary objects. By
+   * defining a copy constructor but throwing an error, we satisfy the formal
+   * requirements of containers, but at the same time disallow actual copies.
+   * Finally, through the exception, one easily finds the places where code
+   * has to be changed to avoid copies.
    */
   Triangulation (const Triangulation<dim, spacedim> &t);
 
   /**
-   *  Delete the object and all levels of
-   *  the hierarchy.
+   * Delete the object and all levels of the hierarchy.
    */
   virtual ~Triangulation ();
 
   /**
-   * Reset this triangulation into a
-   * virgin state by deleting all data.
+   * Reset this triangulation into a virgin state by deleting all data.
    *
-   * Note that this operation is only
-   * allowed if no subscriptions to this
-   * object exist any more, such as
-   * DoFHandler objects using it.
+   * Note that this operation is only allowed if no subscriptions to this
+   * object exist any more, such as DoFHandler objects using it.
    */
   virtual void clear ();
 
   /**
-   * Sets the mesh smoothing to @p
-   * mesh_smoothing. This overrides
-   * the MeshSmoothing given to the
-   * constructor. It is allowed to
-   * call this function only if
-   * the triangulation is empty.
+   * Sets the mesh smoothing to @p mesh_smoothing. This overrides the
+   * MeshSmoothing given to the constructor. It is allowed to call this
+   * function only if the triangulation is empty.
    */
   virtual void set_mesh_smoothing (const MeshSmoothing mesh_smoothing);
 
   /**
-   * If @p dim==spacedim, assign a boundary object to a certain part
-   * of the boundary of a the triangulation. If a face with boundary
-   * number @p number is refined, this object is used to find the
-   * location of new vertices on the boundary (see the results section
-   * of step-49 for a more in-depth discussion of this, with
-   * examples).  It is also used for non-linear (i.e.: non-Q1)
-   * transformations of cells to the unit cell in shape function
-   * calculations.
-   *
-   * If @p dim!=spacedim the boundary object is in fact the exact
-   * manifold that the triangulation is approximating (for example a
-   * circle approximated by a polygon triangulation). As above, the
-   * refinement is made in such a way that the new points are located
-   * on the exact manifold.
-   *
-   * Numbers of boundary objects correspond to material numbers of
-   * faces at the boundary, for instance the material id in a UCD
-   * input file. They are not necessarily consecutive but must be in
-   * the range 0-(types::boundary_id-1).  Material IDs on boundaries
-   * are also called boundary indicators and are accessed with
-   * accessor functions of that name.
+   * If @p dim==spacedim, assign a boundary object to a certain part of the
+   * boundary of a the triangulation. If a face with boundary number @p number
+   * is refined, this object is used to find the location of new vertices on
+   * the boundary (see the results section of step-49 for a more in-depth
+   * discussion of this, with examples).  It is also used for non-linear
+   * (i.e.: non-Q1) transformations of cells to the unit cell in shape
+   * function calculations.
+   *
+   * If @p dim!=spacedim the boundary object is in fact the exact manifold
+   * that the triangulation is approximating (for example a circle
+   * approximated by a polygon triangulation). As above, the refinement is
+   * made in such a way that the new points are located on the exact manifold.
+   *
+   * Numbers of boundary objects correspond to material numbers of faces at
+   * the boundary, for instance the material id in a UCD input file. They are
+   * not necessarily consecutive but must be in the range
+   * 0-(types::boundary_id-1).  Material IDs on boundaries are also called
+   * boundary indicators and are accessed with accessor functions of that
+   * name.
    *
    * The @p boundary_object is not copied and MUST persist until the
    * triangulation is destroyed. This is also true for triangulations
    * generated from this one by @p copy_triangulation.
    *
-   * It is possible to remove or replace the boundary object during
-   * the lifetime of a non-empty triangulation. Usually, this is done
-   * before the first refinement and is dangerous afterwards. Removal
-   * of a boundary object is done by <tt>set_boundary(number)</tt>,
-   * i.e. the function of same name but only one argument. This
-   * operation then replaces the boundary object given before by a
-   * straight boundary approximation.
+   * It is possible to remove or replace the boundary object during the
+   * lifetime of a non-empty triangulation. Usually, this is done before the
+   * first refinement and is dangerous afterwards. Removal of a boundary
+   * object is done by <tt>set_boundary(number)</tt>, i.e. the function of
+   * same name but only one argument. This operation then replaces the
+   * boundary object given before by a straight boundary approximation.
    *
    * @ingroup boundary
    *
@@ -1833,10 +1658,10 @@ public:
 
 
   /**
-   * Reset those parts of the boundary with the given number to use a
-   * straight boundary approximation. This is the default state of a
-   * triangulation, and undoes assignment of a different boundary
-   * object by the function of same name and two arguments.
+   * Reset those parts of the boundary with the given number to use a straight
+   * boundary approximation. This is the default state of a triangulation, and
+   * undoes assignment of a different boundary object by the function of same
+   * name and two arguments.
    *
    * @ingroup boundary
    *
@@ -1845,25 +1670,23 @@ public:
   void set_boundary (const types::manifold_id number);
 
   /**
-   * Assign a manifold object to a certain part of the the
-   * triangulation. If an object with manfifold number @p number is
-   * refined, this object is used to find the location of new vertices
-   * (see the results section of step-49 for a more in-depth
-   * discussion of this, with examples).  It is also used for
-   * non-linear (i.e.: non-Q1) transformations of cells to the unit
-   * cell in shape function calculations.
+   * Assign a manifold object to a certain part of the the triangulation. If
+   * an object with manfifold number @p number is refined, this object is used
+   * to find the location of new vertices (see the results section of step-49
+   * for a more in-depth discussion of this, with examples).  It is also used
+   * for non-linear (i.e.: non-Q1) transformations of cells to the unit cell
+   * in shape function calculations.
    *
    * The @p manifold_object is not copied and MUST persist until the
    * triangulation is destroyed. This is also true for triangulations
    * generated from this one by @p copy_triangulation.
    *
-   * It is possible to remove or replace the boundary object during
-   * the lifetime of a non-empty triangulation. Usually, this is done
-   * before the first refinement and is dangerous afterwards. Removal
-   * of a manifold object is done by <tt>set_manifold(number)</tt>,
-   * i.e. the function of same name but only one argument. This
-   * operation then replaces the manifold object given before by a
-   * straight manifold approximation.
+   * It is possible to remove or replace the boundary object during the
+   * lifetime of a non-empty triangulation. Usually, this is done before the
+   * first refinement and is dangerous afterwards. Removal of a manifold
+   * object is done by <tt>set_manifold(number)</tt>, i.e. the function of
+   * same name but only one argument. This operation then replaces the
+   * manifold object given before by a straight manifold approximation.
    *
    * @ingroup manifold
    *
@@ -1874,10 +1697,10 @@ public:
 
 
   /**
-   * Reset those parts of the triangulation with the given manifold_id
-   * to use a FlatManifold object. This is the default state of a
-   * triangulation, and undoes assignment of a different Manifold
-   * object by the function of same name and two arguments.
+   * Reset those parts of the triangulation with the given manifold_id to use
+   * a FlatManifold object. This is the default state of a triangulation, and
+   * undoes assignment of a different Manifold object by the function of same
+   * name and two arguments.
    *
    * @ingroup manifold
    *
@@ -1906,11 +1729,10 @@ public:
   const Manifold<dim,spacedim> &get_manifold (const types::manifold_id number) const;
 
   /**
-   * Returns a vector containing all boundary indicators assigned to
-   * boundary faces of this Triangulation object. Note, that each
-   * boundary indicator is reported only once. The size of the return
-   * vector will represent the number of different indicators (which
-   * is greater or equal one).
+   * Returns a vector containing all boundary indicators assigned to boundary
+   * faces of this Triangulation object. Note, that each boundary indicator is
+   * reported only once. The size of the return vector will represent the
+   * number of different indicators (which is greater or equal one).
    *
    * @ingroup boundary
    *
@@ -1919,11 +1741,10 @@ public:
   std::vector<types::boundary_id> get_boundary_indicators() const;
 
   /**
-   * Returns a vector containing all manifold indicators assigned to
-   * the objects of this Triangulation. Note, that each manifold
-   * indicator is reported only once. The size of the return vector
-   * will represent the number of different indicators (which is
-   * greater or equal one).
+   * Returns a vector containing all manifold indicators assigned to the
+   * objects of this Triangulation. Note, that each manifold indicator is
+   * reported only once. The size of the return vector will represent the
+   * number of different indicators (which is greater or equal one).
    *
    * @ingroup manifold
    *
@@ -1932,96 +1753,87 @@ public:
   std::vector<types::manifold_id> get_manifold_ids() const;
 
   /**
-   *  Copy a triangulation. This operation is not cheap, so you should
-   *  be careful with using this. We do not implement this function as
-   *  a copy constructor, since it makes it easier to maintain
-   *  collections of triangulations if you can assign them values
-   *  later on.
+   * Copy a triangulation. This operation is not cheap, so you should be
+   * careful with using this. We do not implement this function as a copy
+   * constructor, since it makes it easier to maintain collections of
+   * triangulations if you can assign them values later on.
    *
-   *  Keep in mind that this function also copies the pointer to the
-   *  boundary descriptor previously set by the @p set_boundary
-   *  function and to the Manifold object previously set by the
-   *  set_manifold() function. You must therefore also guarantee that
-   *  the boundary and manifold objects have a lifetime at least as
-   *  long as the copied triangulation.
+   * Keep in mind that this function also copies the pointer to the boundary
+   * descriptor previously set by the @p set_boundary function and to the
+   * Manifold object previously set by the set_manifold() function. You must
+   * therefore also guarantee that the boundary and manifold objects have a
+   * lifetime at least as long as the copied triangulation.
    *
-   *  This triangulation must be empty beforehand.
+   * This triangulation must be empty beforehand.
    *
-   *  The function is made @p virtual since some derived classes might
-   *  want to disable or extend the functionality of this function.
+   * The function is made @p virtual since some derived classes might want to
+   * disable or extend the functionality of this function.
    *
-   *  @note Calling this function triggers the 'copy' signal on
-   *  old_tria, i.e.  the triangulation being copied <i>from</i>.  It
-   *  also triggers the 'create' signal of the current triangulation.
-   *  See the section on signals in the general documentation for more
-   *  information.
+   * @note Calling this function triggers the 'copy' signal on old_tria, i.e.
+   * the triangulation being copied <i>from</i>.  It also triggers the
+   * 'create' signal of the current triangulation. See the section on signals
+   * in the general documentation for more information.
    *
-   *  @note The list of connections to signals is not copied from the
-   *  old to the new triangulation since these connections were
-   *  established to monitor how the old triangulation changes, not
-   *  how any triangulation it may be copied to changes.
+   * @note The list of connections to signals is not copied from the old to
+   * the new triangulation since these connections were established to monitor
+   * how the old triangulation changes, not how any triangulation it may be
+   * copied to changes.
    */
   virtual void copy_triangulation (const Triangulation<dim, spacedim> &old_tria);
 
   /**
-   * Create a triangulation from a list of vertices and a list of
-   * cells, each of the latter being a list of <tt>1<<dim</tt> vertex
-   * indices. The triangulation must be empty upon calling this
-   * function and the cell list should be useful (connected domain,
-   * etc.).
-   *
-   * Material data for the cells is given within the @p cells array,
-   * while boundary information is given in the @p subcelldata field.
-   *
-   * The numbering of vertices within the @p cells array is subject to
-   * some constraints; see the general class documentation for this.
-   *
-   * For conditions when this function can generate a valid
-   * triangulation, see the documentation of this class, and the
-   * GridIn and GridReordering class.
-   *
-   * If the <code>check_for_distorted_cells</code> flag was specified
-   * upon creation of this object, at the very end of its operation,
-   * the current function walks over all cells and verifies that none
-   * of the cells is deformed (see the entry on @ref GlossDistorted
-   * "distorted cells" in the glossary), where we call a cell deformed
-   * if the determinant of the Jacobian of the mapping from reference
-   * cell to real cell is negative at least at one of the vertices
-   * (this computation is done using the
-   * GeometryInfo::jacobian_determinants_at_vertices function). If
-   * there are deformed cells, this function throws an exception of
-   * kind DistortedCellList. Since this happens after all data
-   * structures have been set up, you can catch and ignore this
-   * exception if you know what you do -- for example, it may be that
-   * the determinant is zero (indicating that you have collapsed edges
-   * in a cell) but that this is ok because you didn't intend to
-   * integrate on this cell anyway. On the other hand, deformed cells
-   * are often a sign of a mesh that is too coarse to resolve the
-   * geometry of the domain, and in this case ignoring the exception
-   * is probably unwise.
+   * Create a triangulation from a list of vertices and a list of cells, each
+   * of the latter being a list of <tt>1<<dim</tt> vertex indices. The
+   * triangulation must be empty upon calling this function and the cell list
+   * should be useful (connected domain, etc.).
+   *
+   * Material data for the cells is given within the @p cells array, while
+   * boundary information is given in the @p subcelldata field.
+   *
+   * The numbering of vertices within the @p cells array is subject to some
+   * constraints; see the general class documentation for this.
+   *
+   * For conditions when this function can generate a valid triangulation, see
+   * the documentation of this class, and the GridIn and GridReordering class.
+   *
+   * If the <code>check_for_distorted_cells</code> flag was specified upon
+   * creation of this object, at the very end of its operation, the current
+   * function walks over all cells and verifies that none of the cells is
+   * deformed (see the entry on @ref GlossDistorted "distorted cells" in the
+   * glossary), where we call a cell deformed if the determinant of the
+   * Jacobian of the mapping from reference cell to real cell is negative at
+   * least at one of the vertices (this computation is done using the
+   * GeometryInfo::jacobian_determinants_at_vertices function). If there are
+   * deformed cells, this function throws an exception of kind
+   * DistortedCellList. Since this happens after all data structures have been
+   * set up, you can catch and ignore this exception if you know what you do
+   * -- for example, it may be that the determinant is zero (indicating that
+   * you have collapsed edges in a cell) but that this is ok because you
+   * didn't intend to integrate on this cell anyway. On the other hand,
+   * deformed cells are often a sign of a mesh that is too coarse to resolve
+   * the geometry of the domain, and in this case ignoring the exception is
+   * probably unwise.
    *
    * @note This function is used in step-14 .
    *
-   * @note This function triggers the create signal after doing its
-   * work. See the section on signals in the general documentation of
-   * this class.
+   * @note This function triggers the create signal after doing its work. See
+   * the section on signals in the general documentation of this class.
    *
-   * @note The check for distorted cells is only done if
-   * dim==spacedim, as otherwise cells can legitimately be twisted if
-   * the manifold they describe is twisted.
+   * @note The check for distorted cells is only done if dim==spacedim, as
+   * otherwise cells can legitimately be twisted if the manifold they describe
+   * is twisted.
    */
   virtual void create_triangulation (const std::vector<Point<spacedim> >    &vertices,
                                      const std::vector<CellData<dim> > &cells,
                                      const SubCellData                 &subcelldata);
 
   /**
-   * For backward compatibility, only. This function takes the cell
-   * data in the ordering as requested by deal.II versions up to 5.2,
-   * converts it to the new (lexicographic) ordering and calls
-   * create_triangulation().
+   * For backward compatibility, only. This function takes the cell data in
+   * the ordering as requested by deal.II versions up to 5.2, converts it to
+   * the new (lexicographic) ordering and calls create_triangulation().
    *
-   * @note This function internally calls create_triangulation and
-   * therefore can throw the same exception as the other function.
+   * @note This function internally calls create_triangulation and therefore
+   * can throw the same exception as the other function.
    */
   virtual void create_triangulation_compatibility (
     const std::vector<Point<spacedim> >    &vertices,
@@ -2029,22 +1841,22 @@ public:
     const SubCellData                 &subcelldata);
 
   /**
-   * Revert or flip the direction_flags of a dim<spacedim
-   * triangulation, see @ref GlossDirectionFlag .
+   * Revert or flip the direction_flags of a dim<spacedim triangulation, see
+   * @ref GlossDirectionFlag .
    *
    * This function throws an exception if dim equals spacedim.
-  */
+   */
   void flip_all_direction_flags();
 
   /**
-   * Distort the grid by randomly moving around all the vertices of
-   * the grid.  The direction of moving is random, while the length of
-   * the shift vector has a value of @p factor times the minimal
-   * length of the active lines adjacent to this vertex. Note that @p
-   * factor should obviously be well below <tt>0.5</tt>.
+   * Distort the grid by randomly moving around all the vertices of the grid.
+   * The direction of moving is random, while the length of the shift vector
+   * has a value of @p factor times the minimal length of the active lines
+   * adjacent to this vertex. Note that @p factor should obviously be well
+   * below <tt>0.5</tt>.
    *
-   * If @p keep_boundary is set to @p true (which is the default),
-   * then boundary vertices are not moved.
+   * If @p keep_boundary is set to @p true (which is the default), then
+   * boundary vertices are not moved.
    *
    * @deprecated Use GridTools::distort_random instead.
    */
@@ -2057,11 +1869,10 @@ public:
    */
 
   /**
-   *  Flag all active cells for refinement.  This will refine all
-   *  cells of all levels which are not already refined (i.e. only
-   *  cells are refined which do not yet have children). The cells are
-   *  only flagged, not refined, thus you have the chance to save the
-   *  refinement flags.
+   * Flag all active cells for refinement.  This will refine all cells of all
+   * levels which are not already refined (i.e. only cells are refined which
+   * do not yet have children). The cells are only flagged, not refined, thus
+   * you have the chance to save the refinement flags.
    */
   void set_all_refine_flags ();
 
@@ -2069,50 +1880,48 @@ public:
    * Refine all cells @p times times, by alternatingly calling
    * set_all_refine_flags and execute_coarsening_and_refinement.
    *
-   * The latter function may throw an exception if it creates cells
-   * that are distorted (see its documentation for an
-   * explanation). This exception will be propagated through this
-   * function if that happens, and you may not get the actual number
-   * of refinement steps in that case.
+   * The latter function may throw an exception if it creates cells that are
+   * distorted (see its documentation for an explanation). This exception will
+   * be propagated through this function if that happens, and you may not get
+   * the actual number of refinement steps in that case.
    *
-   * @note This function triggers the pre- and post-refinement signals
-   * before and after doing each individual refinement cycle
-   * (i.e. more than once if times > 1) . See the section on signals
-   * in the general documentation of this class.
+   * @note This function triggers the pre- and post-refinement signals before
+   * and after doing each individual refinement cycle (i.e. more than once if
+   * times > 1) . See the section on signals in the general documentation of
+   * this class.
    */
   void refine_global (const unsigned int times = 1);
 
   /**
    * Execute both refinement and coarsening of the triangulation.
    *
-   * The function resets all refinement and coarsening flags to
-   * false. It uses the user flags for internal purposes. They will
-   * therefore be overwritten by undefined content.
+   * The function resets all refinement and coarsening flags to false. It uses
+   * the user flags for internal purposes. They will therefore be overwritten
+   * by undefined content.
    *
-   * To allow user programs to fix up these cells if that is desired,
-   * this function after completing all other work may throw an
-   * exception of type DistortedCellList that contains a list of those
-   * cells that have been refined and have at least one child that is
-   * distorted. The function does not create such an exception if no
-   * cells have created distorted children.  Note that for the check
-   * for distorted cells to happen, the
-   * <code>check_for_distorted_cells</code> flag has to be specified
-   * upon creation of a triangulation object.
+   * To allow user programs to fix up these cells if that is desired, this
+   * function after completing all other work may throw an exception of type
+   * DistortedCellList that contains a list of those cells that have been
+   * refined and have at least one child that is distorted. The function does
+   * not create such an exception if no cells have created distorted children.
+   * Note that for the check for distorted cells to happen, the
+   * <code>check_for_distorted_cells</code> flag has to be specified upon
+   * creation of a triangulation object.
    *
    * See the general docs for more information.
    *
-   * @note This function triggers the pre- and post-refinement signals
-   * before and after doing its work. See the section on signals in
-   * the general documentation of this class.
+   * @note This function triggers the pre- and post-refinement signals before
+   * and after doing its work. See the section on signals in the general
+   * documentation of this class.
    *
-   * @note If the boundary description is sufficiently irregular, it
-   * can happen that some of the children produced by mesh refinement
-   * are distorted (see the extensive discussion on @ref
-   * GlossDistorted "distorted cells").
+   * @note If the boundary description is sufficiently irregular, it can
+   * happen that some of the children produced by mesh refinement are
+   * distorted (see the extensive discussion on @ref GlossDistorted "distorted
+   * cells").
    *
-   * @note This function is <tt>virtual</tt> to allow derived classes
-   * to insert hooks, such as saving refinement flags and the like
-   * (see e.g. the PersistentTriangulation class).
+   * @note This function is <tt>virtual</tt> to allow derived classes to
+   * insert hooks, such as saving refinement flags and the like (see e.g. the
+   * PersistentTriangulation class).
    */
   virtual void execute_coarsening_and_refinement ();
 
@@ -2120,32 +1929,30 @@ public:
    * Do both preparation for refinement and coarsening as well as mesh
    * smoothing.
    *
-   * Regarding the refinement process it fixes the closure of the
-   * refinement in <tt>dim>=2</tt> (make sure that no two cells are
-   * adjacent with a refinement level differing with more than one),
-   * etc.  It performs some mesh smoothing if the according flag was
-   * given to the constructor of this class.  The function returns
-   * whether additional cells have been flagged for refinement.
+   * Regarding the refinement process it fixes the closure of the refinement
+   * in <tt>dim>=2</tt> (make sure that no two cells are adjacent with a
+   * refinement level differing with more than one), etc.  It performs some
+   * mesh smoothing if the according flag was given to the constructor of this
+   * class.  The function returns whether additional cells have been flagged
+   * for refinement.
    *
-   * See the general doc of this class for more information on
-   * smoothing upon refinement.
+   * See the general doc of this class for more information on smoothing upon
+   * refinement.
    *
    * Regarding the coarsening part, flagging and deflagging cells in
    * preparation of the actual coarsening step are done. This includes
-   * deleting coarsen flags from cells which may not be deleted
-   * (e.g. because one neighbor is more refined than the cell), doing
-   * some smoothing, etc.
+   * deleting coarsen flags from cells which may not be deleted (e.g. because
+   * one neighbor is more refined than the cell), doing some smoothing, etc.
    *
-   * The effect is that only those cells are flagged for coarsening
-   * which will actually be coarsened. This includes the fact that all
-   * flagged cells belong to parent cells of which all children are
-   * flagged.
+   * The effect is that only those cells are flagged for coarsening which will
+   * actually be coarsened. This includes the fact that all flagged cells
+   * belong to parent cells of which all children are flagged.
    *
-   * The function returns whether some cells' flagging has been
-   * changed in the process.
+   * The function returns whether some cells' flagging has been changed in the
+   * process.
    *
-   * This function uses the user flags, so store them if you still
-   * need them afterwards.
+   * This function uses the user flags, so store them if you still need them
+   * afterwards.
    */
   bool prepare_coarsening_and_refinement ();
 
@@ -2159,26 +1966,25 @@ public:
    */
 
   /**
-   *  Add a RefinementListener. Adding listeners to the Triangulation
-   *  allows other classes to be informed when the Triangulation is
-   *  refined.
+   * Add a RefinementListener. Adding listeners to the Triangulation allows
+   * other classes to be informed when the Triangulation is refined.
    *
    * @note The use of this function has been superseded by the signals
-   * mechanism.  See the general documentation of the Triangulation
-   * class for more information.
+   * mechanism.  See the general documentation of the Triangulation class for
+   * more information.
    *
    * @deprecated
    */
   void add_refinement_listener (RefinementListener &listener) const DEAL_II_DEPRECATED;
 
   /**
-   *  Remove a RefinementListener. When some class needs no longer to
-   *  be informed about refinements, the listener should be removed
-   *  from the Triangulation.
+   * Remove a RefinementListener. When some class needs no longer to be
+   * informed about refinements, the listener should be removed from the
+   * Triangulation.
    *
    * @note The use of this function has been superseded by the signals
-   * mechanism.  See the general documentation of the Triangulation
-   * class for more information.
+   * mechanism.  See the general documentation of the Triangulation class for
+   * more information.
    *
    * @deprecated
    */
@@ -2187,11 +1993,12 @@ public:
   /**
    * A structure that has boost::signal objects for a number of actions that a
    * triangulation can do to itself. See the general documentation of the
-   * Triangulation class for more information and for documentation of
-   * the semantics of the member functions.
+   * Triangulation class for more information and for documentation of the
+   * semantics of the member functions.
    *
-   * For documentation on signals, see http://www.boost.org/doc/libs/release/libs/signals2 .
-   **/
+   * For documentation on signals, see
+   * http://www.boost.org/doc/libs/release/libs/signals2 .
+   */
   struct Signals
   {
     boost::signals2::signal<void ()> create;
@@ -2217,25 +2024,23 @@ public:
    */
 
   /**
-   *  Save the addresses of the cells which are flagged for refinement
-   *  to @p out.  For usage, read the general documentation for this
-   *  class.
+   * Save the addresses of the cells which are flagged for refinement to @p
+   * out.  For usage, read the general documentation for this class.
    */
   void save_refine_flags (std::ostream &out) const;
 
   /**
-   * Same as above, but store the flags to a bitvector rather than to
-   * a file.
+   * Same as above, but store the flags to a bitvector rather than to a file.
    */
   void save_refine_flags (std::vector<bool> &v) const;
 
   /**
-   *  Read the information stored by @p save_refine_flags.
+   * Read the information stored by @p save_refine_flags.
    */
   void load_refine_flags (std::istream &in);
 
   /**
-   *  Read the information stored by @p save_refine_flags.
+   * Read the information stored by @p save_refine_flags.
    */
   void load_refine_flags (const std::vector<bool> &v);
 
@@ -2245,8 +2050,7 @@ public:
   void save_coarsen_flags (std::ostream &out) const;
 
   /**
-   * Same as above, but store the flags to a bitvector rather than to
-   * a file.
+   * Same as above, but store the flags to a bitvector rather than to a file.
    */
   void save_coarsen_flags (std::vector<bool> &v) const;
 
@@ -2261,8 +2065,8 @@ public:
   void load_coarsen_flags (const std::vector<bool> &v);
 
   /**
-   * Return whether this triangulation has ever undergone anisotropic
-   * (as opposed to only isotropic) refinement.
+   * Return whether this triangulation has ever undergone anisotropic (as
+   * opposed to only isotropic) refinement.
    */
   bool get_anisotropic_refinement_flag() const;
 
@@ -2276,38 +2080,38 @@ public:
    */
 
   /**
-   *  Clear all user flags.  See also @ref GlossUserFlags .
+   * Clear all user flags.  See also @ref GlossUserFlags .
    */
   void clear_user_flags ();
 
   /**
-   *  Save all user flags. See the general documentation for this
-   *  class and the documentation for the @p save_refine_flags for
-   *  more details.  See also @ref GlossUserFlags .
+   * Save all user flags. See the general documentation for this class and the
+   * documentation for the @p save_refine_flags for more details.  See also
+   * @ref GlossUserFlags .
    */
   void save_user_flags (std::ostream &out) const;
 
   /**
-   *  Same as above, but store the flags to a bitvector rather than to
-   *  a file.  The output vector is resized if necessary.  See also
-   *  @ref GlossUserFlags .
+   * Same as above, but store the flags to a bitvector rather than to a file.
+   * The output vector is resized if necessary.  See also @ref GlossUserFlags
+   * .
    */
   void save_user_flags (std::vector<bool> &v) const;
 
   /**
-   *  Read the information stored by @p save_user_flags.  See also
-   *  @ref GlossUserFlags .
+   * Read the information stored by @p save_user_flags.  See also @ref
+   * GlossUserFlags .
    */
   void load_user_flags (std::istream &in);
 
   /**
-   *  Read the information stored by @p save_user_flags.  See also
-   *  @ref GlossUserFlags .
+   * Read the information stored by @p save_user_flags.  See also @ref
+   * GlossUserFlags .
    */
   void load_user_flags (const std::vector<bool> &v);
 
   /**
-   *  Clear all user flags on lines.  See also @ref GlossUserFlags .
+   * Clear all user flags on lines.  See also @ref GlossUserFlags .
    */
   void clear_user_flags_line ();
 
@@ -2317,26 +2121,24 @@ public:
   void save_user_flags_line (std::ostream &out) const;
 
   /**
-   * Same as above, but store the flags to a bitvector rather than to
-   * a file.  The output vector is resized if necessary.  See also
-   * @ref GlossUserFlags .
+   * Same as above, but store the flags to a bitvector rather than to a file.
+   * The output vector is resized if necessary.  See also @ref GlossUserFlags
+   * .
    */
   void save_user_flags_line (std::vector<bool> &v) const;
 
   /**
-   * Load the user flags located on lines.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on lines.  See also @ref GlossUserFlags .
    */
   void load_user_flags_line (std::istream &in);
 
   /**
-   * Load the user flags located on lines.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on lines.  See also @ref GlossUserFlags .
    */
   void load_user_flags_line (const std::vector<bool> &v);
 
   /**
-   *  Clear all user flags on quads.  See also @ref GlossUserFlags .
+   * Clear all user flags on quads.  See also @ref GlossUserFlags .
    */
   void clear_user_flags_quad ();
 
@@ -2346,21 +2148,19 @@ public:
   void save_user_flags_quad (std::ostream &out) const;
 
   /**
-   * Same as above, but store the flags to a bitvector rather than to
-   * a file.  The output vector is resized if necessary.  See also
-   * @ref GlossUserFlags .
+   * Same as above, but store the flags to a bitvector rather than to a file.
+   * The output vector is resized if necessary.  See also @ref GlossUserFlags
+   * .
    */
   void save_user_flags_quad (std::vector<bool> &v) const;
 
   /**
-   * Load the user flags located on quads.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on quads.  See also @ref GlossUserFlags .
    */
   void load_user_flags_quad (std::istream &in);
 
   /**
-   * Load the user flags located on quads.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on quads.  See also @ref GlossUserFlags .
    */
   void load_user_flags_quad (const std::vector<bool> &v);
 
@@ -2376,58 +2176,56 @@ public:
   void save_user_flags_hex (std::ostream &out) const;
 
   /**
-   * Same as above, but store the flags to a bitvector rather than to
-   * a file.  The output vector is resized if necessary.  See also
-   * @ref GlossUserFlags .
+   * Same as above, but store the flags to a bitvector rather than to a file.
+   * The output vector is resized if necessary.  See also @ref GlossUserFlags
+   * .
    */
   void save_user_flags_hex (std::vector<bool> &v) const;
 
   /**
-   * Load the user flags located on hexs.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on hexs.  See also @ref GlossUserFlags .
    */
   void load_user_flags_hex (std::istream &in);
 
   /**
-   * Load the user flags located on hexs.  See also @ref
-   * GlossUserFlags .
+   * Load the user flags located on hexs.  See also @ref GlossUserFlags .
    */
   void load_user_flags_hex (const std::vector<bool> &v);
 
   /**
-   * Clear all user pointers and indices and allow the use of both for
-   * next access.  See also @ref GlossUserData .
+   * Clear all user pointers and indices and allow the use of both for next
+   * access.  See also @ref GlossUserData .
    */
   void clear_user_data ();
 
   /**
    * @deprecated User clear_user_data() instead.
    *
-   *  Clear all user pointers.  See also @ref GlossUserData .
+   * Clear all user pointers.  See also @ref GlossUserData .
    */
   void clear_user_pointers () DEAL_II_DEPRECATED;
 
   /**
-   * Save all user indices. The output vector is resized if necessary.
-   * See also @ref GlossUserData .
+   * Save all user indices. The output vector is resized if necessary. See
+   * also @ref GlossUserData .
    */
   void save_user_indices (std::vector<unsigned int> &v) const;
 
   /**
-   * Read the information stored by save_user_indices().  See also
-   * @ref GlossUserData .
+   * Read the information stored by save_user_indices().  See also @ref
+   * GlossUserData .
    */
   void load_user_indices (const std::vector<unsigned int> &v);
 
   /**
-   * Save all user pointers. The output vector is resized if
-   * necessary.  See also @ref GlossUserData .
+   * Save all user pointers. The output vector is resized if necessary.  See
+   * also @ref GlossUserData .
    */
   void save_user_pointers (std::vector<void *> &v) const;
 
   /**
-   * Read the information stored by save_user_pointers().  See also
-   * @ref GlossUserData .
+   * Read the information stored by save_user_pointers().  See also @ref
+   * GlossUserData .
    */
   void load_user_pointers (const std::vector<void *> &v);
 
@@ -2438,8 +2236,7 @@ public:
   void save_user_indices_line (std::vector<unsigned int> &v) const;
 
   /**
-   * Load the user indices located on lines.  See also @ref
-   * GlossUserData .
+   * Load the user indices located on lines.  See also @ref GlossUserData .
    */
   void load_user_indices_line (const std::vector<unsigned int> &v);
 
@@ -2450,8 +2247,7 @@ public:
   void save_user_indices_quad (std::vector<unsigned int> &v) const;
 
   /**
-   * Load the user indices located on quads.  See also @ref
-   * GlossUserData .
+   * Load the user indices located on quads.  See also @ref GlossUserData .
    */
   void load_user_indices_quad (const std::vector<unsigned int> &v);
 
@@ -2462,8 +2258,7 @@ public:
   void save_user_indices_hex (std::vector<unsigned int> &v) const;
 
   /**
-   * Load the user indices located on hexs.  See also @ref
-   * GlossUserData .
+   * Load the user indices located on hexs.  See also @ref GlossUserData .
    */
   void load_user_indices_hex (const std::vector<unsigned int> &v);
   /**
@@ -2473,8 +2268,7 @@ public:
   void save_user_pointers_line (std::vector<void *> &v) const;
 
   /**
-   * Load the user pointers located on lines.  See also @ref
-   * GlossUserData .
+   * Load the user pointers located on lines.  See also @ref GlossUserData .
    */
   void load_user_pointers_line (const std::vector<void *> &v);
 
@@ -2485,8 +2279,7 @@ public:
   void save_user_pointers_quad (std::vector<void *> &v) const;
 
   /**
-   * Load the user pointers located on quads.  See also @ref
-   * GlossUserData .
+   * Load the user pointers located on quads.  See also @ref GlossUserData .
    */
   void load_user_pointers_quad (const std::vector<void *> &v);
 
@@ -2497,8 +2290,7 @@ public:
   void save_user_pointers_hex (std::vector<void *> &v) const;
 
   /**
-   * Load the user pointers located on hexs.  See also @ref
-   * GlossUserData .
+   * Load the user pointers located on hexs.  See also @ref GlossUserData .
    */
   void load_user_pointers_hex (const std::vector<void *> &v);
 
@@ -2512,63 +2304,63 @@ public:
    */
 
   /**
-   *  Iterator to the first used cell on level @p level.
+   * Iterator to the first used cell on level @p level.
    */
   cell_iterator        begin       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active cell on level @p level. If the
-   *  given level does not contain any active cells (i.e., all cells
-   *  on this level are further refined, then this function returns
-   *  <code>end_active(level)</code> so that loops of the kind
+   * Iterator to the first active cell on level @p level. If the given level
+   * does not contain any active cells (i.e., all cells on this level are
+   * further refined, then this function returns
+   * <code>end_active(level)</code> so that loops of the kind
    *  @code
    *    for (cell=tria.begin_active(level); cell!=tria.end_active(level); ++cell)
    *      ...
    *  @endcode
-   *  have zero iterations, as may be expected if there are no active
-   *  cells on this level.
+   * have zero iterations, as may be expected if there are no active cells on
+   * this level.
    */
   active_cell_iterator begin_active(const unsigned int level = 0) const;
 
   /**
-   *  Iterator past the end; this iterator serves for comparisons of
-   *  iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   cell_iterator        end () const;
 
   /**
-   * Return an iterator which is the first iterator not on level. If
-   * @p level is the last level, then this returns <tt>end()</tt>.
+   * Return an iterator which is the first iterator not on level. If @p level
+   * is the last level, then this returns <tt>end()</tt>.
    */
   cell_iterator        end (const unsigned int level) const;
 
   /**
-   * Return an active iterator which is the first active iterator not
-   * on the given level. If @p level is the last level, then this
-   * returns <tt>end()</tt>.
+   * Return an active iterator which is the first active iterator not on the
+   * given level. If @p level is the last level, then this returns
+   * <tt>end()</tt>.
    */
   active_cell_iterator end_active (const unsigned int level) const;
 
 
   /**
-   *  Return an iterator pointing to the last used cell.
+   * Return an iterator pointing to the last used cell.
    */
   cell_iterator        last () const;
 
   /**
-   *  Return an iterator pointing to the last active cell.
+   * Return an iterator pointing to the last active cell.
    */
   active_cell_iterator last_active () const;
 
   /**
-   *  @name Cell iterator functions returning ranges of iterators
+   * @name Cell iterator functions returning ranges of iterators
    */
 
   /**
-   * Return an iterator range that contains all cells (active or not)
-   * that make up this triangulation. Such a range is useful to
-   * initialize range-based for loops as supported by C++11. See the
-   * example in the documentation of active_cell_iterators().
+   * Return an iterator range that contains all cells (active or not) that
+   * make up this triangulation. Such a range is useful to initialize range-
+   * based for loops as supported by C++11. See the example in the
+   * documentation of active_cell_iterators().
    *
    * @return The half open range <code>[this->begin(), this->end())</code>
    *
@@ -2577,18 +2369,16 @@ public:
   IteratorRange<cell_iterator>        cell_iterators () const;
 
   /**
-   * Return an iterator range that contains all active cells
-   * that make up this triangulation. Such a range is useful to
-   * initialize range-based for loops as supported by C++11,
-   * see also @ref CPP11 "C++11 standard".
+   * Return an iterator range that contains all active cells that make up this
+   * triangulation. Such a range is useful to initialize range-based for loops
+   * as supported by C++11, see also @ref CPP11 "C++11 standard".
    *
-   * Range-based for loops are useful in that they require much less
-   * code than traditional loops (see
-   * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
-   * for a discussion of how they work). An example is that without
-   * range-based for loops, one often writes code such as the following
-   * (assuming for a moment that our goal is setting the user flag
-   * on every active cell):
+   * Range-based for loops are useful in that they require much less code than
+   * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
+   * #Range-based_for_loop">here</a> for a discussion of how they work). An
+   * example is that without range-based for loops, one often writes code such
+   * as the following (assuming for a moment that our goal is setting the user
+   * flag on every active cell):
    * @code
    *   Triangulation<dim> triangulation;
    *   ...
@@ -2598,8 +2388,8 @@ public:
    *   for (; cell!=endc; ++cell)
    *     cell->set_user_flag();
    * @endcode
-   * Using C++11's range-based for loops, this is now entirely
-   * equivalent to the following:
+   * Using C++11's range-based for loops, this is now entirely equivalent to
+   * the following:
    * @code
    *   Triangulation<dim> triangulation;
    *   ...
@@ -2608,21 +2398,22 @@ public:
    * @endcode
    * To use this feature, you need a compiler that supports C++11.
    *
-   * @return The half open range <code>[this->begin_active(), this->end())</code>
+   * @return The half open range <code>[this->begin_active(),
+   * this->end())</code>
    *
    * @ingroup CPP11
    */
   IteratorRange<active_cell_iterator> active_cell_iterators () const;
 
   /**
-   * Return an iterator range that contains all cells (active or not)
-   * that make up the given level of this triangulation. Such a range is useful to
-   * initialize range-based for loops as supported by C++11. See the
-   * example in the documentation of active_cell_iterators().
+   * Return an iterator range that contains all cells (active or not) that
+   * make up the given level of this triangulation. Such a range is useful to
+   * initialize range-based for loops as supported by C++11. See the example
+   * in the documentation of active_cell_iterators().
    *
    * @param[in] level A given level in the refinement hierarchy of this
-   *   triangulation.
-   * @return The half open range <code>[this->begin(level), this->end(level))</code>
+   * triangulation. @return The half open range <code>[this->begin(level),
+   * this->end(level))</code>
    *
    * @pre level must be less than this->n_levels().
    *
@@ -2631,14 +2422,14 @@ public:
   IteratorRange<cell_iterator>        cell_iterators_on_level (const unsigned int level) const;
 
   /**
-   * Return an iterator range that contains all active cells
-   * that make up the given level of this triangulation. Such a range is useful to
-   * initialize range-based for loops as supported by C++11. See the
-   * example in the documentation of active_cell_iterators().
+   * Return an iterator range that contains all active cells that make up the
+   * given level of this triangulation. Such a range is useful to initialize
+   * range-based for loops as supported by C++11. See the example in the
+   * documentation of active_cell_iterators().
    *
    * @param[in] level A given level in the refinement hierarchy of this
-   *   triangulation.
-   * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+   * triangulation. @return The half open range
+   * <code>[this->begin_active(level), this->end(level))</code>
    *
    * @pre level must be less than this->n_levels().
    *
@@ -2659,18 +2450,18 @@ public:
    */
 
   /**
-   *  Iterator to the first used face.
+   * Iterator to the first used face.
    */
   face_iterator        begin_face       () const;
 
   /**
-   *  Iterator to the first active face.
+   * Iterator to the first active face.
    */
   active_face_iterator begin_active_face() const;
 
   /**
-   *  Iterator past the end; this iterator serves for comparisons of
-   *  iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   face_iterator        end_face () const;
 
@@ -2684,24 +2475,21 @@ public:
    */
 
   /**
-   * In the following, most functions are provided in two versions,
-   * with and without an argument describing the level. The versions
-   * with this argument are only applicable for objects describing the
-   * cells of the present triangulation. For example: in 2D
-   * <tt>n_lines(level)</tt> cannot be called, only
-   * <tt>n_lines()</tt>, as lines are faces in 2D and therefore have
-   * no level.
+   * In the following, most functions are provided in two versions, with and
+   * without an argument describing the level. The versions with this argument
+   * are only applicable for objects describing the cells of the present
+   * triangulation. For example: in 2D <tt>n_lines(level)</tt> cannot be
+   * called, only <tt>n_lines()</tt>, as lines are faces in 2D and therefore
+   * have no level.
    */
 
   /**
-   *  Return the total number of used lines,
-   *  active or not.
+   * Return the total number of used lines, active or not.
    */
   unsigned int n_lines () const;
 
   /**
-   *  Return the total number of used lines,
-   *  active or not on level @p level.
+   * Return the total number of used lines, active or not on level @p level.
    */
   unsigned int n_lines (const unsigned int level) const;
 
@@ -2711,81 +2499,67 @@ public:
   unsigned int n_active_lines () const;
 
   /**
-   *  Return the total number of active lines,
-   *  on level @p level.
+   * Return the total number of active lines, on level @p level.
    */
   unsigned int n_active_lines (const unsigned int level) const;
 
   /**
-   *  Return the total number of used quads,
-   *  active or not.
+   * Return the total number of used quads, active or not.
    */
   unsigned int n_quads () const;
 
   /**
-   *  Return the total number of used quads,
-   *  active or not on level @p level.
+   * Return the total number of used quads, active or not on level @p level.
    */
   unsigned int n_quads (const unsigned int level) const;
 
   /**
-   *  Return the total number of active quads,
-   *  active or not.
+   * Return the total number of active quads, active or not.
    */
   unsigned int n_active_quads () const;
 
   /**
-   *  Return the total number of active quads,
-   *  active or not on level @p level.
+   * Return the total number of active quads, active or not on level @p level.
    */
   unsigned int n_active_quads (const unsigned int level) const;
 
   /**
-   *  Return the total number of used
-   *  hexahedra, active or not.
+   * Return the total number of used hexahedra, active or not.
    */
   unsigned int n_hexs() const;
 
   /**
-   *  Return the total number of used
-   *  hexahedra, active or not on level @p
-   *  level.
+   * Return the total number of used hexahedra, active or not on level @p
+   * level.
    */
   unsigned int n_hexs(const unsigned int level) const;
 
   /**
-   *  Return the total number of active
-   *  hexahedra, active or not.
+   * Return the total number of active hexahedra, active or not.
    */
   unsigned int n_active_hexs() const;
 
   /**
-   *  Return the total number of active
-   *  hexahedra, active or not on level @p
-   *  level.
+   * Return the total number of active hexahedra, active or not on level @p
+   * level.
    */
   unsigned int n_active_hexs(const unsigned int level) const;
 
   /**
-   *  Return the total number of used cells,
-   *  active or not.  Maps to
-   *  <tt>n_lines()</tt> in one space
-   *  dimension and so on.
+   * Return the total number of used cells, active or not.  Maps to
+   * <tt>n_lines()</tt> in one space dimension and so on.
    */
   unsigned int n_cells () const;
 
   /**
-   *  Return the total number of used cells,
-   *  active or not, on level @p level.
-   *  Maps to <tt>n_lines(level)</tt> in
-   *  one space dimension and so on.
+   * Return the total number of used cells, active or not, on level @p level.
+   * Maps to <tt>n_lines(level)</tt> in one space dimension and so on.
    */
   unsigned int n_cells (const unsigned int level) const;
 
   /**
-   *  Return the total number of active cells.
-   *  Maps to <tt>n_active_lines()</tt> in
-   *  one space dimension and so on.
+   * Return the total number of active cells. Maps to
+   * <tt>n_active_lines()</tt> in one space dimension and so on.
    */
   unsigned int n_active_cells () const;
 
@@ -2800,59 +2574,49 @@ public:
 
 
   /**
-   * Return the total number of active cells on
-   * level @p level.  Maps to
-   * <tt>n_active_lines(level)</tt> in one
-   * space dimension and so on.
+   * Return the total number of active cells on level @p level.  Maps to
+   * <tt>n_active_lines(level)</tt> in one space dimension and so on.
    */
   unsigned int n_active_cells (const unsigned int level) const;
 
   /**
-   *  Return the total number of used faces,
-   *  active or not.  In 2D, the result
-   *  equals n_lines(), while in 3D it
-   *  equals n_quads(). Since there are no
-   *  face objects in 1d, the function
-   *  returns zero in 1d.
+   * Return the total number of used faces, active or not.  In 2D, the result
+   * equals n_lines(), while in 3D it equals n_quads(). Since there are no
+   * face objects in 1d, the function returns zero in 1d.
    */
   unsigned int n_faces () const;
 
   /**
-   *  Return the total number of active faces,
-   *  active or not.  In 2D, the result
-   *  equals n_active_lines(), while in 3D
-   *  it equals n_active_quads(). Since
-   *  there are no face objects in 1d, the
-   *  function returns zero in 1d.
+   * Return the total number of active faces, active or not.  In 2D, the
+   * result equals n_active_lines(), while in 3D it equals n_active_quads().
+   * Since there are no face objects in 1d, the function returns zero in 1d.
    */
   unsigned int n_active_faces () const;
 
   /**
    * Return the number of levels in this triangulation.
    *
-   * @note Internally, triangulations store data in levels, and there
-   * may be more levels in this data structure than one may think --
-   * for example, imagine a triangulation that we just got by
-   * coarsening the highest level so that it was completely
-   * depopulated. That level is not removed, since it will most likely
-   * be repopulated soon by the next refinement process. As a consequence,
-   * if you happened to run through raw cell iterators (which you can't
-   * do as a user of this class, but can internally), then the number
-   * of objects in the levels hierarchy is larger than the level of the most
-   * refined cell plus one. On the other hand, since this is rarely what a
-   * user of this class cares about, the function really just returns the
-   * level of the most refined active cell plus one. (The plus one is
-   * because in a coarse, unrefined mesh, all cells have level zero --
-   * making the number of levels equal to one.)
+   * @note Internally, triangulations store data in levels, and there may be
+   * more levels in this data structure than one may think -- for example,
+   * imagine a triangulation that we just got by coarsening the highest level
+   * so that it was completely depopulated. That level is not removed, since
+   * it will most likely be repopulated soon by the next refinement process.
+   * As a consequence, if you happened to run through raw cell iterators
+   * (which you can't do as a user of this class, but can internally), then
+   * the number of objects in the levels hierarchy is larger than the level of
+   * the most refined cell plus one. On the other hand, since this is rarely
+   * what a user of this class cares about, the function really just returns
+   * the level of the most refined active cell plus one. (The plus one is
+   * because in a coarse, unrefined mesh, all cells have level zero -- making
+   * the number of levels equal to one.)
    */
   unsigned int n_levels () const;
 
   /**
-   * Return the number of levels in use. This function is equivalent
-   * to n_levels() for a serial Triangulation, but gives the maximum
-   * of n_levels() over all processors for a
-   * parallel::distributed::Triangulation and therefore can be larger
-   * than n_levels().
+   * Return the number of levels in use. This function is equivalent to
+   * n_levels() for a serial Triangulation, but gives the maximum of
+   * n_levels() over all processors for a parallel::distributed::Triangulation
+   * and therefore can be larger than n_levels().
    */
   virtual
   unsigned int n_global_levels () const;
@@ -2860,46 +2624,38 @@ public:
   /**
    * Return true if the triangulation has hanging nodes.
    *
-   * The function is made virtual since the result can be interpreted in different
-   * ways, depending on whether the triangulation lives only on a single processor,
-   * or may be distributed as done in the parallel::distributed::Triangulation
-   * class (see there for a description of what the function is supposed to do in the
-   * parallel context).
+   * The function is made virtual since the result can be interpreted in
+   * different ways, depending on whether the triangulation lives only on a
+   * single processor, or may be distributed as done in the
+   * parallel::distributed::Triangulation class (see there for a description
+   * of what the function is supposed to do in the parallel context).
    */
   virtual
   bool has_hanging_nodes() const;
 
   /**
-   * Return the total number of
-   * vertices.  Some of them may
-   * not be used, which usually
-   * happens upon coarsening of a
-   * triangulation when some
-   * vertices are discarded, but we
-   * do not want to renumber the
-   * remaining ones, leading to
-   * holes in the numbers of used
-   * vertices.  You can get the
-   * number of used vertices using
-   * @p n_used_vertices function.
+   * Return the total number of vertices.  Some of them may not be used, which
+   * usually happens upon coarsening of a triangulation when some vertices are
+   * discarded, but we do not want to renumber the remaining ones, leading to
+   * holes in the numbers of used vertices.  You can get the number of used
+   * vertices using @p n_used_vertices function.
    */
   unsigned int n_vertices () const;
 
   /**
    * Return a constant reference to all the vertices present in this
-   * triangulation. Note that not necessarily all vertices in this
-   * array are actually used; for example, if you coarsen a mesh, then
-   * some vertices are deleted, but their positions in this array are
-   * unchanged as the indices of vertices are only allocated once. You
-   * can find out about which vertices are actually used by the
-   * function get_used_vertices().
+   * triangulation. Note that not necessarily all vertices in this array are
+   * actually used; for example, if you coarsen a mesh, then some vertices are
+   * deleted, but their positions in this array are unchanged as the indices
+   * of vertices are only allocated once. You can find out about which
+   * vertices are actually used by the function get_used_vertices().
    */
   const std::vector<Point<spacedim> > &
   get_vertices () const;
 
   /**
-   * Return the number of vertices that are presently in use,
-   * i.e. belong to at least one used element.
+   * Return the number of vertices that are presently in use, i.e. belong to
+   * at least one used element.
    */
   unsigned int n_used_vertices () const;
 
@@ -2909,32 +2665,30 @@ public:
   bool vertex_used (const unsigned int index) const;
 
   /**
-   * Return a constant reference to the array of @p bools indicating
-   * whether an entry in the vertex array is used or not.
+   * Return a constant reference to the array of @p bools indicating whether
+   * an entry in the vertex array is used or not.
    */
   const std::vector<bool> &
   get_used_vertices () const;
 
   /**
-   * Return the maximum number of cells meeting at a common
-   * vertex. Since this number is an invariant under refinement, only
-   * the cells on the coarsest level are considered. The operation is
-   * thus reasonably fast. The invariance is only true for
-   * sufficiently many cells in the coarsest triangulation (e.g. for a
-   * single cell one would be returned), so a minimum of four is
-   * returned in two dimensions, 8 in three dimensions, etc, which is
-   * how many cells meet if the triangulation is refined.
+   * Return the maximum number of cells meeting at a common vertex. Since this
+   * number is an invariant under refinement, only the cells on the coarsest
+   * level are considered. The operation is thus reasonably fast. The
+   * invariance is only true for sufficiently many cells in the coarsest
+   * triangulation (e.g. for a single cell one would be returned), so a
+   * minimum of four is returned in two dimensions, 8 in three dimensions,
+   * etc, which is how many cells meet if the triangulation is refined.
    *
    * In one space dimension, two is returned.
    */
   unsigned int max_adjacent_cells () const;
 
   /**
-   * This function always returns @p invalid_subdomain_id but is there
-   * for compatibility with the derived @p
-   * parallel::distributed::Triangulation class. For distributed
-   * parallel triangulations this function returns the subdomain id of
-   * those cells that are owned by the current processor.
+   * This function always returns @p invalid_subdomain_id but is there for
+   * compatibility with the derived @p parallel::distributed::Triangulation
+   * class. For distributed parallel triangulations this function returns the
+   * subdomain id of those cells that are owned by the current processor.
    */
   virtual types::subdomain_id locally_owned_subdomain () const;
 
@@ -2950,153 +2704,89 @@ public:
   /**
    * Total number of lines, used or unused.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_lines () const;
 
   /**
-   * Number of lines, used or
-   * unused, on the given level.
+   * Number of lines, used or unused, on the given level.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_lines (const unsigned int level) const;
 
   /**
-   * Total number of quads, used or
-   * unused.
+   * Total number of quads, used or unused.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_quads () const;
 
   /**
-   * Number of quads, used or
-   * unused, on the given level.
+   * Number of quads, used or unused, on the given level.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_quads (const unsigned int level) const;
 
   /**
-   * Total number of hexs, used or
-   * unused.
+   * Total number of hexs, used or unused.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_hexs () const;
 
   /**
-   * Number of hexs, used or
-   * unused, on the given level.
+   * Number of hexs, used or unused, on the given level.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_hexs (const unsigned int level) const;
 
   /**
-   * Number of cells, used or
-   * unused, on the given level.
+   * Number of cells, used or unused, on the given level.
    *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_cells (const unsigned int level) const;
 
   /**
-   * Return the total number of faces,
-   * used or not. In 2d, the result
-   * equals n_raw_lines(), while in 3d it
-   * equals n_raw_quads().
-   *
-   * @note This function really
-   * exports internal information
-   * about the triangulation. It
-   * shouldn't be used in
-   * applications. The function is
-   * only part of the public
-   * interface of this class
-   * because it is used in some of
-   * the other classes that build
-   * very closely on it (in
-   * particular, the DoFHandler
-   * class).
+   * Return the total number of faces, used or not. In 2d, the result equals
+   * n_raw_lines(), while in 3d it equals n_raw_quads().
+   *
+   * @note This function really exports internal information about the
+   * triangulation. It shouldn't be used in applications. The function is only
+   * part of the public interface of this class because it is used in some of
+   * the other classes that build very closely on it (in particular, the
+   * DoFHandler class).
    */
   unsigned int n_raw_faces () const;
 
@@ -3105,12 +2795,12 @@ public:
    */
 
   /**
-   * Determine an estimate for the memory consumption (in bytes) of
-   * this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * This function is made virtual, since a triangulation object might
-   * be accessed through a pointer to this base class, even if the
-   * actual object is a derived class.
+   * This function is made virtual, since a triangulation object might be
+   * accessed through a pointer to this base class, even if the actual object
+   * is a derived class.
    */
   virtual std::size_t memory_consumption () const;
 
@@ -3118,10 +2808,9 @@ public:
    * Write the data of this object to a stream for the purpose of
    * serialization.
    *
-   * @note This function does not save <i>all</i> member variables of
-   * the current triangulation. Rather, only certain kinds of
-   * information are stored. For more information see the general
-   * documentation of this class.
+   * @note This function does not save <i>all</i> member variables of the
+   * current triangulation. Rather, only certain kinds of information are
+   * stored. For more information see the general documentation of this class.
    */
   template <class Archive>
   void save (Archive &ar,
@@ -3131,17 +2820,16 @@ public:
    * Read the data of this object from a stream for the purpose of
    * serialization. Throw away the previous content.
    *
-   * @note This function does not reset <i>all</i> member variables of
-   * the current triangulation to the ones of the triangulation that
-   * was previously stored to an archive. Rather, only certain kinds
-   * of information are loaded. For more information see the general
+   * @note This function does not reset <i>all</i> member variables of the
+   * current triangulation to the ones of the triangulation that was
+   * previously stored to an archive. Rather, only certain kinds of
+   * information are loaded. For more information see the general
    * documentation of this class.
    *
    * @note This function calls the Triangulation::clear() function and
-   * consequently triggers the "clear" signal. After loading all data
-   * from the archive, it then triggers the "create" signal. For more
-   * information on signals, see the general documentation of this
-   * class.
+   * consequently triggers the "clear" signal. After loading all data from the
+   * archive, it then triggers the "create" signal. For more information on
+   * signals, see the general documentation of this class.
    */
   template <class Archive>
   void load (Archive &ar,
@@ -3155,7 +2843,7 @@ public:
    */
 
   /**
-   *  Exception @ingroup Exceptions
+   * Exception @ingroup Exceptions
    */
   DeclException1 (ExcInvalidLevel,
                   int,
@@ -3199,26 +2887,23 @@ public:
 
 protected:
   /**
-   *  Do some smoothing in the process of refining the
-   *  triangulation. See the general doc of this class for more
-   *  information about this.
+   * Do some smoothing in the process of refining the triangulation. See the
+   * general doc of this class for more information about this.
    */
   MeshSmoothing                    smooth_grid;
 
   /**
-   *  Write a bool vector to the given stream, writing a pre- and a
-   *  postfix magic number. The vector is written in an almost binary
-   *  format, i.e. the bool flags are packed but the data is written
-   *  as ASCII text.
+   * Write a bool vector to the given stream, writing a pre- and a postfix
+   * magic number. The vector is written in an almost binary format, i.e. the
+   * bool flags are packed but the data is written as ASCII text.
    *
-   *  The flags are stored in a binary format: for each @p true, a @p
-   *  1 bit is stored, a @p 0 bit otherwise.  The bits are stored as
-   *  <tt>unsigned char</tt>, thus avoiding endianess. They are
-   *  written to @p out in plain text, thus amounting to 3.6 bits in
-   *  the output per bits in the input on the average. Other
-   *  information (magic numbers and number of elements of the input
-   *  vector) is stored as plain text as well. The format should
-   *  therefore be interplatform compatible.
+   * The flags are stored in a binary format: for each @p true, a @p 1 bit is
+   * stored, a @p 0 bit otherwise.  The bits are stored as <tt>unsigned
+   * char</tt>, thus avoiding endianess. They are written to @p out in plain
+   * text, thus amounting to 3.6 bits in the output per bits in the input on
+   * the average. Other information (magic numbers and number of elements of
+   * the input vector) is stored as plain text as well. The format should
+   * therefore be interplatform compatible.
    */
   static void write_bool_vector (const unsigned int       magic_number1,
                                  const std::vector<bool> &v,
@@ -3226,8 +2911,8 @@ protected:
                                  std::ostream            &out);
 
   /**
-   * Re-read a vector of bools previously written by @p
-   * write_bool_vector and compare with the magic numbers.
+   * Re-read a vector of bools previously written by @p write_bool_vector and
+   * compare with the magic numbers.
    */
   static void read_bool_vector (const unsigned int       magic_number1,
                                 std::vector<bool>       &v,
@@ -3241,13 +2926,12 @@ private:
    */
 
   /**
-   * Declare a number of iterator types for raw iterators, i.e.,
-   * iterators that also iterate over holes in the list of cells left
-   * by cells that have been coarsened away in previous mesh
-   * refinement cycles.
+   * Declare a number of iterator types for raw iterators, i.e., iterators
+   * that also iterate over holes in the list of cells left by cells that have
+   * been coarsened away in previous mesh refinement cycles.
    *
-   * Since users should never have to access these internal properties
-   * of how we store data, these iterator types are made private.
+   * Since users should never have to access these internal properties of how
+   * we store data, these iterator types are made private.
    */
   typedef TriaRawIterator   <CellAccessor<dim,spacedim>         > raw_cell_iterator;
   typedef TriaRawIterator   <TriaAccessor<dim-1, dim, spacedim> > raw_face_iterator;
@@ -3256,15 +2940,14 @@ private:
   typedef typename IteratorSelector::raw_hex_iterator             raw_hex_iterator;
 
   /**
-   *  Iterator to the first cell, used or not, on level @p level. If a
-   *  level has no cells, a past-the-end iterator is returned.
+   * Iterator to the first cell, used or not, on level @p level. If a level
+   * has no cells, a past-the-end iterator is returned.
    */
   raw_cell_iterator    begin_raw   (const unsigned int level = 0) const;
 
   /**
-   * Return a raw iterator which is the first iterator not on
-   * level. If @p level is the last level, then this returns
-   * <tt>end()</tt>.
+   * Return a raw iterator which is the first iterator not on level. If @p
+   * level is the last level, then this returns <tt>end()</tt>.
    */
   raw_cell_iterator    end_raw (const unsigned int level) const;
 
@@ -3278,30 +2961,29 @@ private:
    */
 
   /**
-   *  Iterator to the first line, used or not, on level @p level. If a
-   *  level has no lines, a past-the-end iterator is returned.  If
-   *  lines are no cells, i.e. for @p dim>1 no @p level argument must
-   *  be given.  The same applies for all the other functions above,
-   *  of course.
+   * Iterator to the first line, used or not, on level @p level. If a level
+   * has no lines, a past-the-end iterator is returned.  If lines are no
+   * cells, i.e. for @p dim>1 no @p level argument must be given.  The same
+   * applies for all the other functions above, of course.
    */
   raw_line_iterator
   begin_raw_line   (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first used line on level @p level.
+   * Iterator to the first used line on level @p level.
    */
   line_iterator
   begin_line       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active line on level @p level.
+   * Iterator to the first active line on level @p level.
    */
   active_line_iterator
   begin_active_line(const unsigned int level = 0) const;
 
   /**
-   *  Iterator past the end; this iterator serves for comparisons of
-   *  iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   line_iterator        end_line () const;
 
@@ -3315,30 +2997,28 @@ private:
    */
 
   /**
-   *  Iterator to the first quad, used or not, on the given level. If
-   *  a level has no quads, a past-the-end iterator is returned.  If
-   *  quads are no cells, i.e. for $dim>2$ no level argument must be
-   *  given.
-
+   * Iterator to the first quad, used or not, on the given level. If a level
+   * has no quads, a past-the-end iterator is returned.  If quads are no
+   * cells, i.e. for $dim>2$ no level argument must be given.
    */
   raw_quad_iterator
   begin_raw_quad   (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first used quad on level @p level.
+   * Iterator to the first used quad on level @p level.
    */
   quad_iterator
   begin_quad       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active quad on level @p level.
+   * Iterator to the first active quad on level @p level.
    */
   active_quad_iterator
   begin_active_quad (const unsigned int level = 0) const;
 
   /**
-   *  Iterator past the end; this iterator serves for comparisons of
-   *  iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   quad_iterator
   end_quad () const;
@@ -3353,27 +3033,27 @@ private:
    */
 
   /**
-   *  Iterator to the first hex, used or not, on level @p level. If a
-   *  level has no hexs, a past-the-end iterator is returned.
+   * Iterator to the first hex, used or not, on level @p level. If a level has
+   * no hexs, a past-the-end iterator is returned.
    */
   raw_hex_iterator
   begin_raw_hex   (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first used hex on level @p level.
+   * Iterator to the first used hex on level @p level.
    */
   hex_iterator
   begin_hex       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active hex on level @p level.
+   * Iterator to the first active hex on level @p level.
    */
   active_hex_iterator
   begin_active_hex (const unsigned int level = 0) const;
 
   /**
-   *  Iterator past the end; this iterator serves for comparisons of
-   *  iterators with past-the-end or before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   hex_iterator
   end_hex () const;
@@ -3384,77 +3064,75 @@ private:
 
 
   /**
-   * The (public) function clear() will only work when the
-   * triangulation is not subscribed to by other users. The
-   * clear_despite_subscriptions() function now allows the
-   * triangulation being cleared even when there are subscriptions.
+   * The (public) function clear() will only work when the triangulation is
+   * not subscribed to by other users. The clear_despite_subscriptions()
+   * function now allows the triangulation being cleared even when there are
+   * subscriptions.
    *
-   * Make sure, you know what you do, when calling this function, as
-   * its use is reasonable in very rare cases, only. For example, when
-   * the subscriptions were for the initially empty Triangulation and
-   * the Triangulation object wants to release its memory before
-   * throwing an assertion due to input errors (e.g. in the
-   * create_triangulation() function).
+   * Make sure, you know what you do, when calling this function, as its use
+   * is reasonable in very rare cases, only. For example, when the
+   * subscriptions were for the initially empty Triangulation and the
+   * Triangulation object wants to release its memory before throwing an
+   * assertion due to input errors (e.g. in the create_triangulation()
+   * function).
    */
   void clear_despite_subscriptions ();
 
   /**
-   *  Refine all cells on all levels which were previously flagged for
-   *  refinement.
+   * Refine all cells on all levels which were previously flagged for
+   * refinement.
    *
-   *  Note, that this function uses the <tt>line->user_flags</tt> for
-   *  <tt>dim=2,3</tt> and the <tt>quad->user_flags</tt> for
-   *  <tt>dim=3</tt>.
+   * Note, that this function uses the <tt>line->user_flags</tt> for
+   * <tt>dim=2,3</tt> and the <tt>quad->user_flags</tt> for <tt>dim=3</tt>.
    *
-   *  The function returns a list of cells that have produced children
-   *  that satisfy the criteria of @ref GlossDistorted "distorted
-   *  cells" if the <code>check_for_distorted_cells</code> flag was
-   *  specified upon creation of this object, at
+   * The function returns a list of cells that have produced children that
+   * satisfy the criteria of @ref GlossDistorted "distorted cells" if the
+   * <code>check_for_distorted_cells</code> flag was specified upon creation
+   * of this object, at
    */
   DistortedCellList execute_refinement ();
 
   /**
-   * Coarsen all cells which were flagged for coarsening, or rather:
-   * delete all children of those cells of which all child cells are
-   * flagged for coarsening and several other constraints hold (see
-   * the general doc of this class).
+   * Coarsen all cells which were flagged for coarsening, or rather: delete
+   * all children of those cells of which all child cells are flagged for
+   * coarsening and several other constraints hold (see the general doc of
+   * this class).
    */
   void execute_coarsening ();
 
   /**
-   * Make sure that either all or none of the children of a cell are
-   * tagged for coarsening.
+   * Make sure that either all or none of the children of a cell are tagged
+   * for coarsening.
    */
   void fix_coarsen_flags ();
 
   /**
-   *  Array of pointers pointing to the objects storing the cell data
-   *  on the different levels.
+   * Array of pointers pointing to the objects storing the cell data on the
+   * different levels.
    */
   std::vector<dealii::internal::Triangulation::TriaLevel<dim>*> levels;
 
   /**
-   *  Pointer to the faces of the triangulation. In 1d this contains
-   *  nothing, in 2D it contains data concerning lines and in 3D quads
-   *  and lines.  All of these have no level and are therefore treated
-   *  separately.
+   * Pointer to the faces of the triangulation. In 1d this contains nothing,
+   * in 2D it contains data concerning lines and in 3D quads and lines.  All
+   * of these have no level and are therefore treated separately.
    */
   dealii::internal::Triangulation::TriaFaces<dim> *faces;
 
 
   /**
-   *  Array of the vertices of this triangulation.
+   * Array of the vertices of this triangulation.
    */
   std::vector<Point<spacedim> >              vertices;
 
   /**
-   *  Array storing a bit-pattern which vertices are used.
+   * Array storing a bit-pattern which vertices are used.
    */
   std::vector<bool>                     vertices_used;
 
   /**
-   *  Collection of manifold objects. We store only objects, which are
-   *  not of type FlatManifold.
+   * Collection of manifold objects. We store only objects, which are not of
+   * type FlatManifold.
    */
   std::map<types::manifold_id, SmartPointer<const Manifold<dim,spacedim> , Triangulation<dim, spacedim> > >  manifold;
 
@@ -3466,74 +3144,71 @@ private:
 
 
   /**
-   * A flag that determines whether we are to check for distorted
-   * cells upon creation and refinement of a mesh.
+   * A flag that determines whether we are to check for distorted cells upon
+   * creation and refinement of a mesh.
    */
   const bool check_for_distorted_cells;
 
   /**
-   * Cache to hold the numbers of lines, quads, hexes, etc. These
-   * numbers are set at the end of the refinement and coarsening
-   * functions and enable faster access later on. In the old days,
-   * whenever one wanted to access one of these numbers, one had to
-   * perform a loop over all lines, e.g., and count the elements until
-   * we hit the end iterator. This is time consuming and since access
-   * to the number of lines etc is a rather frequent operation, this
-   * was not an optimal solution.
+   * Cache to hold the numbers of lines, quads, hexes, etc. These numbers are
+   * set at the end of the refinement and coarsening functions and enable
+   * faster access later on. In the old days, whenever one wanted to access
+   * one of these numbers, one had to perform a loop over all lines, e.g., and
+   * count the elements until we hit the end iterator. This is time consuming
+   * and since access to the number of lines etc is a rather frequent
+   * operation, this was not an optimal solution.
    */
   dealii::internal::Triangulation::NumberCache<dim> number_cache;
 
   /**
-   * A map that relates the number of a boundary vertex to the
-   * boundary indicator. This field is only used in 1d. We have this
-   * field because we store boundary indicator information with faces
-   * in 2d and higher where we have space in the structures that store
-   * data for faces, but in 1d there is no such space for faces.
+   * A map that relates the number of a boundary vertex to the boundary
+   * indicator. This field is only used in 1d. We have this field because we
+   * store boundary indicator information with faces in 2d and higher where we
+   * have space in the structures that store data for faces, but in 1d there
+   * is no such space for faces.
    *
-   * The field is declared as a pointer for a rather mundane reason:
-   * all other fields of this class that can be modified by the
-   * TriaAccessor hierarchy are pointers, and so these accessor
-   * classes store a const pointer to the triangulation. We could no
-   * longer do so for TriaAccessor<0,1,spacedim> if this field (that
-   * can be modified by TriaAccessor::set_boundary_indicator) were not
-   * a pointer.
+   * The field is declared as a pointer for a rather mundane reason: all other
+   * fields of this class that can be modified by the TriaAccessor hierarchy
+   * are pointers, and so these accessor classes store a const pointer to the
+   * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
+   * this field (that can be modified by TriaAccessor::set_boundary_indicator)
+   * were not a pointer.
    */
   std::map<unsigned int, types::boundary_id> *vertex_to_boundary_id_map_1d;
 
 
   /**
-   * A map that relates the number of a boundary vertex to the
-   * manifold indicator. This field is only used in 1d. We have this
-   * field because we store manifold indicator information with faces
-   * in 2d and higher where we have space in the structures that store
-   * data for faces, but in 1d there is no such space for faces.
+   * A map that relates the number of a boundary vertex to the manifold
+   * indicator. This field is only used in 1d. We have this field because we
+   * store manifold indicator information with faces in 2d and higher where we
+   * have space in the structures that store data for faces, but in 1d there
+   * is no such space for faces.
    *
    * @note Manifold objects are pretty useless for points since they are
    * neither refined nor are their interiors mapped. We nevertheless allow
    * storing manifold ids for points to be consistent in dimension-independent
    * programs.
    *
-   * The field is declared as a pointer for a rather mundane reason:
-   * all other fields of this class that can be modified by the
-   * TriaAccessor hierarchy are pointers, and so these accessor
-   * classes store a const pointer to the triangulation. We could no
-   * longer do so for TriaAccessor<0,1,spacedim> if this field (that
-   * can be modified by TriaAccessor::set_boundary_indicator) were not
-   * a pointer.
+   * The field is declared as a pointer for a rather mundane reason: all other
+   * fields of this class that can be modified by the TriaAccessor hierarchy
+   * are pointers, and so these accessor classes store a const pointer to the
+   * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
+   * this field (that can be modified by TriaAccessor::set_boundary_indicator)
+   * were not a pointer.
    */
   std::map<unsigned int, types::manifold_id> *vertex_to_manifold_id_map_1d;
 
 
   /**
-   * A map that correlates each refinement listener that has been
-   * added through the outdated RefinementListener interface via
-   * add_refinement_listener(), with the new-style boost::signal
-   * connections for each of the member function. We need to keep this
-   * list around so that we can later terminate the connection again
-   * when someone calls remove_refinement_listener().
+   * A map that correlates each refinement listener that has been added
+   * through the outdated RefinementListener interface via
+   * add_refinement_listener(), with the new-style boost::signal connections
+   * for each of the member function. We need to keep this list around so that
+   * we can later terminate the connection again when someone calls
+   * remove_refinement_listener().
    *
-   * The data type is a multimap since, although this would be weird,
-   * the same object may add itself multiple times as a listener.
+   * The data type is a multimap since, although this would be weird, the same
+   * object may add itself multiple times as a listener.
    */
   mutable
   std::multimap<const RefinementListener *, std::vector<boost::signals2::connection> >
index a681fd1256f0693952b0c1a52d5494166f2b3d83..e6ee86873d39f3324ab71e849eee0b57dd6e91a5 100644 (file)
@@ -53,13 +53,9 @@ namespace internal
     struct Implementation;
 
     /**
-     * Implementation of a type with
-     * which to store the level of an
-     * accessor object. We only need
-     * it for the case that
-     * <tt>structdim ==
-     * dim</tt>. Otherwise, an empty
-     * object is sufficient.
+     * Implementation of a type with which to store the level of an accessor
+     * object. We only need it for the case that <tt>structdim == dim</tt>.
+     * Otherwise, an empty object is sufficient.
      */
     template <int structdim, int dim> struct PresentLevelType
     {
@@ -72,9 +68,7 @@ namespace internal
         {}
 
         /**
-         * Dummy
-         * constructor. Only
-         * level zero is allowed.
+         * Dummy constructor. Only level zero is allowed.
          */
         type (const int level)
         {
@@ -83,9 +77,7 @@ namespace internal
         }
 
         /**
-         * Dummy conversion
-         * operator. Returns
-         * level zero.
+         * Dummy conversion operator. Returns level zero.
          */
         operator int () const
         {
@@ -106,13 +98,9 @@ namespace internal
 
 
     /**
-     * Implementation of a type with
-     * which to store the level of an
-     * accessor object. We only need
-     * it for the case that
-     * <tt>structdim ==
-     * dim</tt>. Otherwise, an empty
-     * object is sufficient.
+     * Implementation of a type with which to store the level of an accessor
+     * object. We only need it for the case that <tt>structdim == dim</tt>.
+     * Otherwise, an empty object is sufficient.
      */
     template <int dim> struct PresentLevelType<dim,dim>
     {
@@ -142,28 +130,22 @@ namespace TriaAccessorExceptions
    */
   DeclException0 (ExcCellNotUsed);
   /**
-   * The cell is not an @ref
-   * GlossActive "active" cell, but
-   * it already has children. Some
-   * operations, like setting
-   * refinement flags or accessing
-   * degrees of freedom are only
-   * possible on active cells.
+   * The cell is not an @ref GlossActive "active" cell, but it already has
+   * children. Some operations, like setting refinement flags or accessing
+   * degrees of freedom are only possible on active cells.
    *
    * @ingroup Exceptions
    */
   DeclException0 (ExcCellNotActive);
   /**
-   * Trying to access the children of
-   * a cell which is in fact active.
+   * Trying to access the children of a cell which is in fact active.
    *
    * @ingroup Exceptions
    */
   DeclException0 (ExcCellHasNoChildren);
   /**
-   * Trying to access the parent of
-   * a cell which is in the coarsest
-   * level of the triangulation.
+   * Trying to access the parent of a cell which is in the coarsest level of
+   * the triangulation.
    *
    * @ingroup Exceptions
    */
@@ -213,13 +195,9 @@ namespace TriaAccessorExceptions
    */
   DeclException0 (ExcNeighborIsNotCoarser);
   /**
-   * You are trying to access the
-   * level of a face, but faces have
-   * no inherent level. The level of
-   * a face can only be determined by
-   * the level of an adjacent face,
-   * which in turn implies that a
-   * face can have several levels.
+   * You are trying to access the level of a face, but faces have no inherent
+   * level. The level of a face can only be determined by the level of an
+   * adjacent face, which in turn implies that a face can have several levels.
    *
    * @ingroup Exceptions
    */
@@ -236,25 +214,26 @@ namespace TriaAccessorExceptions
 
 
 /**
- * A base class for the accessor classes used by TriaRawIterator and
- * derived classes.
+ * A base class for the accessor classes used by TriaRawIterator and derived
+ * classes.
  *
- * This class offers only the basic functionality required by the
- * iterators (stores the necessary data members, offers comparison
- * operators and the like), but has no functionality to actually
- * dereference data. This is done in the derived classes.
+ * This class offers only the basic functionality required by the iterators
+ * (stores the necessary data members, offers comparison operators and the
+ * like), but has no functionality to actually dereference data. This is done
+ * in the derived classes.
  *
- * In the implementation, the behavior of this class differs between
- * the cases where <tt>structdim==dim</tt> (cells of a mesh) and
- * <tt>structdim&lt;dim</tt> (faces and edges). For the latter,
- * #present_level is always equal to zero and the constructors may not
- * receive a positive value there. For cells, any level is
- * possible, but only those within the range of the levels of the
- * Triangulation are reasonable. Furthermore, the function objects()
- * returns either the container with all cells on the same level or
- * the container with all objects of this dimension (<tt>structdim&lt;dim</tt>).
+ * In the implementation, the behavior of this class differs between the cases
+ * where <tt>structdim==dim</tt> (cells of a mesh) and
+ * <tt>structdim&lt;dim</tt> (faces and edges). For the latter, #present_level
+ * is always equal to zero and the constructors may not receive a positive
+ * value there. For cells, any level is possible, but only those within the
+ * range of the levels of the Triangulation are reasonable. Furthermore, the
+ * function objects() returns either the container with all cells on the same
+ * level or the container with all objects of this dimension
+ * (<tt>structdim&lt;dim</tt>).
  *
- * Some internals of this class are discussed in @ref IteratorAccessorInternals .
+ * Some internals of this class are discussed in @ref
+ * IteratorAccessorInternals .
  *
  * @ingroup grid
  * @ingroup Accessors
@@ -265,57 +244,36 @@ class TriaAccessorBase
 {
 public:
   /**
-   *  Dimension of the space the
-   *  object represented by this
-   *  accessor lives in. For
-   *  example, if this accessor
-   *  represents a quad that is
-   *  part of a two-dimensional
-   *  surface in four-dimensional
-   *  space, then this value is
-   *  four.
+   * Dimension of the space the object represented by this accessor lives in.
+   * For example, if this accessor represents a quad that is part of a two-
+   * dimensional surface in four-dimensional space, then this value is four.
    */
   static const unsigned int space_dimension = spacedim;
 
   /**
-   * Dimensionality of the object
-   * that the thing represented by
-   * this accessopr is part of. For
-   * example, if this accessor
-   * represents a line that is part
-   * of a hexahedron, then this
-   * value will be three.
+   * Dimensionality of the object that the thing represented by this accessopr
+   * is part of. For example, if this accessor represents a line that is part
+   * of a hexahedron, then this value will be three.
    */
   static const unsigned int dimension = dim;
 
   /**
-   * Dimensionality of the current
-   * object represented by this
-   * accessor. For example, if it
-   * is line (irrespective of
-   * whether it is part of a quad
-   * or hex, and what dimension we
-   * are in), then this value
-   * equals 1.
+   * Dimensionality of the current object represented by this accessor. For
+   * example, if it is line (irrespective of whether it is part of a quad or
+   * hex, and what dimension we are in), then this value equals 1.
    */
   static const unsigned int structure_dimension = structdim;
 
 protected:
   /**
-   * Declare the data type that
-   * this accessor class expects to
-   * get passed from the iterator
-   * classes. Since the pure
-   * triangulation iterators need
-   * no additional data, this data
-   * type is @p void.
+   * Declare the data type that this accessor class expects to get passed from
+   * the iterator classes. Since the pure triangulation iterators need no
+   * additional data, this data type is @p void.
    */
   typedef void AccessorData;
 
   /**
-   *  Constructor. Protected, thus
-   *  only callable from friend
-   *  classes.
+   * Constructor. Protected, thus only callable from friend classes.
    */
   TriaAccessorBase (const Triangulation<dim,spacedim> *parent =  0,
                     const int                 level  = -1,
@@ -323,60 +281,46 @@ protected:
                     const AccessorData             * =  0);
 
   /**
-   *  Copy constructor. Creates an
-   *  object with exactly the same data.
+   * Copy constructor. Creates an object with exactly the same data.
    */
   TriaAccessorBase (const TriaAccessorBase &);
 
   /**
-   *  Copy operator. Since this is
-   *  only called from iterators,
-   *  do not return anything, since
-   *  the iterator will return
-   *  itself.
+   * Copy operator. Since this is only called from iterators, do not return
+   * anything, since the iterator will return itself.
    *
-   *  This method is protected,
-   *  since it is only to be called
-   *  from the iterator class.
+   * This method is protected, since it is only to be called from the iterator
+   * class.
    */
   void copy_from (const TriaAccessorBase &);
 
   /**
-   *  Copy operator. Creates an
-   *  object with exactly the same data.
+   * Copy operator. Creates an object with exactly the same data.
    */
   TriaAccessorBase &operator = (const TriaAccessorBase &);
 
   /**
-   * Ordering of accessors. If #structure_dimension is less than
-   * #dimension, we simply compare the index of such an object. If
-   * #structure_dimension equals #dimension, we compare the level()
-   * first, and the index() only if levels are equal.
+   * Ordering of accessors. If #structure_dimension is less than #dimension,
+   * we simply compare the index of such an object. If #structure_dimension
+   * equals #dimension, we compare the level() first, and the index() only if
+   * levels are equal.
    */
   bool operator < (const TriaAccessorBase &other) const;
 
 protected:
   /**
-   *  Copy operator. This is normally
-   *  used in a context like
-   *  <tt>iterator a,b;  *a=*b;</tt>. Since
-   *  the meaning is to copy the object
-   *  pointed to by @p b to the object
-   *  pointed to by @p a and since
-   *  accessors are not real but
-   *  virtual objects, this operation
-   *  is not useful for iterators on
-   *  triangulations. We declare this
-   *  function here private, thus it may
-   *  not be used from outside.
-   *  Furthermore it is not implemented
-   *  and will give a linker error if
-   *  used anyway.
+   * Copy operator. This is normally used in a context like <tt>iterator a,b;
+   * *a=*b;</tt>. Since the meaning is to copy the object pointed to by @p b
+   * to the object pointed to by @p a and since accessors are not real but
+   * virtual objects, this operation is not useful for iterators on
+   * triangulations. We declare this function here private, thus it may not be
+   * used from outside. Furthermore it is not implemented and will give a
+   * linker error if used anyway.
    */
   void operator = (const TriaAccessorBase *);
 
   /**
-   *  Compare for equality.
+   * Compare for equality.
    */
   bool operator == (const TriaAccessorBase &) const;
 
@@ -392,31 +336,20 @@ protected:
    * @{
    */
   /**
-   *  This operator advances the
-   *  iterator to the next element.
+   * This operator advances the iterator to the next element.
    *
-   *  For @p dim=1 only:
-   *  The next element is next on
-   *  this level if there are
-   *  more. If the present element
-   *  is the last on this level,
-   *  the first on the next level
-   *  is accessed.
+   * For @p dim=1 only: The next element is next on this level if there are
+   * more. If the present element is the last on this level, the first on the
+   * next level is accessed.
    */
   void operator ++ ();
 
   /**
-   *  This operator moves the
-   *  iterator to the previous
-   *  element.
+   * This operator moves the iterator to the previous element.
    *
-   *  For @p dim=1 only:
-   *  The previous element is
-   *  previous on this level if
-   *  <tt>index>0</tt>. If the present
-   *  element is the first on this
-   *  level, the last on the
-   *  previous level is accessed.
+   * For @p dim=1 only: The previous element is previous on this level if
+   * <tt>index>0</tt>. If the present element is the first on this level, the
+   * last on the previous level is accessed.
    */
   void operator -- ();
   /**
@@ -424,20 +357,16 @@ protected:
    */
 
   /**
-   * Access to the other objects of
-   * a Triangulation with same
-   * dimension.
+   * Access to the other objects of a Triangulation with same dimension.
    */
   dealii::internal::Triangulation::TriaObjects<dealii::internal::Triangulation::TriaObject<structdim> > &
   objects () const;
 
 public:
   /**
-   * Data type to be used for passing
-   * parameters from iterators to the
-   * accessor classes in a unified
-   * way, no matter what the type of
-   * number of these parameters is.
+   * Data type to be used for passing parameters from iterators to the
+   * accessor classes in a unified way, no matter what the type of number of
+   * these parameters is.
    */
   typedef void *LocalData;
 
@@ -455,63 +384,54 @@ public:
    *
    * @note Within a Triangulation object, cells are uniquely identified by a
    * pair <code>(level, index)</code> where the former is the cell's
-   * refinement level and the latter is the index of the cell within
-   * this refinement level (the former being what this function
-   * returns). Consequently, there may be multiple cells on different
-   * refinement levels but with the same index within their level.
-   * Contrary to this, if the current object corresponds to a face or
-   * edge, then the object is uniquely identified solely by its index
-   * as faces and edges do not have a refinement level. For these objects,
-   * the current function always returns zero as the level.
+   * refinement level and the latter is the index of the cell within this
+   * refinement level (the former being what this function returns).
+   * Consequently, there may be multiple cells on different refinement levels
+   * but with the same index within their level. Contrary to this, if the
+   * current object corresponds to a face or edge, then the object is uniquely
+   * identified solely by its index as faces and edges do not have a
+   * refinement level. For these objects, the current function always returns
+   * zero as the level.
    */
   int level () const;
 
   /**
-   * Return the index of the
-   * element presently pointed to
-   * on the present level.
+   * Return the index of the element presently pointed to on the present
+   * level.
    *
-   * Within a Triangulation object, cells are uniquely identified by a
-   * pair <code>(level, index)</code> where the former is the cell's
-   * refinement level and the latter is the index of the cell within
-   * this refinement level (the latter being what this function
-   * returns). Consequently, there may be multiple cells on different
-   * refinement levels but with the same index within their level.
-   * Contrary to this, if the current object corresponds to a face or
-   * edge, then the object is uniquely identified solely by its index
-   * as faces and edges do not have a refinement level.
-   *
-   * @note The indices objects returned by this function are not a
-   * contiguous set of numbers on each level: going from cell to cell,
-   * some of the indices in a level may be unused.
+   * Within a Triangulation object, cells are uniquely identified by a pair
+   * <code>(level, index)</code> where the former is the cell's refinement
+   * level and the latter is the index of the cell within this refinement
+   * level (the latter being what this function returns). Consequently, there
+   * may be multiple cells on different refinement levels but with the same
+   * index within their level. Contrary to this, if the current object
+   * corresponds to a face or edge, then the object is uniquely identified
+   * solely by its index as faces and edges do not have a refinement level.
+   *
+   * @note The indices objects returned by this function are not a contiguous
+   * set of numbers on each level: going from cell to cell, some of the
+   * indices in a level may be unused.
    *
    * @note If the triangulation is actually of type
-   * parallel::distributed::Triangulation then the indices are
-   * relatively only to that part of the distributed triangulation
-   * that is stored on the current processor. In other words, cells
-   * living in the partitions of the triangulation stored on different
-   * processors may have the same index even if they refer to the same
-   * cell, and the may have different indices even if they do refer to
-   * the same cell (e.g., if a cell is owned by one processor but is a
-   * ghost cell on another).
+   * parallel::distributed::Triangulation then the indices are relatively only
+   * to that part of the distributed triangulation that is stored on the
+   * current processor. In other words, cells living in the partitions of the
+   * triangulation stored on different processors may have the same index even
+   * if they refer to the same cell, and the may have different indices even
+   * if they do refer to the same cell (e.g., if a cell is owned by one
+   * processor but is a ghost cell on another).
    */
   int index () const;
 
   /**
-   *  Return the state of the
-   *  iterator.  For the different
-   *  states an accessor can be in,
-   *  refer to the
-   *  TriaRawIterator
-   *  documentation.
+   * Return the state of the iterator.  For the different states an accessor
+   * can be in, refer to the TriaRawIterator documentation.
    */
   IteratorState::IteratorStates state () const;
 
   /**
-   * Return a pointer to the
-   * triangulation which the object
-   * pointed to by this class
-   * belongs to.
+   * Return a pointer to the triangulation which the object pointed to by this
+   * class belongs to.
    */
   const Triangulation<dim,spacedim> &get_triangulation () const;
 
@@ -520,23 +440,19 @@ public:
    */
 protected:
   /**
-   * The level if this is a cell
-   * (<tt>structdim==dim</tt>). Else,
-   * contains zero.
+   * The level if this is a cell (<tt>structdim==dim</tt>). Else, contains
+   * zero.
    */
   typename dealii::internal::TriaAccessor::PresentLevelType<structdim,dim>::type present_level;
 
   /**
-   *  Used to store the index of
-   *  the element presently pointed
-   *  to on the level presentl
-   *  used.
+   * Used to store the index of the element presently pointed to on the level
+   * presentl used.
    */
   int present_index;
 
   /**
-   *  Pointer to the triangulation
-   *  which we act on.
+   * Pointer to the triangulation which we act on.
    */
   const Triangulation<dim,spacedim> *tria;
 
@@ -550,23 +466,21 @@ private:
 
 
 /**
- * A class that represents accessor objects to iterators that don't
- * make sense such as quad iterators in on 1d meshes.  This class can
- * not be used to create objects (it will in fact throw an exception
- * if this should ever be attempted but it sometimes allows code to be
- * written in a simpler way in a dimension independent way. For
- * example, it allows to write code that works on quad iterators that
- * is dimension independent because quad iterators (with the current
- * class) exist and are syntactically correct. You can not expect,
- * however, to ever generate one of these iterators, meaning you need
- * to expect to wrap the code block in which you use quad iterators
- * into something like <code>if (dim@>1)</code> -- which makes eminent
- * sense anyway.
+ * A class that represents accessor objects to iterators that don't make sense
+ * such as quad iterators in on 1d meshes.  This class can not be used to
+ * create objects (it will in fact throw an exception if this should ever be
+ * attempted but it sometimes allows code to be written in a simpler way in a
+ * dimension independent way. For example, it allows to write code that works
+ * on quad iterators that is dimension independent because quad iterators
+ * (with the current class) exist and are syntactically correct. You can not
+ * expect, however, to ever generate one of these iterators, meaning you need
+ * to expect to wrap the code block in which you use quad iterators into
+ * something like <code>if (dim@>1)</code> -- which makes eminent sense
+ * anyway.
  *
- * This class provides the minimal interface necessary for Accessor
- * classes to interact with Iterator classes. However, this is only
- * for syntactic correctness, none of the functions do anything but
- * generate errors.
+ * This class provides the minimal interface necessary for Accessor classes to
+ * interact with Iterator classes. However, this is only for syntactic
+ * correctness, none of the functions do anything but generate errors.
  *
  * @ingroup Accessors
  * @author Wolfgang Bangerth, 2008
@@ -576,22 +490,15 @@ class InvalidAccessor :  public TriaAccessorBase<structdim,dim,spacedim>
 {
 public:
   /**
-   * Propagate typedef from
-   * base class to this class.
+   * Propagate typedef from base class to this class.
    */
   typedef typename TriaAccessorBase<structdim,dim,spacedim>::AccessorData AccessorData;
 
   /**
-   * Constructor.  This class is
-   * used for iterators that make
-   * sense in a given dimension,
-   * for example quads for 1d
-   * meshes. Consequently, while
-   * the creation of such objects
-   * is syntactically valid, they
-   * make no semantic sense, and we
-   * generate an exception when
-   * such an object is actually
+   * Constructor.  This class is used for iterators that make sense in a given
+   * dimension, for example quads for 1d meshes. Consequently, while the
+   * creation of such objects is syntactically valid, they make no semantic
+   * sense, and we generate an exception when such an object is actually
    * generated.
    */
   InvalidAccessor (const Triangulation<dim,spacedim> *parent     =  0,
@@ -600,26 +507,17 @@ public:
                    const AccessorData       *local_data =  0);
 
   /**
-   * Copy constructor.  This class
-   * is used for iterators that
-   * make sense in a given
-   * dimension, for example quads
-   * for 1d meshes. Consequently,
-   * while the creation of such
-   * objects is syntactically
-   * valid, they make no semantic
-   * sense, and we generate an
-   * exception when such an object
-   * is actually generated.
+   * Copy constructor.  This class is used for iterators that make sense in a
+   * given dimension, for example quads for 1d meshes. Consequently, while the
+   * creation of such objects is syntactically valid, they make no semantic
+   * sense, and we generate an exception when such an object is actually
+   * generated.
    */
   InvalidAccessor (const InvalidAccessor &);
 
   /**
-   * Conversion from other
-   * accessors to the current
-   * invalid one. This of course
-   * also leads to a run-time
-   * error.
+   * Conversion from other accessors to the current invalid one. This of
+   * course also leads to a run-time error.
    */
   template <typename OtherAccessor>
   InvalidAccessor (const OtherAccessor &);
@@ -636,23 +534,20 @@ public:
   bool operator != (const InvalidAccessor &) const;
 
   /**
-   * Dummy operators to make things
-   * compile. Does nothing.
+   * Dummy operators to make things compile. Does nothing.
    */
   void operator ++ () const;
   void operator -- () const;
 
   /**
-   * Dummy function representing
-   * whether the accessor points to
-   * a used or an unused object.
+   * Dummy function representing whether the accessor points to a used or an
+   * unused object.
    */
   bool used () const;
 
   /**
-   * Dummy function representing
-   * whether the accessor points to
-   * an object that has children.
+   * Dummy function representing whether the accessor points to an object that
+   * has children.
    */
   bool has_children () const;
 };
@@ -660,17 +555,16 @@ public:
 
 
 /**
- * A class that provides access to objects in a triangulation such as
- * its vertices, sub-objects, children, geometric information, etc.
- * This class represents objects of dimension <code>structdim</code>
- * (i.e. 1 for lines, 2 for quads, 3 for hexes) in a triangulation of
- * dimensionality <code>dim</code> (i.e. 1 for a triangulation of
- * lines, 2 for a triangulation of quads, and 3 for a triangulation of
- * hexes) that is embedded in a space of dimensionality
- * <code>spacedim</code> (for <code>spacedim==dim</code> the
- * triangulation represents a domain in $R^{dim}$, for
- * <code>spacedim@>dim</code> the triangulation is of a manifold
- * embedded in a higher dimensional space).
+ * A class that provides access to objects in a triangulation such as its
+ * vertices, sub-objects, children, geometric information, etc. This class
+ * represents objects of dimension <code>structdim</code> (i.e. 1 for lines, 2
+ * for quads, 3 for hexes) in a triangulation of dimensionality
+ * <code>dim</code> (i.e. 1 for a triangulation of lines, 2 for a
+ * triangulation of quads, and 3 for a triangulation of hexes) that is
+ * embedded in a space of dimensionality <code>spacedim</code> (for
+ * <code>spacedim==dim</code> the triangulation represents a domain in
+ * $R^{dim}$, for <code>spacedim@>dim</code> the triangulation is of a
+ * manifold embedded in a higher dimensional space).
  *
  * @ingroup Accessors
  * @author Wolfgang Bangerth and others, 1998, 2000, 2008
@@ -680,15 +574,14 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
 {
 public:
   /**
-   * Propagate typedef from
-   * base class to this class.
+   * Propagate typedef from base class to this class.
    */
   typedef
   typename TriaAccessorBase<structdim,dim,spacedim>::AccessorData
   AccessorData;
 
   /**
-   *  Constructor.
+   * Constructor.
    */
   TriaAccessor (const Triangulation<dim,spacedim> *parent     =  0,
                 const int                 level      = -1,
@@ -696,158 +589,120 @@ public:
                 const AccessorData       *local_data =  0);
 
   /**
-   * Conversion constructor. This
-   * constructor exists to make certain
-   * constructs simpler to write in
-   * dimension independent code. For
-   * example, it allows assigning a face
-   * iterator to a line iterator, an
-   * operation that is useful in 2d but
-   * doesn't make any sense in 3d. The
-   * constructor here exists for the
-   * purpose of making the code conform to
-   * C++ but it will unconditionally abort;
-   * in other words, assigning a face
-   * iterator to a line iterator is better
-   * put into an if-statement that checks
-   * that the dimension is two, and assign
-   * to a quad iterator in 3d (an operator
-   * that, without this constructor would
-   * be illegal if we happen to compile for
+   * Conversion constructor. This constructor exists to make certain
+   * constructs simpler to write in dimension independent code. For example,
+   * it allows assigning a face iterator to a line iterator, an operation that
+   * is useful in 2d but doesn't make any sense in 3d. The constructor here
+   * exists for the purpose of making the code conform to C++ but it will
+   * unconditionally abort; in other words, assigning a face iterator to a
+   * line iterator is better put into an if-statement that checks that the
+   * dimension is two, and assign to a quad iterator in 3d (an operator that,
+   * without this constructor would be illegal if we happen to compile for
    * 2d).
    */
   template <int structdim2, int dim2, int spacedim2>
   TriaAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Another conversion operator
-   * between objects that don't
-   * make sense, just like the
-   * previous one.
+   * Another conversion operator between objects that don't make sense, just
+   * like the previous one.
    */
   template <int structdim2, int dim2, int spacedim2>
   TriaAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   *  Test for the element being
-   *  used or not.  The return
-   *  value is @p true for all
-   *  iterators that are either
-   *  normal iterators or active
-   *  iterators, only raw iterators
-   *  can return @p false. Since
-   *  raw iterators are only used
-   *  in the interiors of the
-   *  library, you will not usually
-   *  need this function.
+   * Test for the element being used or not.  The return value is @p true for
+   * all iterators that are either normal iterators or active iterators, only
+   * raw iterators can return @p false. Since raw iterators are only used in
+   * the interiors of the library, you will not usually need this function.
    */
   bool used () const;
 
   /**
-   *  @name Accessing sub-objects
+   * @name Accessing sub-objects
    */
   /**
    * @{
    */
 
   /**
-   *  Return the global index of i-th
-   *  vertex of the current object. The
-   *  convention regarding the numbering of
-   *  vertices is laid down in the
-   *  documentation of the GeometryInfo
-   *  class.
+   * Return the global index of i-th vertex of the current object. The
+   * convention regarding the numbering of vertices is laid down in the
+   * documentation of the GeometryInfo class.
    *
-   *  Note that the returned value is only
-   *  the index of the geometrical
-   *  vertex. It has nothing to do with
-   *  possible degrees of freedom
-   *  associated with it. For this, see the
-   *  @p DoFAccessor::vertex_dof_index
-   *  functions.
+   * Note that the returned value is only the index of the geometrical vertex.
+   * It has nothing to do with possible degrees of freedom associated with it.
+   * For this, see the @p DoFAccessor::vertex_dof_index functions.
    *
-   *  @note Despite the name, the index returned here is only
-   *  global in the sense that it is specific to a particular
-   *  Triangulation object or, in the case the triangulation is
-   *  actually of type parallel::distributed::Triangulation,
-   *  specific to that part of the distributed triangulation stored
-   *  on the current processor.
+   * @note Despite the name, the index returned here is only global in the
+   * sense that it is specific to a particular Triangulation object or, in the
+   * case the triangulation is actually of type
+   * parallel::distributed::Triangulation, specific to that part of the
+   * distributed triangulation stored on the current processor.
    */
   unsigned int vertex_index (const unsigned int i) const;
 
   /**
-   *  Return a reference to the
-   *  @p ith vertex. The reference is not const, i.e., it is possible
-   *  to call this function on the left hand side of an assignment,
-   *  thereby moving the vertex of a cell within the triangulation. Of
-   *  course, doing so requires that you ensure that the new location
-   *  of the vertex remains useful -- for example, avoiding inverted
-   *  or otherwise distorted (see also @ref GlossDistorted "this glossary entry").
-   *
-   *  @note When a cell is refined, its children inherit the position
-   *  of the vertex positions of those vertices they share with the mother
-   *  cell (plus the locations of the new vertices on edges, faces, and
-   *  cell interiors that are created for the new child cells). If the
-   *  vertex of a cell is moved, this implies that its children will also
-   *  use these new locations. On the other hand, imagine a 2d situation
-   *  where you have one cell that is refined (with four children) and then
-   *  you move the central vertex connecting all four children. If you
-   *  coarsen these four children again to the mother cell, then the
-   *  location of the moved vertex is lost and if, in a later step, you
-   *  refine the mother cell again, the then again new vertex will be
-   *  placed again at the same position as the first time around -- i.e.,
-   *  not at the location you had previously moved it to.
-   *
-   *  @note The behavior described above is relevant if
-   *  you have a parallel::distributed::Triangulation object. There,
-   *  refining a mesh always involves a re-partitioning. In other words,
-   *  vertices of locally owned cells (see
-   *  @ref GlossLocallyOwnedCell "this glossary entry")
-   *  that you may have moved to a different location on one processor
-   *  may be moved to a different processor upon mesh refinement (even
-   *  if these particular cells were not refined) which will re-create
-   *  their position based on the position of the coarse cells they
-   *  previously had, not based on the position these vertices had on
-   *  the processor that previously owned them. In other words, in
-   *  parallel computations, you will probably have to move nodes
-   *  explicitly after every mesh refinement because vertex positions
-   *  may or may not be preserved across the re-partitioning that
-   *  accompanies mesh refinement.
+   * Return a reference to the @p ith vertex. The reference is not const,
+   * i.e., it is possible to call this function on the left hand side of an
+   * assignment, thereby moving the vertex of a cell within the triangulation.
+   * Of course, doing so requires that you ensure that the new location of the
+   * vertex remains useful -- for example, avoiding inverted or otherwise
+   * distorted (see also @ref GlossDistorted "this glossary entry").
+   *
+   * @note When a cell is refined, its children inherit the position of the
+   * vertex positions of those vertices they share with the mother cell (plus
+   * the locations of the new vertices on edges, faces, and cell interiors
+   * that are created for the new child cells). If the vertex of a cell is
+   * moved, this implies that its children will also use these new locations.
+   * On the other hand, imagine a 2d situation where you have one cell that is
+   * refined (with four children) and then you move the central vertex
+   * connecting all four children. If you coarsen these four children again to
+   * the mother cell, then the location of the moved vertex is lost and if, in
+   * a later step, you refine the mother cell again, the then again new vertex
+   * will be placed again at the same position as the first time around --
+   * i.e., not at the location you had previously moved it to.
+   *
+   * @note The behavior described above is relevant if you have a
+   * parallel::distributed::Triangulation object. There, refining a mesh
+   * always involves a re-partitioning. In other words, vertices of locally
+   * owned cells (see @ref GlossLocallyOwnedCell "this glossary entry") that
+   * you may have moved to a different location on one processor may be moved
+   * to a different processor upon mesh refinement (even if these particular
+   * cells were not refined) which will re-create their position based on the
+   * position of the coarse cells they previously had, not based on the
+   * position these vertices had on the processor that previously owned them.
+   * In other words, in parallel computations, you will probably have to move
+   * nodes explicitly after every mesh refinement because vertex positions may
+   * or may not be preserved across the re-partitioning that accompanies mesh
+   * refinement.
    */
   Point<spacedim> &vertex (const unsigned int i) const;
 
   /**
-   * Pointer to the @p ith line
-   * bounding this object.
+   * Pointer to the @p ith line bounding this object.
    */
   typename dealii::internal::Triangulation::Iterators<dim,spacedim>::line_iterator
   line (const unsigned int i) const;
 
   /**
-   * Line index of the @p ith
-   * line bounding this object.
+   * Line index of the @p ith line bounding this object.
    *
-   * Implemented only for
-   * <tt>structdim>1</tt>,
-   * otherwise an exception
+   * Implemented only for <tt>structdim>1</tt>, otherwise an exception
    * generated.
    */
   unsigned int line_index (const unsigned int i) const;
 
   /**
-   * Pointer to the @p ith quad
-   * bounding this object.
+   * Pointer to the @p ith quad bounding this object.
    */
   typename dealii::internal::Triangulation::Iterators<dim,spacedim>::quad_iterator
   quad (const unsigned int i) const;
 
   /**
-   * Quad index of the @p ith
-   * quad bounding this object.
+   * Quad index of the @p ith quad bounding this object.
    *
-   * Implemented only for
-   * <tt>structdim>2</tt>,
-   * otherwise an exception
+   * Implemented only for <tt>structdim>2</tt>, otherwise an exception
    * generated.
    */
   unsigned int quad_index (const unsigned int i) const;
@@ -856,84 +711,56 @@ public:
    */
 
   /**
-   *  @name Orientation of sub-objects
+   * @name Orientation of sub-objects
    */
   /**
    * @{
    */
 
   /**
-   * Return whether the face with
-   * index @p face has its normal
-   * pointing in the standard
-   * direction (@p true) or
-   * whether it is the opposite
-   * (@p false). Which is the
-   * standard direction is
-   * documented with the
-   * GeometryInfo class. In
-   * 1d and 2d, this is always
-   * @p true, but in 3d it may be
-   * different, see the respective
-   * discussion in the
-   * documentation of the
+   * Return whether the face with index @p face has its normal pointing in the
+   * standard direction (@p true) or whether it is the opposite (@p false).
+   * Which is the standard direction is documented with the GeometryInfo
+   * class. In 1d and 2d, this is always @p true, but in 3d it may be
+   * different, see the respective discussion in the documentation of the
    * GeometryInfo class.
    *
-   * This function is really only
-   * for internal use in the
-   * library unless you absolutely
-   * know what this is all about.
+   * This function is really only for internal use in the library unless you
+   * absolutely know what this is all about.
    */
   bool face_orientation (const unsigned int face) const;
 
   /**
-   * Return whether the face with index @p
-   * face is rotated by 180 degrees (@p true)
-   * or or not (@p false). In 1d and 2d, this
-   * is always @p false, but in 3d it may be
-   * different, see the respective discussion
-   * in the documentation of the
-   * GeometryInfo class.
+   * Return whether the face with index @p face is rotated by 180 degrees (@p
+   * true) or or not (@p false). In 1d and 2d, this is always @p false, but in
+   * 3d it may be different, see the respective discussion in the
+   * documentation of the GeometryInfo class.
    *
-   * This function is really only
-   * for internal use in the
-   * library unless you absolutely
-   * know what this is all about.
+   * This function is really only for internal use in the library unless you
+   * absolutely know what this is all about.
    */
   bool face_flip (const unsigned int face) const;
 
   /**
-   * Return whether the face with index @p
-   * face is rotated by 90 degrees (@p true)
-   * or or not (@p false). In 1d and 2d, this
-   * is always @p false, but in 3d it may be
-   * different, see the respective discussion
-   * in the documentation of the
-   * GeometryInfo class.
+   * Return whether the face with index @p face is rotated by 90 degrees (@p
+   * true) or or not (@p false). In 1d and 2d, this is always @p false, but in
+   * 3d it may be different, see the respective discussion in the
+   * documentation of the GeometryInfo class.
    *
-   * This function is really only
-   * for internal use in the
-   * library unless you absolutely
-   * know what this is all about.
+   * This function is really only for internal use in the library unless you
+   * absolutely know what this is all about.
    */
   bool face_rotation (const unsigned int face) const;
 
   /**
-   * Return whether the line with index @p
-   * line is oriented in standard
-   * direction. @p true indicates, that the
-   * line is oriented from vertex 0 to vertex
-   * 1, whereas it is the other way around
-   * otherwise. In 1d and 2d, this is always
-   * @p true, but in 3d it may be different,
-   * see the respective discussion in the
-   * documentation of the
-   * GeometryInfo classe.
+   * Return whether the line with index @p line is oriented in standard
+   * direction. @p true indicates, that the line is oriented from vertex 0 to
+   * vertex 1, whereas it is the other way around otherwise. In 1d and 2d,
+   * this is always @p true, but in 3d it may be different, see the respective
+   * discussion in the documentation of the GeometryInfo classe.
    *
-   * This function is really only
-   * for internal use in the
-   * library unless you absolutely
-   * know what this is all about.
+   * This function is really only for internal use in the library unless you
+   * absolutely know what this is all about.
    */
   bool line_orientation (const unsigned int line) const;
   /**
@@ -941,123 +768,86 @@ public:
    */
 
   /**
-   *  @name Accessing children
+   * @name Accessing children
    */
   /**
    * @{
    */
 
   /**
-   *  Test whether the object has
-   *  children.
+   * Test whether the object has children.
    */
   bool has_children () const;
 
   /**
-   * Return the number of immediate
-   * children of this object. The
-   * number of children of an
-   * unrefined cell is zero.
+   * Return the number of immediate children of this object. The number of
+   * children of an unrefined cell is zero.
    */
   unsigned int n_children() const;
 
   /**
-   * Compute and return the number
-   * of active descendants of this
-   * objects. For example, if all
-   * of the eight children of a hex
-   * are further refined
-   * isotropically exactly once,
-   * the returned number will be
-   * 64, not 80.
-   *
-   * If the present cell is not
-   * refined, one is returned.
-   *
-   * If one considers a triangulation as a
-   * forest where the root of each tree are
-   * the coarse mesh cells and nodes have
-   * descendents (the children of a cell),
-   * then this function returns the number
-   * of terminal nodes in the sub-tree
-   * originating from the current object;
-   * consequently, if the current object is
-   * not further refined, the answer is
-   * one.
+   * Compute and return the number of active descendants of this objects. For
+   * example, if all of the eight children of a hex are further refined
+   * isotropically exactly once, the returned number will be 64, not 80.
+   *
+   * If the present cell is not refined, one is returned.
+   *
+   * If one considers a triangulation as a forest where the root of each tree
+   * are the coarse mesh cells and nodes have descendents (the children of a
+   * cell), then this function returns the number of terminal nodes in the
+   * sub-tree originating from the current object; consequently, if the
+   * current object is not further refined, the answer is one.
    */
   unsigned int number_of_children () const;
 
   /**
-   * Return the number of times
-   * that this object is
-   * refined. Note that not all its
-   * children are refined that
-   * often (which is why we prepend
-   * @p max_), the returned number
-   * is rather the maximum number
-   * of refinement in any branch of
-   * children of this object.
-   *
-   * For example, if this object is
-   * refined, and one of its children is
-   * refined exactly one more time, then
-   * <tt>max_refinement_depth</tt> should
+   * Return the number of times that this object is refined. Note that not all
+   * its children are refined that often (which is why we prepend @p max_),
+   * the returned number is rather the maximum number of refinement in any
+   * branch of children of this object.
+   *
+   * For example, if this object is refined, and one of its children is
+   * refined exactly one more time, then <tt>max_refinement_depth</tt> should
    * return 2.
    *
-   * If this object is not refined (i.e. it
-   * is active), then the return value is
-   * zero.
+   * If this object is not refined (i.e. it is active), then the return value
+   * is zero.
    */
   unsigned int max_refinement_depth () const;
 
   /**
-   *  Return an iterator to the @p ith
-   *  child.
+   * Return an iterator to the @p ith child.
    */
   TriaIterator<TriaAccessor<structdim,dim,spacedim> >
   child (const unsigned int i) const;
 
   /**
-   *  Return an iterator to that object
-   *  that is identical to the ith child
-   *  for isotropic refinement. If the
-   *  current object is refined
-   *  isotropically, then the returned
-   *  object is the ith child. If the
-   *  current object is refined
-   *  anisotropically, the returned child
-   *  may in fact be a grandchild of the
-   *  object, or may not exist at all (in
-   *  which case an exception is
-   *  generated).
+   * Return an iterator to that object that is identical to the ith child for
+   * isotropic refinement. If the current object is refined isotropically,
+   * then the returned object is the ith child. If the current object is
+   * refined anisotropically, the returned child may in fact be a grandchild
+   * of the object, or may not exist at all (in which case an exception is
+   * generated).
    */
   TriaIterator<TriaAccessor<structdim,dim,spacedim> >
   isotropic_child (const unsigned int i) const;
 
   /**
-   * Return the RefinementCase
-   * of this cell.
+   * Return the RefinementCase of this cell.
    */
   RefinementCase<structdim> refinement_case () const;
 
   /**
-   *  Index of the @p ith child.
-   *  The level of the child is one
-   *  higher than that of the
-   *  present cell, if the children
-   *  of a cell are accessed. The
-   *  children of faces have no level.
-   *  If the child does not exist, -1
-   *  is returned.
+   * Index of the @p ith child. The level of the child is one higher than that
+   * of the present cell, if the children of a cell are accessed. The children
+   * of faces have no level. If the child does not exist, -1 is returned.
    */
   int child_index (const unsigned int i) const;
 
   /**
-   *  Index of the @p ith isotropic child.
-   *  See the isotropic_child() function
-   *  for a definition of this concept.  If
-   *  the child does not exist, -1 is
-   *  returned.
+   * Index of the @p ith isotropic child. See the isotropic_child() function
+   * for a definition of this concept.  If the child does not exist, -1 is
+   * returned.
    */
   int isotropic_child_index (const unsigned int i) const;
   /**
@@ -1065,67 +855,46 @@ public:
    */
 
   /**
-   *  @name Dealing with boundary indicators
+   * @name Dealing with boundary indicators
    */
   /**
    * @{
    */
 
   /**
-   * Boundary indicator of this
-   * object.
+   * Boundary indicator of this object.
    *
-   * If the return value is the special
-   * value numbers::internal_face_boundary_id,
-   * then this object is in the
-   * interior of the domain.
+   * If the return value is the special value
+   * numbers::internal_face_boundary_id, then this object is in the interior
+   * of the domain.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
   types::boundary_id boundary_indicator () const;
 
   /**
-   * Set the boundary indicator.
-   * The same applies as for the
-   * <tt>boundary_indicator()</tt>
-   * function.
-   *
-   * Note that it only sets the
-   * boundary object of the current
-   * object itself, not the
-   * indicators of the ones that
-   * bound it. For example, in 3d,
-   * if this function is called on
-   * a face, then the boundary
-   * indicator of the 4 edges that
-   * bound the face remain
-   * unchanged. If you want to set
-   * the boundary indicators of
-   * face and edges at the same
-   * time, use the
-   * set_all_boundary_indicators()
-   * function. You can see the result of not using the correct function in the
-   * results section of step-49.
-   *
-   * @warning You should never set the
-   * boundary indicator of an interior face
-   * (a face not at the boundary of the
-   * domain), or set set the boundary
-   * indicator of an exterior face to
-   * numbers::internal_face_boundary_id
-   * (this value is reserved for another
-   * purpose). Algorithms may not work or
-   * produce very confusing results if
-   * boundary cells have a boundary
-   * indicator of numbers::internal_face_boundary_id
-   * or if interior cells have boundary
-   * indicators other than numbers::internal_face_boundary_id.
-   * Unfortunately, the current object
-   * has no means of finding out whether it
-   * really is at the boundary of the
-   * domain and so cannot determine whether
-   * the value you are trying to set makes
-   * sense under the current circumstances.
+   * Set the boundary indicator. The same applies as for the
+   * <tt>boundary_indicator()</tt> function.
+   *
+   * Note that it only sets the boundary object of the current object itself,
+   * not the indicators of the ones that bound it. For example, in 3d, if this
+   * function is called on a face, then the boundary indicator of the 4 edges
+   * that bound the face remain unchanged. If you want to set the boundary
+   * indicators of face and edges at the same time, use the
+   * set_all_boundary_indicators() function. You can see the result of not
+   * using the correct function in the results section of step-49.
+   *
+   * @warning You should never set the boundary indicator of an interior face
+   * (a face not at the boundary of the domain), or set set the boundary
+   * indicator of an exterior face to numbers::internal_face_boundary_id (this
+   * value is reserved for another purpose). Algorithms may not work or
+   * produce very confusing results if boundary cells have a boundary
+   * indicator of numbers::internal_face_boundary_id or if interior cells have
+   * boundary indicators other than numbers::internal_face_boundary_id.
+   * Unfortunately, the current object has no means of finding out whether it
+   * really is at the boundary of the domain and so cannot determine whether
+   * the value you are trying to set makes sense under the current
+   * circumstances.
    *
    * @ingroup boundary
    *
@@ -1134,36 +903,29 @@ public:
   void set_boundary_indicator (const types::boundary_id) const;
 
   /**
-   * Do as set_boundary_indicator()
-   * but also set the boundary
-   * indicators of the objects that
-   * bound the current object. For
-   * example, in 3d, if
-   * set_boundary_indicator() is
-   * called on a face, then the
-   * boundary indicator of the 4
-   * edges that bound the face
-   * remain unchanged. In contrast, if you call the current function,
-   * the boundary indicators
-   * of face and edges are all set to the given value.
-   *
-   * This function is useful if you set boundary indicators of faces
-   * in 3d (in 2d, the function does the same as set_boundary_indicator())
-   * and you do so because you want a curved boundary object to
-   * represent the part of the boundary that corresponds to the
-   * current face. In that case, the Triangulation class needs to figure
-   * out where to put new vertices upon mesh refinement, and higher order
-   * Mapping objects also need to figure out where new interpolation points
-   * for a curved boundary approximation should be. In either case, the
-   * two classes first determine where interpolation points on the edges
-   * of a boundary face should be, asking the boundary object, before
-   * asking the boundary object for the interpolation points corresponding
-   * to the interior of the boundary face. For this to work properly, it is
-   * not sufficient to have set the boundary indicator for the face alone,
-   * but you also need to set the boundary indicators of the edges that
-   * bound the face. This function does all of this at once. You can see
-   * the result of not using the correct function in the
-   * results section of step-49.
+   * Do as set_boundary_indicator() but also set the boundary indicators of
+   * the objects that bound the current object. For example, in 3d, if
+   * set_boundary_indicator() is called on a face, then the boundary indicator
+   * of the 4 edges that bound the face remain unchanged. In contrast, if you
+   * call the current function, the boundary indicators of face and edges are
+   * all set to the given value.
+   *
+   * This function is useful if you set boundary indicators of faces in 3d (in
+   * 2d, the function does the same as set_boundary_indicator()) and you do so
+   * because you want a curved boundary object to represent the part of the
+   * boundary that corresponds to the current face. In that case, the
+   * Triangulation class needs to figure out where to put new vertices upon
+   * mesh refinement, and higher order Mapping objects also need to figure out
+   * where new interpolation points for a curved boundary approximation should
+   * be. In either case, the two classes first determine where interpolation
+   * points on the edges of a boundary face should be, asking the boundary
+   * object, before asking the boundary object for the interpolation points
+   * corresponding to the interior of the boundary face. For this to work
+   * properly, it is not sufficient to have set the boundary indicator for the
+   * face alone, but you also need to set the boundary indicators of the edges
+   * that bound the face. This function does all of this at once. You can see
+   * the result of not using the correct function in the results section of
+   * step-49.
    *
    * @ingroup boundary
    *
@@ -1172,33 +934,28 @@ public:
   void set_all_boundary_indicators (const types::boundary_id) const;
 
   /**
-   * Return whether this object is at the
-   * boundary. Obviously, the use of this
-   * function is only possible for
-   * <tt>dim@>structdim</tt>; however, for
-   * <tt>dim==structdim</tt>, an object is a
-   * cell and the CellAccessor class offers
-   * another possibility to determine
-   * whether a cell is at the boundary or
-   * not.
+   * Return whether this object is at the boundary. Obviously, the use of this
+   * function is only possible for <tt>dim@>structdim</tt>; however, for
+   * <tt>dim==structdim</tt>, an object is a cell and the CellAccessor class
+   * offers another possibility to determine whether a cell is at the boundary
+   * or not.
    */
   bool at_boundary () const;
 
   /**
-   * Return a constant reference to the manifold object used for this
-   * object. This function exists for backward compatibility and calls
-   * get_manifold() internally.
+   * Return a constant reference to the manifold object used for this object.
+   * This function exists for backward compatibility and calls get_manifold()
+   * internally.
    */
   const Boundary<dim,spacedim> &get_boundary () const;
 
   /**
    * Return a constant reference to the manifold object used for this object.
    *
-   * As explained in
-   * @ref boundary "Boundary and manifold description for triangulations",
-   * the process involved in finding the appropriate manifold description
-   * involves querying both the manifold or boundary indicators. See there
-   * for more information.
+   * As explained in @ref boundary "Boundary and manifold description for
+   * triangulations", the process involved in finding the appropriate manifold
+   * description involves querying both the manifold or boundary indicators.
+   * See there for more information.
    */
   const Manifold<dim,spacedim> &get_manifold () const;
 
@@ -1207,19 +964,17 @@ public:
    */
 
   /**
-   *  @name Dealing with manifold indicators
+   * @name Dealing with manifold indicators
    */
   /**
    * @{
    */
 
   /**
-   * Return the manifold indicator of this
-   * object.
+   * Return the manifold indicator of this object.
    *
-   * If the return value is the special value
-   * numbers::flat_manifold_id, then this object is associated with a
-   * standard Cartesian Manifold Description.
+   * If the return value is the special value numbers::flat_manifold_id, then
+   * this object is associated with a standard Cartesian Manifold Description.
    *
    * @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
    */
@@ -1229,13 +984,12 @@ public:
    * Set the manifold indicator.  The same applies as for the
    * <tt>manifold_id()</tt> function.
    *
-   * Note that it only sets the manifold object of the current object
-   * itself, not the indicators of the ones that bound it, nor of its
-   * children. For example, in 3d, if this function is called on a
-   * face, then the manifold indicator of the 4 edges that bound the
-   * face remain unchanged. If you want to set the manifold indicators
-   * of face, edges and all children at the same time, use the
-   * set_all_manifold_ids() function.
+   * Note that it only sets the manifold object of the current object itself,
+   * not the indicators of the ones that bound it, nor of its children. For
+   * example, in 3d, if this function is called on a face, then the manifold
+   * indicator of the 4 edges that bound the face remain unchanged. If you
+   * want to set the manifold indicators of face, edges and all children at
+   * the same time, use the set_all_manifold_ids() function.
    *
    *
    * @ingroup manifold
@@ -1245,20 +999,12 @@ public:
   void set_manifold_id (const types::manifold_id) const;
 
   /**
-   * Do as set_manifold_id()
-   * but also set the manifold
-   * indicators of the objects that
-   * bound the current object. For
-   * example, in 3d, if
-   * set_manifold_id() is
-   * called on a face, then the
-   * manifold indicator of the 4
-   * edges that bound the face
-   * remain unchanged. On the other
-   * hand, the manifold indicators
-   * of face and edges are all set
-   * at the same time using the
-   * current function.
+   * Do as set_manifold_id() but also set the manifold indicators of the
+   * objects that bound the current object. For example, in 3d, if
+   * set_manifold_id() is called on a face, then the manifold indicator of the
+   * 4 edges that bound the face remain unchanged. On the other hand, the
+   * manifold indicators of face and edges are all set at the same time using
+   * the current function.
    *
    * @ingroup manifold
    *
@@ -1278,217 +1024,145 @@ public:
    * @{
    */
   /**
-   *  Read the user flag.
-  *  See @ref GlossUserFlags for more information.
+   * Read the user flag. See @ref GlossUserFlags for more information.
    */
   bool user_flag_set () const;
 
   /**
-   *  Set the user flag.
-  *  See @ref GlossUserFlags for more information.
+   * Set the user flag. See @ref GlossUserFlags for more information.
    */
   void set_user_flag () const;
 
   /**
-   *  Clear the user flag.
-  *  See @ref GlossUserFlags for more information.
+   * Clear the user flag. See @ref GlossUserFlags for more information.
    */
   void clear_user_flag () const;
 
   /**
-   *  Set the user flag for this
-   * and all descendants.
-  *  See @ref GlossUserFlags for more information.
+   * Set the user flag for this and all descendants. See @ref GlossUserFlags
+   * for more information.
    */
   void recursively_set_user_flag () const;
 
   /**
-   *  Clear the user flag for this
-   * and all descendants.
-  *  See @ref GlossUserFlags for more information.
+   * Clear the user flag for this and all descendants. See @ref GlossUserFlags
+   * for more information.
    */
   void recursively_clear_user_flag () const;
 
   /**
-   * Reset the user data to zero,
-   * independent if pointer or index.
-  * See @ref GlossUserData for more information.
+   * Reset the user data to zero, independent if pointer or index. See @ref
+   * GlossUserData for more information.
    */
   void clear_user_data () const;
 
   /**
-   * Set the user pointer
-   * to @p p.
+   * Set the user pointer to @p p.
+   *
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between.
    *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-  *
-  * See @ref GlossUserData for more information.
+   * See @ref GlossUserData for more information.
    */
   void set_user_pointer (void *p) const;
 
   /**
-   * Reset the user pointer
-   * to a @p NULL pointer.
-  * See @ref GlossUserData for more information.
+   * Reset the user pointer to a @p NULL pointer. See @ref GlossUserData for
+   * more information.
    */
   void clear_user_pointer () const;
 
   /**
-   * Access the value of the user
-   * pointer. It is in the
-   * responsibility of the user to
-   * make sure that the pointer
-   * points to something
-   * useful. You should use the new
-   * style cast operator to
-   * maintain a minimum of
-   * typesafety, e.g.
-   *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-   * <tt>A *a=static_cast<A*>(cell->user_pointer());</tt>.
-  *
-  * See @ref GlossUserData for more information.
+   * Access the value of the user pointer. It is in the responsibility of the
+   * user to make sure that the pointer points to something useful. You should
+   * use the new style cast operator to maintain a minimum of typesafety, e.g.
+   *
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between. <tt>A
+   * *a=static_cast<A*>(cell->user_pointer());</tt>.
+   *
+   * See @ref GlossUserData for more information.
    */
   void *user_pointer () const;
 
   /**
-   * Set the user pointer of this
-   * object and all its children to
-   * the given value. This is
-   * useful for example if all
-   * cells of a certain subdomain,
-   * or all faces of a certain part
-   * of the boundary should have
-   * user pointers pointing to
-   * objects describing this part
-   * of the domain or boundary.
-   *
-   * Note that the user pointer is
-   * not inherited under mesh
-   * refinement, so after mesh
-   * refinement there might be
-   * cells or faces that don't have
-   * user pointers pointing to the
-   * describing object. In this
-   * case, simply loop over all the
-   * elements of the coarsest level
-   * that has this information, and
-   * use this function to
-   * recursively set the user
-   * pointer of all finer levels of
-   * the triangulation.
+   * Set the user pointer of this object and all its children to the given
+   * value. This is useful for example if all cells of a certain subdomain, or
+   * all faces of a certain part of the boundary should have user pointers
+   * pointing to objects describing this part of the domain or boundary.
    *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-  *
-  * See @ref GlossUserData for more information.
+   * Note that the user pointer is not inherited under mesh refinement, so
+   * after mesh refinement there might be cells or faces that don't have user
+   * pointers pointing to the describing object. In this case, simply loop
+   * over all the elements of the coarsest level that has this information,
+   * and use this function to recursively set the user pointer of all finer
+   * levels of the triangulation.
+   *
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between.
+   *
+   * See @ref GlossUserData for more information.
    */
   void recursively_set_user_pointer (void *p) const;
 
   /**
-   * Clear the user pointer of this
-   * object and all of its
-   * descendants. The same holds as
-   * said for the
-   * recursively_set_user_pointer()
-   * function.
-  * See @ref GlossUserData for more information.
+   * Clear the user pointer of this object and all of its descendants. The
+   * same holds as said for the recursively_set_user_pointer() function. See
+   * @ref GlossUserData for more information.
    */
   void recursively_clear_user_pointer () const;
 
   /**
-   * Set the user index
-   * to @p p.
+   * Set the user index to @p p.
    *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-  * See @ref GlossUserData for more information.
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between. See @ref GlossUserData for
+   * more information.
    */
   void set_user_index (const unsigned int p) const;
 
   /**
-   * Reset the user index to 0.
-  * See @ref GlossUserData for more information.
+   * Reset the user index to 0. See @ref GlossUserData for more information.
    */
   void clear_user_index () const;
 
   /**
-   * Access the value of the user
-   * index.
+   * Access the value of the user index.
+   *
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between.
    *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-  *
-  * See @ref GlossUserData for more information.
+   * See @ref GlossUserData for more information.
    */
   unsigned int user_index () const;
 
   /**
-   * Set the user index of this
-   * object and all its children.
-   *
-   * Note that the user index is
-   * not inherited under mesh
-   * refinement, so after mesh
-   * refinement there might be
-   * cells or faces that don't have
-   * the expected user indices. In
-   * this case, simply loop over
-   * all the elements of the
-   * coarsest level that has this
-   * information, and use this
-   * function to recursively set
-   * the user index of all finer
-   * levels of the triangulation.
+   * Set the user index of this object and all its children.
+   *
+   * Note that the user index is not inherited under mesh refinement, so after
+   * mesh refinement there might be cells or faces that don't have the
+   * expected user indices. In this case, simply loop over all the elements of
+   * the coarsest level that has this information, and use this function to
+   * recursively set the user index of all finer levels of the triangulation.
    *
-   * @note User pointers and user
-   * indices are mutually
-   * exclusive. Therefore, you can
-   * only use one of them, unless
-   * you call
-   * Triangulation::clear_user_data()
-   * in between.
-  *
-  * See @ref GlossUserData for more information.
+   * @note User pointers and user indices are mutually exclusive. Therefore,
+   * you can only use one of them, unless you call
+   * Triangulation::clear_user_data() in between.
+   *
+   * See @ref GlossUserData for more information.
    */
   void recursively_set_user_index (const unsigned int p) const;
 
   /**
-   * Clear the user index of this
-   * object and all of its
-   * descendants. The same holds as
-   * said for the
-   * recursively_set_user_index()
-   * function.
-  *
-  * See @ref GlossUserData for more information.
+   * Clear the user index of this object and all of its descendants. The same
+   * holds as said for the recursively_set_user_index() function.
+   *
+   * See @ref GlossUserData for more information.
    */
   void recursively_clear_user_index () const;
   /**
@@ -1505,72 +1179,59 @@ public:
   /**
    * Diameter of the object.
    *
-   * The diameter of an object is computed
-   * to be the largest diagonal. This is
-   * not necessarily the true diameter for
-   * objects that may use higher order
-   * mappings, but completely sufficient
-   * for most computations.
+   * The diameter of an object is computed to be the largest diagonal. This is
+   * not necessarily the true diameter for objects that may use higher order
+   * mappings, but completely sufficient for most computations.
    */
   double diameter () const;
 
   /**
-   * Length of an object in the direction
-   * of the given axis, specified in the
-   * local coordinate system. See the
-   * documentation of GeometryInfo for the
-   * meaning and enumeration of the local
-   * axes.
+   * Length of an object in the direction of the given axis, specified in the
+   * local coordinate system. See the documentation of GeometryInfo for the
+   * meaning and enumeration of the local axes.
    *
-   * Note that the "length" of an object
-   * can be interpreted in a variety of
-   * ways. Here, we choose it as the
-   * maximal length of any of the edges of
-   * the object that are parallel to the
-   * chosen axis on the reference cell.
+   * Note that the "length" of an object can be interpreted in a variety of
+   * ways. Here, we choose it as the maximal length of any of the edges of the
+   * object that are parallel to the chosen axis on the reference cell.
    */
   double extent_in_direction (const unsigned int axis) const;
 
   /**
-   * Returns the minimal distance between
-   * any two vertices.
+   * Returns the minimal distance between any two vertices.
    */
   double minimum_vertex_distance () const;
 
   /**
-   * Returns a point belonging to the Manifold<dim,spacedim> where
-   * this object lives, given its parametric coordinates on the
-   * reference #structdim cell. This function queries the underlying
-   * manifold object, and can be used to obtain the exact geometrical
-   * location of arbitrary points on this object.
+   * Returns a point belonging to the Manifold<dim,spacedim> where this object
+   * lives, given its parametric coordinates on the reference #structdim cell.
+   * This function queries the underlying manifold object, and can be used to
+   * obtain the exact geometrical location of arbitrary points on this object.
    *
-   * Notice that the argument @p coordinates are the coordinates on
-   * the <emph>reference cell</emph>, given in reference
-   * coordinates. In other words, the argument provides a weighting
-   * between the different vertices. For example, for lines, calling
-   * this function with argument Point<1>(.5), is equivalent to asking
-   * the line for its center.
+   * Notice that the argument @p coordinates are the coordinates on the
+   * <emph>reference cell</emph>, given in reference coordinates. In other
+   * words, the argument provides a weighting between the different vertices.
+   * For example, for lines, calling this function with argument Point<1>(.5),
+   * is equivalent to asking the line for its center.
    */
   Point<spacedim> intermediate_point(const Point<structdim> &coordinates) const;
 
   /**
-   * Center of the object. The center of an object is defined to be
-   * the average of the locations of the vertices. If required, the
-   * user may ask this function to return the average of the point
-   * according to the underlyinging Manifold object, by setting to
-   * true the optional parameter @p respect_manifold.
-   *
-   * When the geometry of a TriaAccessor is not flat, or when part of
-   * the bounding objects of this TriaAccessor are not flat, the
-   * result given by the TriaAccessor::center() function may not be
-   * accurate enough, even when parameter @p respect_manifold is set
-   * to true. If you find this to be case, than you can further refine
-   * the computation of the center by setting to true the second
-   * additional parameter @p use_laplace_transformation, which will
-   * force this function to compute the location of the center by
-   * solving a linear elasticity problem with Dirichlet boundary
-   * conditions set to the location of the bounding vertices and the
-   * centers of the bounding lines and quads.
+   * Center of the object. The center of an object is defined to be the
+   * average of the locations of the vertices. If required, the user may ask
+   * this function to return the average of the point according to the
+   * underlyinging Manifold object, by setting to true the optional parameter
+   * @p respect_manifold.
+   *
+   * When the geometry of a TriaAccessor is not flat, or when part of the
+   * bounding objects of this TriaAccessor are not flat, the result given by
+   * the TriaAccessor::center() function may not be accurate enough, even when
+   * parameter @p respect_manifold is set to true. If you find this to be
+   * case, than you can further refine the computation of the center by
+   * setting to true the second additional parameter @p
+   * use_laplace_transformation, which will force this function to compute the
+   * location of the center by solving a linear elasticity problem with
+   * Dirichlet boundary conditions set to the location of the bounding
+   * vertices and the centers of the bounding lines and quads.
    */
   Point<spacedim> center (const bool respect_manifold=false,
                           const bool use_laplace_transformation=false) const;
@@ -1581,60 +1242,45 @@ public:
   Point<spacedim> barycenter () const;
 
   /**
-   * Compute the dim-dimensional measure of the object. For a
-   * dim-dimensional cell in dim-dimensional space, this equals its
-   * volume. On the other hand, for a 2d cell in 3d space, or if the
-   * current object pointed to is a 2d face of a 3d cell in 3d space,
-   * then the function computes the area the object occupies. For a
-   * one-dimensional object, return its length.
-   *
-   * The function only computes the measure of cells, faces or edges
-   * assumed to be represented by (bi-/tri-)linear mappings. In other
-   * words, it only takes into account the locations of the vertices
-   * that bound the current object but not how the interior of the
-   * object may actually be mapped. In most simple cases, this is
-   * exactly what you want. However, for objects that are not
-   * "straight", e.g. 2d cells embedded in 3d space as part of a
-   * triangulation of a curved domain, two-dimensional faces of 3d
-   * cells that are not just parallelograms, or for faces that are at
-   * the boundary of a domain that is not just bounded by straight
-   * line segments or planes, this function only computes the
-   * dim-dimensional measure of a (bi-/tri-)linear interpolation of
-   * the "real" object as defined by the manifold or boundary object
-   * describing the real geometry of the object in question. If you
-   * want to consider the "real" geometry, you will need to compute
-   * the measure by integrating a function equal to one over the
-   * object, which after applying quadrature equals the summing the
-   * JxW values returned by the FEValues or FEFaceValues object you
-   * will want to use for the integral.
+   * Compute the dim-dimensional measure of the object. For a dim-dimensional
+   * cell in dim-dimensional space, this equals its volume. On the other hand,
+   * for a 2d cell in 3d space, or if the current object pointed to is a 2d
+   * face of a 3d cell in 3d space, then the function computes the area the
+   * object occupies. For a one-dimensional object, return its length.
+   *
+   * The function only computes the measure of cells, faces or edges assumed
+   * to be represented by (bi-/tri-)linear mappings. In other words, it only
+   * takes into account the locations of the vertices that bound the current
+   * object but not how the interior of the object may actually be mapped. In
+   * most simple cases, this is exactly what you want. However, for objects
+   * that are not "straight", e.g. 2d cells embedded in 3d space as part of a
+   * triangulation of a curved domain, two-dimensional faces of 3d cells that
+   * are not just parallelograms, or for faces that are at the boundary of a
+   * domain that is not just bounded by straight line segments or planes, this
+   * function only computes the dim-dimensional measure of a (bi-/tri-)linear
+   * interpolation of the "real" object as defined by the manifold or boundary
+   * object describing the real geometry of the object in question. If you
+   * want to consider the "real" geometry, you will need to compute the
+   * measure by integrating a function equal to one over the object, which
+   * after applying quadrature equals the summing the JxW values returned by
+   * the FEValues or FEFaceValues object you will want to use for the
+   * integral.
    */
   double measure () const;
 
   /**
-   * Return true if the current object is a
-   * translation of the given argument.
-   *
-   * @note For the purpose of a
-   * triangulation, cells, faces, etc are
-   * only characterized by their
-   * vertices. The current function
-   * therefore only compares the locations
-   * of vertices. For many practical
-   * applications, however, it is not only
-   * the vertices that determine whether
-   * one cell is a translation of another,
-   * but also how the cell is mapped from
-   * the reference cell to its location in
-   * real space. For example, if we are
-   * using higher order mappings, then not
-   * only do the vertices have to be
-   * translations of each other, but also
-   * the points along edges. In these
-   * questions, therefore, it would be
-   * appropriate to ask the mapping, not
-   * the current function, whether two
-   * objects are translations of each
-   * other.
+   * Return true if the current object is a translation of the given argument.
+   *
+   * @note For the purpose of a triangulation, cells, faces, etc are only
+   * characterized by their vertices. The current function therefore only
+   * compares the locations of vertices. For many practical applications,
+   * however, it is not only the vertices that determine whether one cell is a
+   * translation of another, but also how the cell is mapped from the
+   * reference cell to its location in real space. For example, if we are
+   * using higher order mappings, then not only do the vertices have to be
+   * translations of each other, but also the points along edges. In these
+   * questions, therefore, it would be appropriate to ask the mapping, not the
+   * current function, whether two objects are translations of each other.
    */
   bool
   is_translation_of (const TriaIterator<TriaAccessor<structdim,dim,spacedim> > &o) const;
@@ -1646,158 +1292,105 @@ public:
 
 private:
   /**
-   *  Copy the data of the given
-   *  object into the internal data
-   *  structures of a
-   *  triangulation.
+   * Copy the data of the given object into the internal data structures of a
+   * triangulation.
    */
   void set (const dealii::internal::Triangulation::TriaObject<structdim> &o) const;
 
   /**
-   * Set the flag indicating, what
-   * <code>line_orientation()</code> will
+   * Set the flag indicating, what <code>line_orientation()</code> will
    * return.
    *
-   * It is only possible to set the
-   * line_orientation of faces in 3d
-   * (i.e. <code>structdim==2 &&
-   * dim==3</code>).
+   * It is only possible to set the line_orientation of faces in 3d (i.e.
+   * <code>structdim==2 && dim==3</code>).
    */
   void set_line_orientation (const unsigned int line,
                              const bool         orientation) const;
 
   /**
-   * Set whether the quad with
-   * index @p face has its normal
-   * pointing in the standard
-   * direction (@p true) or
-   * whether it is the opposite
-   * (@p false). Which is the
-   * standard direction is
-   * documented with the
-   * GeometryInfo class.
+   * Set whether the quad with index @p face has its normal pointing in the
+   * standard direction (@p true) or whether it is the opposite (@p false).
+   * Which is the standard direction is documented with the GeometryInfo
+   * class.
    *
-   * This function is only for
-   * internal use in the
-   * library. Setting this flag to
-   * any other value than the one
-   * that the triangulation has
-   * already set is bound to bring
-   * you desaster.
+   * This function is only for internal use in the library. Setting this flag
+   * to any other value than the one that the triangulation has already set is
+   * bound to bring you desaster.
    */
   void set_face_orientation (const unsigned int face,
                              const bool         orientation) const;
 
   /**
-   * Set the flag indicating, what
-   * <code>face_flip()</code> will
-   * return.
+   * Set the flag indicating, what <code>face_flip()</code> will return.
    *
-   * It is only possible to set the
-   * face_orientation of cells in 3d
-   * (i.e. <code>structdim==3 &&
-   * dim==3</code>).
+   * It is only possible to set the face_orientation of cells in 3d (i.e.
+   * <code>structdim==3 && dim==3</code>).
    */
   void set_face_flip (const unsigned int face,
                       const bool         flip) const;
 
   /**
-   * Set the flag indicating, what
-   * <code>face_rotation()</code> will
-   * return.
+   * Set the flag indicating, what <code>face_rotation()</code> will return.
    *
-   * It is only possible to set the
-   * face_orientation of cells in 3d
-   * (i.e. <code>structdim==3 &&
-   * dim==3</code>).
+   * It is only possible to set the face_orientation of cells in 3d (i.e.
+   * <code>structdim==3 && dim==3</code>).
    */
   void set_face_rotation (const unsigned int face,
                           const bool         rotation) const;
 
   /**
-   *  Set the @p used flag. Only
-   *  for internal use in the
-   *  library.
+   * Set the @p used flag. Only for internal use in the library.
    */
   void set_used_flag () const;
 
   /**
-   *  Clear the @p used flag. Only
-   *  for internal use in the
-   *  library.
+   * Clear the @p used flag. Only for internal use in the library.
    */
   void clear_used_flag () const;
 
   /**
-   * Set the @p RefinementCase<dim> this
-   * TriaObject is refined with.
-   * Not defined for
-   * <tt>structdim=1</tt> as lines
-   * are always refined resulting
-   * in 2 children lines (isotropic
-   * refinement).
+   * Set the @p RefinementCase<dim> this TriaObject is refined with. Not
+   * defined for <tt>structdim=1</tt> as lines are always refined resulting in
+   * 2 children lines (isotropic refinement).
    *
-   * You should know quite exactly
-   * what you are doing if you
-   * touch this function. It is
-   * exclusively for internal use
-   * in the library.
+   * You should know quite exactly what you are doing if you touch this
+   * function. It is exclusively for internal use in the library.
    */
   void set_refinement_case (const RefinementCase<structdim> &ref_case) const;
 
   /**
-   * Clear the RefinementCase<dim> of
-   * this TriaObject, i.e. reset it
-   * to RefinementCase<dim>::no_refinement.
+   * Clear the RefinementCase<dim> of this TriaObject, i.e. reset it to
+   * RefinementCase<dim>::no_refinement.
    *
-   * You should know quite exactly
-   * what you are doing if you
-   * touch this function. It is
-   * exclusively for internal use
-   * in the library.
+   * You should know quite exactly what you are doing if you touch this
+   * function. It is exclusively for internal use in the library.
    */
   void clear_refinement_case () const;
 
   /**
-   *  Set the index of the ith
-   *  child. Since the children
-   *  come at least in pairs, we
-   *  need to store the index of
-   *  only every second child,
-   *  i.e. of the even numbered
-   *  children. Make sure, that the
-   *  index of child i=0 is set
-   *  first. Calling this function
-   *  for odd numbered children is
-   *  not allowed.
+   * Set the index of the ith child. Since the children come at least in
+   * pairs, we need to store the index of only every second child, i.e. of the
+   * even numbered children. Make sure, that the index of child i=0 is set
+   * first. Calling this function for odd numbered children is not allowed.
    */
   void set_children (const unsigned int i, const int index) const;
 
   /**
-   *  Clear the child field,
-   *  i.e. set it to a value which
-   *  indicates that this cell has
-   *  no children.
+   * Clear the child field, i.e. set it to a value which indicates that this
+   * cell has no children.
    */
   void clear_children () const;
 
 private:
   /**
-   *  Copy operator. This is normally used
-   *  in a context like <tt>iterator a,b;
-   *  *a=*b;</tt>. Presumably, the intent
-   *  here is to copy the object pointed to
-   *  by @p b to the object pointed to by
-   *  @p a. However, the result of
-   *  dereferencing an iterator is not an
-   *  object but an accessor; consequently,
-   *  this operation is not useful for
-   *  iterators on triangulations. We
-   *  declare this function here private,
-   *  thus it may not be used from outside.
-   *  Furthermore it is not implemented and
-   *  will give a linker error if used
-   *  anyway.
+   * Copy operator. This is normally used in a context like <tt>iterator a,b;
+   * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+   * by @p b to the object pointed to by @p a. However, the result of
+   * dereferencing an iterator is not an object but an accessor; consequently,
+   * this operation is not useful for iterators on triangulations. We declare
+   * this function here private, thus it may not be used from outside.
+   * Furthermore it is not implemented and will give a linker error if used
+   * anyway.
    */
   void operator = (const TriaAccessor &);
 
@@ -1813,8 +1406,8 @@ private:
 
 
 /**
- * Closure class to stop induction of classes. Should never be called
- * and thus produces an error when created.
+ * Closure class to stop induction of classes. Should never be called and thus
+ * produces an error when created.
  *
  * @ingroup grid
  */
@@ -1823,9 +1416,7 @@ class TriaAccessor<0, dim, spacedim>
 {
 private:
   /**
-   * Constructor. Made private to
-   * make sure that this class
-   * can't be used.
+   * Constructor. Made private to make sure that this class can't be used.
    */
   TriaAccessor ();
 };
@@ -1833,11 +1424,10 @@ private:
 
 
 /**
- * A class that represents an access to a face in 1d -- i.e. to a
- * point. This is not a full fledged access from which you can build
- * an iterator: for example, you can't iterate from one such point to
- * the next. Point also don't have children, and they don't have
- * neighbors.
+ * A class that represents an access to a face in 1d -- i.e. to a point. This
+ * is not a full fledged access from which you can build an iterator: for
+ * example, you can't iterate from one such point to the next. Point also
+ * don't have children, and they don't have neighbors.
  *
  * @author Wolfgang Bangerth, 2010
  */
@@ -1846,38 +1436,23 @@ class TriaAccessor<0, 1, spacedim>
 {
 public:
   /**
-   *  Dimension of the space the
-   *  object represented by this
-   *  accessor lives in. For
-   *  example, if this accessor
-   *  represents a quad that is
-   *  part of a two-dimensional
-   *  surface in four-dimensional
-   *  space, then this value is
-   *  four.
+   * Dimension of the space the object represented by this accessor lives in.
+   * For example, if this accessor represents a quad that is part of a two-
+   * dimensional surface in four-dimensional space, then this value is four.
    */
   static const unsigned int space_dimension = spacedim;
 
   /**
-   * Dimensionality of the object
-   * that the thing represented by
-   * this accessopr is part of. For
-   * example, if this accessor
-   * represents a line that is part
-   * of a hexahedron, then this
-   * value will be three.
+   * Dimensionality of the object that the thing represented by this accessopr
+   * is part of. For example, if this accessor represents a line that is part
+   * of a hexahedron, then this value will be three.
    */
   static const unsigned int dimension = 1;
 
   /**
-   * Dimensionality of the current
-   * object represented by this
-   * accessor. For example, if it
-   * is line (irrespective of
-   * whether it is part of a quad
-   * or hex, and what dimension we
-   * are in), then this value
-   * equals 1.
+   * Dimensionality of the current object represented by this accessor. For
+   * example, if it is line (irrespective of whether it is part of a quad or
+   * hex, and what dimension we are in), then this value equals 1.
    */
   static const unsigned int structure_dimension = 0;
 
@@ -1887,10 +1462,8 @@ public:
   typedef void AccessorData;
 
   /**
-   * Whether the vertex represented
-   * here is at the left end of the
-   * domain, the right end, or in
-   * the interior.
+   * Whether the vertex represented here is at the left end of the domain, the
+   * right end, or in the interior.
    */
   enum VertexKind
   {
@@ -1902,35 +1475,22 @@ public:
   /**
    * Constructor.
    *
-   * Since there is no mapping from
-   * vertices to cells, an accessor
-   * object for a point has no way
-   * to figure out whether it is at
-   * the boundary of the domain or
-   * not. Consequently, the second
-   * argument must be passed by the
-   * object that generates this
-   * accessor -- e.g. a 1d cell
-   * that can figure out whether
-   * its left or right vertex are
-   * at the boundary.
-   *
-   * The third argument is the
-   * global index of the vertex we
-   * point to.
+   * Since there is no mapping from vertices to cells, an accessor object for
+   * a point has no way to figure out whether it is at the boundary of the
+   * domain or not. Consequently, the second argument must be passed by the
+   * object that generates this accessor -- e.g. a 1d cell that can figure out
+   * whether its left or right vertex are at the boundary.
+   *
+   * The third argument is the global index of the vertex we point to.
    */
   TriaAccessor (const Triangulation<1,spacedim> *tria,
                 const VertexKind      vertex_kind,
                 const unsigned int    vertex_index);
 
   /**
-   * Constructor. This constructor
-   * exists in order to maintain
-   * interface compatibility with
-   * the other accessor
-   * classes. However, it doesn't
-   * do anything useful here and so
-   * may not actually be called.
+   * Constructor. This constructor exists in order to maintain interface
+   * compatibility with the other accessor classes. However, it doesn't do
+   * anything useful here and so may not actually be called.
    */
   TriaAccessor (const Triangulation<1,spacedim> *tria = 0,
                 const int = 0,
@@ -1938,56 +1498,42 @@ public:
                 const AccessorData * = 0);
 
   /**
-   * Constructor. Should never be
-   * called and thus produces an
-   * error.
+   * Constructor. Should never be called and thus produces an error.
    */
   template <int structdim2, int dim2, int spacedim2>
   TriaAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Constructor. Should never be
-   * called and thus produces an
-   * error.
+   * Constructor. Should never be called and thus produces an error.
    */
   template <int structdim2, int dim2, int spacedim2>
   TriaAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   *  Copy operator. Since this is
-   *  only called from iterators,
-   *  do not return anything, since
-   *  the iterator will return
-   *  itself.
+   * Copy operator. Since this is only called from iterators, do not return
+   * anything, since the iterator will return itself.
    *
-   *  This method is protected,
-   *  since it is only to be called
-   *  from the iterator class.
+   * This method is protected, since it is only to be called from the iterator
+   * class.
    */
   void copy_from (const TriaAccessor &);
 
   /**
-   *  Return the state of the
-   *  iterator. Since an iterator
-   *  to points can not be
-   *  incremented or decremented,
-   *  its state remains constant,
-   *  and in particular equal to
-   *  IteratorState::valid.
+   * Return the state of the iterator. Since an iterator to points can not be
+   * incremented or decremented, its state remains constant, and in particular
+   * equal to IteratorState::valid.
    */
   static IteratorState::IteratorStates state ();
 
   /**
-   * Level of this object. Vertices
-   * have no level, so this
-   * function always returns zero.
+   * Level of this object. Vertices have no level, so this function always
+   * returns zero.
    */
   static int level ();
 
   /**
-   * Index of this object. Returns
-   * the global index of the vertex
-   * this object points to.
+   * Index of this object. Returns the global index of the vertex this object
+   * points to.
    */
   int index () const;
 
@@ -1998,26 +1544,18 @@ public:
    * @{
    */
   /**
-   *  This operator advances the
-   *  iterator to the next
-   *  element. For points, this
-   *  operation is not defined, so
-   *  you can't iterate over point
-   *  iterators.
+   * This operator advances the iterator to the next element. For points, this
+   * operation is not defined, so you can't iterate over point iterators.
    */
   void operator ++ () const;
 
   /**
-   *  This operator moves the
-   *  iterator to the previous
-   *  element. For points, this
-   *  operation is not defined, so
-   *  you can't iterate over point
-   *  iterators.
+   * This operator moves the iterator to the previous element. For points,
+   * this operation is not defined, so you can't iterate over point iterators.
    */
   void operator -- () const;
   /**
-   *  Compare for equality.
+   * Compare for equality.
    */
   bool operator == (const TriaAccessor &) const;
 
@@ -2031,90 +1569,68 @@ public:
    */
 
   /**
-   *  @name Accessing sub-objects
+   * @name Accessing sub-objects
    */
   /**
    * @{
    */
 
   /**
-   *  Return the global index of
-   *  i-th vertex of the current
-   *  object. If i is zero, this
-   *  returns the index of the
-   *  current point to which this
-   *  object refers. Otherwise, it
-   *  throws an exception.
+   * Return the global index of i-th vertex of the current object. If i is
+   * zero, this returns the index of the current point to which this object
+   * refers. Otherwise, it throws an exception.
    *
-   *  Note that the returned value is only
-   *  the index of the geometrical
-   *  vertex. It has nothing to do with
-   *  possible degrees of freedom
-   *  associated with it. For this, see the
-   *  @p DoFAccessor::vertex_dof_index
-   *  functions.
+   * Note that the returned value is only the index of the geometrical vertex.
+   * It has nothing to do with possible degrees of freedom associated with it.
+   * For this, see the @p DoFAccessor::vertex_dof_index functions.
    *
-   *  @note Despite the name, the index returned here is only
-   *  global in the sense that it is specific to a particular
-   *  Triangulation object or, in the case the triangulation is
-   *  actually of type parallel::distributed::Triangulation,
-   *  specific to that part of the distributed triangulation stored
-   *  on the current processor.
+   * @note Despite the name, the index returned here is only global in the
+   * sense that it is specific to a particular Triangulation object or, in the
+   * case the triangulation is actually of type
+   * parallel::distributed::Triangulation, specific to that part of the
+   * distributed triangulation stored on the current processor.
    */
   unsigned int vertex_index (const unsigned int i = 0) const;
 
   /**
-   *  Return a reference to the
-   *  @p ith vertex. If i is zero, this
-   *  returns a reference to the
-   *  current point to which this
-   *  object refers. Otherwise, it
-   *  throws an exception.
+   * Return a reference to the @p ith vertex. If i is zero, this returns a
+   * reference to the current point to which this object refers. Otherwise, it
+   * throws an exception.
    */
   Point<spacedim> &vertex (const unsigned int i = 0) const;
 
   /**
-   * Return the center of this object,
-   * which of course co-incides with the
-   * location of the vertex this object
-   * refers to.
+   * Return the center of this object, which of course co-incides with the
+   * location of the vertex this object refers to.
    */
   Point<spacedim> center () const;
 
   /**
-   * Pointer to the @p ith line
-   * bounding this object. Will
-   * point to an invalid object.
+   * Pointer to the @p ith line bounding this object. Will point to an invalid
+   * object.
    */
   typename dealii::internal::Triangulation::Iterators<1,spacedim>::line_iterator
   static line (const unsigned int);
 
   /**
-   * Line index of the @p ith
-   * line bounding this object.
+   * Line index of the @p ith line bounding this object.
    *
-   * Implemented only for
-   * <tt>structdim>1</tt>,
-   * otherwise an exception
+   * Implemented only for <tt>structdim>1</tt>, otherwise an exception
    * generated.
    */
   static unsigned int line_index (const unsigned int i);
 
   /**
-   * Pointer to the @p ith quad
-   * bounding this object.
+   * Pointer to the @p ith quad bounding this object.
    */
   static
   typename dealii::internal::Triangulation::Iterators<1,spacedim>::quad_iterator
   quad (const unsigned int i);
 
   /**
-   * Quad index of the @p ith
-   * quad bounding this object.
+   * Quad index of the @p ith quad bounding this object.
    *
-   * Implemented only for
-   * <tt>structdim>2</tt>,
-   * otherwise an exception
+   * Implemented only for <tt>structdim>2</tt>, otherwise an exception
    * generated.
    */
   static unsigned int quad_index (const unsigned int i);
@@ -2125,10 +1641,8 @@ public:
 
 
   /**
-   * Return whether this point is
-   * at the boundary of the
-   * one-dimensional triangulation
-   * we deal with here.
+   * Return whether this point is at the boundary of the one-dimensional
+   * triangulation we deal with here.
    */
   bool at_boundary () const;
 
@@ -2148,8 +1662,7 @@ public:
   types::boundary_id boundary_indicator () const;
 
   /**
-   * Return the manifold indicator of this
-   * object.
+   * Return the manifold indicator of this object.
    *
    * @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
    */
@@ -2157,7 +1670,7 @@ public:
 
 
   /**
-   *  @name Orientation of sub-objects
+   * @name Orientation of sub-objects
    */
   /**
    * @{
@@ -2188,36 +1701,31 @@ public:
    */
 
   /**
-   *  @name Accessing children
+   * @name Accessing children
    */
   /**
    * @{
    */
 
   /**
-   *  Test whether the object has
-   *  children. Always false.
+   * Test whether the object has children. Always false.
    */
   static bool has_children ();
 
   /**
-   * Return the number of immediate
-   * children of this object.This
-   * is always zero in dimension 0.
+   * Return the number of immediate children of this object.This is always
+   * zero in dimension 0.
    */
   static unsigned int n_children();
 
   /**
-   * Compute and return the number
-   * of active descendants of this
-   * objects. Always zero.
+   * Compute and return the number of active descendants of this objects.
+   * Always zero.
    */
   static unsigned int number_of_children ();
 
   /**
-   * Return the number of times
-   * that this object is
-   * refined. Always 0.
+   * Return the number of times that this object is refined. Always 0.
    */
   static unsigned int max_refinement_depth ();
 
@@ -2257,37 +1765,27 @@ public:
    */
 
   /**
-   *  @name Dealing with boundary indicators
+   * @name Dealing with boundary indicators
    */
   /**
    * @{
    */
 
   /**
-   * Set the boundary indicator.
-   * The same applies as for the
-   * <tt>boundary_indicator()</tt>
-   * function.
-   *
-   * @warning You should never set the
-   * boundary indicator of an interior face
-   * (a face not at the boundary of the
-   * domain), or set set the boundary
-   * indicator of an exterior face to
-   *  numbers::internal_face_boundary_id
-   * (this value is reserved for another
-   * purpose). Algorithms may not work or
-   * produce very confusing results if
-   * boundary cells have a boundary
-   * indicator of numbers::internal_face_boundary_id
-   * or if interior cells have boundary
-   * indicators other than numbers::internal_face_boundary_id.
-   * Unfortunately, the current object
-   * has no means of finding out whether it
-   * really is at the boundary of the
-   * domain and so cannot determine whether
-   * the value you are trying to set makes
-   * sense under the current circumstances.
+   * Set the boundary indicator. The same applies as for the
+   * <tt>boundary_indicator()</tt> function.
+   *
+   * @warning You should never set the boundary indicator of an interior face
+   * (a face not at the boundary of the domain), or set set the boundary
+   * indicator of an exterior face to numbers::internal_face_boundary_id (this
+   * value is reserved for another purpose). Algorithms may not work or
+   * produce very confusing results if boundary cells have a boundary
+   * indicator of numbers::internal_face_boundary_id or if interior cells have
+   * boundary indicators other than numbers::internal_face_boundary_id.
+   * Unfortunately, the current object has no means of finding out whether it
+   * really is at the boundary of the domain and so cannot determine whether
+   * the value you are trying to set makes sense under the current
+   * circumstances.
    *
    * @ingroup boundary
    *
@@ -2306,9 +1804,9 @@ public:
   set_manifold_id (const types::manifold_id);
 
   /**
-   * Set the boundary indicator of this object and all of its
-   * lower-dimensional sub-objects.  Since this object only represents a
-   * single vertex, there are no lower-dimensional obejct and this function is
+   * Set the boundary indicator of this object and all of its lower-
+   * dimensional sub-objects.  Since this object only represents a single
+   * vertex, there are no lower-dimensional obejct and this function is
    * equivalent to calling set_boundary_indicator with the same argument.
    *
    * @ingroup boundary
@@ -2319,9 +1817,9 @@ public:
   set_all_boundary_indicators (const types::boundary_id);
 
   /**
-   * Set the manifold indicator of this object and all of its
-   * lower-dimensional sub-objects.  Since this object only represents a
-   * single vertex, there are no lower-dimensional obejct and this function is
+   * Set the manifold indicator of this object and all of its lower-
+   * dimensional sub-objects.  Since this object only represents a single
+   * vertex, there are no lower-dimensional obejct and this function is
    * equivalent to calling set_manifold_indicator with the same argument.
    *
    * @ingroup manifold
@@ -2336,31 +1834,24 @@ public:
    */
 
   /**
-   * Return whether the vertex
-   * pointed to here is used.
+   * Return whether the vertex pointed to here is used.
    */
   bool used () const;
 
 protected:
   /**
-   * Pointer to the triangulation
-   * we operate on.
+   * Pointer to the triangulation we operate on.
    */
   const Triangulation<1,spacedim> *tria;
 
   /**
-   * Whether this is a left end,
-   * right end, or interior
-   * vertex. This information is
-   * provided by the cell at the
-   * time of creation.
+   * Whether this is a left end, right end, or interior vertex. This
+   * information is provided by the cell at the time of creation.
    */
   VertexKind      vertex_kind;
 
   /**
-   * The global vertex index of the
-   * vertex this object corresponds
-   * to.
+   * The global vertex index of the vertex this object corresponds to.
    */
   unsigned int    global_vertex_index;
 };
@@ -2369,16 +1860,16 @@ protected:
 
 
 /**
- * This class allows access to a cell: a line in one dimension, a quad
- * in two dimension, etc.
+ * This class allows access to a cell: a line in one dimension, a quad in two
+ * dimension, etc.
  *
  * The following refers to any dimension:
  *
- * This class allows access to a <tt>cell</tt>, which is a line in 1D
- * and a quad in 2D. Cells have more functionality than lines or quads
- * by themselves, for example they can be flagged for refinement, they
- * have neighbors, they have the possibility to check whether they are
- * at the boundary etc. This class offers access to all this data.
+ * This class allows access to a <tt>cell</tt>, which is a line in 1D and a
+ * quad in 2D. Cells have more functionality than lines or quads by
+ * themselves, for example they can be flagged for refinement, they have
+ * neighbors, they have the possibility to check whether they are at the
+ * boundary etc. This class offers access to all this data.
  *
  * @ingroup grid
  * @ingroup Accessors
@@ -2389,26 +1880,24 @@ class CellAccessor :  public TriaAccessor<dim,dim,spacedim>
 {
 public:
   /**
-   * Propagate the AccessorData type
-   * into the present class.
+   * Propagate the AccessorData type into the present class.
    */
   typedef typename TriaAccessor<dim,dim,spacedim>::AccessorData AccessorData;
 
   /**
-   * Define the type of the
-   * container this is part of.
+   * Define the type of the container this is part of.
    */
   typedef Triangulation<dim, spacedim> Container;
 
   /**
-   *  @name Constructors
+   * @name Constructors
    */
   /**
    * @{
    */
 
   /**
-   *  Constructor.
+   * Constructor.
    */
   CellAccessor (const Triangulation<dim,spacedim> *parent     =  0,
                 const int                 level      = -1,
@@ -2421,34 +1910,23 @@ public:
   CellAccessor (const TriaAccessor<dim,dim,spacedim> &cell_accessor);
 
   /**
-   * Conversion constructor. This
-   * constructor exists to make certain
-   * constructs simpler to write in
-   * dimension independent code. For
-   * example, it allows assigning a face
-   * iterator to a line iterator, an
-   * operation that is useful in 2d but
-   * doesn't make any sense in 3d. The
-   * constructor here exists for the
-   * purpose of making the code conform to
-   * C++ but it will unconditionally abort;
-   * in other words, assigning a face
-   * iterator to a line iterator is better
-   * put into an if-statement that checks
-   * that the dimension is two, and assign
-   * to a quad iterator in 3d (an operator
-   * that, without this constructor would
-   * be illegal if we happen to compile for
+   * Conversion constructor. This constructor exists to make certain
+   * constructs simpler to write in dimension independent code. For example,
+   * it allows assigning a face iterator to a line iterator, an operation that
+   * is useful in 2d but doesn't make any sense in 3d. The constructor here
+   * exists for the purpose of making the code conform to C++ but it will
+   * unconditionally abort; in other words, assigning a face iterator to a
+   * line iterator is better put into an if-statement that checks that the
+   * dimension is two, and assign to a quad iterator in 3d (an operator that,
+   * without this constructor would be illegal if we happen to compile for
    * 2d).
    */
   template <int structdim2, int dim2, int spacedim2>
   CellAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
 
   /**
-   * Another conversion operator
-   * between objects that don't
-   * make sense, just like the
-   * previous one.
+   * Another conversion operator between objects that don't make sense, just
+   * like the previous one.
    */
   template <int structdim2, int dim2, int spacedim2>
   CellAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
@@ -2458,131 +1936,82 @@ public:
    */
 
   /**
-   *  @name Accessing sub-objects and neighbors
+   * @name Accessing sub-objects and neighbors
    */
   /**
    * @{
    */
 
   /**
-   *  Return a pointer to the
-   *  @p ith child. Overloaded
-   *  version which returns a more
-   *  reasonable iterator class.
+   * Return a pointer to the @p ith child. Overloaded version which returns a
+   * more reasonable iterator class.
    */
   TriaIterator<CellAccessor<dim, spacedim> >
   child (const unsigned int i) const;
 
   /**
-   * Return an iterator to the
-   * @p ith face of this cell.
+   * Return an iterator to the @p ith face of this cell.
    */
   TriaIterator<TriaAccessor<dim-1,dim,spacedim> >
   face (const unsigned int i) const;
 
   /**
-   * Return the (global) index of the
-   * @p ith face of this cell.
+   * Return the (global) index of the @p ith face of this cell.
    *
-   *  @note Despite the name, the index returned here is only
-   *  global in the sense that it is specific to a particular
-   *  Triangulation object or, in the case the triangulation is
-   *  actually of type parallel::distributed::Triangulation,
-   *  specific to that part of the distributed triangulation stored
-   *  on the current processor.
+   * @note Despite the name, the index returned here is only global in the
+   * sense that it is specific to a particular Triangulation object or, in the
+   * case the triangulation is actually of type
+   * parallel::distributed::Triangulation, specific to that part of the
+   * distributed triangulation stored on the current processor.
    */
   unsigned int
   face_index (const unsigned int i) const;
 
   /**
-   * Return an iterator to that
-   * cell that neighbors the
-   * present cell on the given face
-   * and subface number.
-   *
-   * To succeed, the present cell
-   * must not be further refined,
-   * and the neighbor on the given
-   * face must be further refined
-   * exactly once; the returned
-   * cell is then a child of that
-   * neighbor.
-   *
-   * The function may not be called
-   * in 1d, since there we have no
-   * subfaces.  The implementation
-   * of this function is rather
-   * straightforward in 2d, by
-   * first determining which face
-   * of the neighbor cell the
-   * present cell is bordering on
-   * (this is what the
-   * @p neighbor_of_neighbor
-   * function does), and then
-   * asking
-   * @p GeometryInfo::child_cell_on_subface
-   * for the index of the
-   * child.
-   *
-   * However, the situation is more
-   * complicated in 3d, since there faces may
-   * have more than one orientation, and we
-   * have to use @p face_orientation, @p
-   * face_flip and @p face_rotation for both
-   * this and the neighbor cell to figure out
-   * which cell we want to have.
-   *
-   * This can lead to surprising
-   * results: if we are sitting on
-   * a cell and are asking for a
-   * cell behind subface
-   * <tt>sf</tt>, then this means
-   * that we are considering the
-   * subface for the face in the
-   * natural direction for the
-   * present cell. However, if the
-   * face as seen from this cell
-   * has
-   * <tt>face_orientation()==false</tt>,
-   * then the child of the face
-   * that separates the present
-   * cell from the neighboring
-   * cell's child is not
-   * necessarily the @p sf-th child
-   * of the face of this cell. This
-   * is so because the @p
-   * subface_no on a cell corresponds to the
-   * subface with respect to the
-   * intrinsic ordering of the
-   * present cell, whereas children
-   * of face iterators are computed
-   * with respect to the intrinsic
-   * ordering of faces; these two
-   * orderings are only identical
-   * if the face orientation is @p
-   * true, and reversed otherwise.
-   *
-   * Similarly, effects of
-   * <tt>face_flip()==true</tt> and
-   * <tt>face_rotation()==true()</tt>, both
-   * of which indicate a non-standard face
-   * have to be considered.
-   *
-   * Fortunately, this is only very rarely of
-   * concern, since usually one simply wishes
-   * to loop over all finer neighbors at a
-   * given face of an active cell. Only in
-   * the process of refinement of a
-   * Triangulation we want to set neighbor
-   * information for both our child cells and
-   * the neighbor's children. Since we can
-   * respect orientation of faces from our
-   * current cell in that case, we do NOT
-   * respect face_orientation, face_flip and
-   * face_rotation of the present cell within
-   * this function, i.e. the returned
-   * neighbor's child is behind subface @p
-   * subface concerning the intrinsic
+   * Return an iterator to that cell that neighbors the present cell on the
+   * given face and subface number.
+   *
+   * To succeed, the present cell must not be further refined, and the
+   * neighbor on the given face must be further refined exactly once; the
+   * returned cell is then a child of that neighbor.
+   *
+   * The function may not be called in 1d, since there we have no subfaces.
+   * The implementation of this function is rather straightforward in 2d, by
+   * first determining which face of the neighbor cell the present cell is
+   * bordering on (this is what the @p neighbor_of_neighbor function does),
+   * and then asking @p GeometryInfo::child_cell_on_subface for the index of
+   * the child.
+   *
+   * However, the situation is more complicated in 3d, since there faces may
+   * have more than one orientation, and we have to use @p face_orientation,
+   * @p face_flip and @p face_rotation for both this and the neighbor cell to
+   * figure out which cell we want to have.
+   *
+   * This can lead to surprising results: if we are sitting on a cell and are
+   * asking for a cell behind subface <tt>sf</tt>, then this means that we are
+   * considering the subface for the face in the natural direction for the
+   * present cell. However, if the face as seen from this cell has
+   * <tt>face_orientation()==false</tt>, then the child of the face that
+   * separates the present cell from the neighboring cell's child is not
+   * necessarily the @p sf-th child of the face of this cell. This is so
+   * because the @p subface_no on a cell corresponds to the subface with
+   * respect to the intrinsic ordering of the present cell, whereas children
+   * of face iterators are computed with respect to the intrinsic ordering of
+   * faces; these two orderings are only identical if the face orientation is
+   * @p true, and reversed otherwise.
+   *
+   * Similarly, effects of <tt>face_flip()==true</tt> and
+   * <tt>face_rotation()==true()</tt>, both of which indicate a non-standard
+   * face have to be considered.
+   *
+   * Fortunately, this is only very rarely of concern, since usually one
+   * simply wishes to loop over all finer neighbors at a given face of an
+   * active cell. Only in the process of refinement of a Triangulation we want
+   * to set neighbor information for both our child cells and the neighbor's
+   * children. Since we can respect orientation of faces from our current cell
+   * in that case, we do NOT respect face_orientation, face_flip and
+   * face_rotation of the present cell within this function, i.e. the returned
+   * neighbor's child is behind subface @p subface concerning the intrinsic
    * ordering of the given face.
    */
   TriaIterator<CellAccessor<dim, spacedim> >
@@ -2590,109 +2019,73 @@ public:
                              const unsigned int subface_no) const;
 
   /**
-   *  Return a pointer to the
-   *  @p ith neighbor.  If the
-   *  neighbor does not exist, an
-   *  invalid iterator is returned.
+   * Return a pointer to the @p ith neighbor.  If the neighbor does not exist,
+   * an invalid iterator is returned.
    *
-   *  <b>Note</b> (cf. TriaLevel<0>):
-   *  The neighbor of a cell has at most the
-   *  same level as this cell, i.e. it may
-   *  or may not be refined.
+   * <b>Note</b> (cf. TriaLevel<0>): The neighbor of a cell has at most the
+   * same level as this cell, i.e. it may or may not be refined.
    */
   TriaIterator<CellAccessor<dim, spacedim>  >
   neighbor (const unsigned int i) const;
 
   /**
-   *  Return the index of the
-   *  @p ith neighbor.  If the
-   *  neighbor does not exist, its
-   *  index is -1.
+   * Return the index of the @p ith neighbor.  If the neighbor does not exist,
+   * its index is -1.
    */
   int neighbor_index (const unsigned int i) const;
 
   /**
-   *  Return the level of the
-   *  @p ith neighbor.  If the
-   *  neighbor does not exist, its
-   *  level is -1.
+   * Return the level of the @p ith neighbor.  If the neighbor does not exist,
+   * its level is -1.
    */
   int neighbor_level (const unsigned int i) const;
 
   /**
-   * Return the how-many'th
-   * neighbor this cell is of
-   * <tt>cell->neighbor(neighbor)</tt>,
-   * i.e. return the @p face_no
-   * such that
-   * <tt>cell->neighbor(neighbor)->neighbor(face_no)==cell</tt>. This
-   * function is the right one if
-   * you want to know how to get
-   * back from a neighbor to the
-   * present cell.
-   *
-   * Note that this operation is
-   * only useful if the neighbor is
-   * not coarser than the present
-   * cell. If the neighbor is
-   * coarser this function throws
-   * an exception. Use the @p
-   * neighbor_of_coarser_neighbor
-   * function in that case.
+   * Return the how-many'th neighbor this cell is of
+   * <tt>cell->neighbor(neighbor)</tt>, i.e. return the @p face_no such that
+   * <tt>cell->neighbor(neighbor)->neighbor(face_no)==cell</tt>. This function
+   * is the right one if you want to know how to get back from a neighbor to
+   * the present cell.
+   *
+   * Note that this operation is only useful if the neighbor is not coarser
+   * than the present cell. If the neighbor is coarser this function throws an
+   * exception. Use the @p neighbor_of_coarser_neighbor function in that case.
    */
   unsigned int neighbor_of_neighbor (const unsigned int neighbor) const;
 
   /**
-   * Return, whether the neighbor
-   * is coarser then the present
-   * cell. This is important in
-   * case of ansiotropic
-   * refinement where this
-   * information does not depend on
-   * the levels of the cells.
-   *
-   * Note, that in an anisotropic
-   * setting, a cell can only be
-   * coarser than another one at a
-   * given face, not on a general
-   * basis. The face of the finer
-   * cell is contained in the
-   * corresponding face of the
-   * coarser cell, the finer face
-   * is either a child or a
-   * grandchild of the coarser
-   * face.
+   * Return, whether the neighbor is coarser then the present cell. This is
+   * important in case of ansiotropic refinement where this information does
+   * not depend on the levels of the cells.
+   *
+   * Note, that in an anisotropic setting, a cell can only be coarser than
+   * another one at a given face, not on a general basis. The face of the
+   * finer cell is contained in the corresponding face of the coarser cell,
+   * the finer face is either a child or a grandchild of the coarser face.
    */
   bool neighbor_is_coarser (const unsigned int neighbor) const;
 
   /**
-   * This function is a generalization of the
-   * @p neighbor_of_neighbor function for the
-   * case of a coarser neighbor. It returns a
-   * pair of numbers, face_no and subface_no,
-   * with the following property, if the
-   * neighbor is not refined:
-   * <tt>cell->neighbor(neighbor)->neighbor_child_on_subface(face_no,subface_no)==cell</tt>.
-   * In 3D, a coarser neighbor can still be
-   * refined. In that case subface_no denotes the child index of the neighbors face that relates to our face:
-   * <tt>cell->neighbor(neighbor)->face(face_no)->child(subface_no)==cell->face(neighbor)</tt>.
-   * This case in 3d and how it can happen
-   * is discussed in the introduction of the
-   * step-30 tutorial program.
+   * This function is a generalization of the @p neighbor_of_neighbor function
+   * for the case of a coarser neighbor. It returns a pair of numbers, face_no
+   * and subface_no, with the following property, if the neighbor is not
+   * refined: <tt>cell->neighbor(neighbor)->neighbor_child_on_subface(face_no,
+   * subface_no)==cell</tt>. In 3D, a coarser neighbor can still be refined.
+   * In that case subface_no denotes the child index of the neighbors face
+   * that relates to our face: <tt>cell->neighbor(neighbor)->face(face_no)->ch
+   * ild(subface_no)==cell->face(neighbor)</tt>. This case in 3d and how it
+   * can happen is discussed in the introduction of the step-30 tutorial
+   * program.
    *
-   * This function is impossible
-   * for <tt>dim==1</tt>.
+   * This function is impossible for <tt>dim==1</tt>.
    */
   std::pair<unsigned int, unsigned int>
   neighbor_of_coarser_neighbor (const unsigned int neighbor) const;
 
   /**
-   * This function is a generalization of the
-   * @p neighbor_of_neighbor and the @p
-   * neighbor_of_coarser_neighbor
-   * functions. It checks whether the
-   * neighbor is coarser or not and calls the
-   * respective function. In both cases, only
+   * This function is a generalization of the @p neighbor_of_neighbor and the
+   * @p neighbor_of_coarser_neighbor functions. It checks whether the neighbor
+   * is coarser or not and calls the respective function. In both cases, only
    * the face_no is returned.
    */
   unsigned int neighbor_face_no (const unsigned int neighbor) const;
@@ -2702,54 +2095,35 @@ public:
    */
 
   /**
-   *  @name Dealing with boundary indicators
+   * @name Dealing with boundary indicators
    */
   /**
    * @{
    */
 
   /**
-   *  Return whether the @p ith
-   *  vertex or face (depending on
-   *  the dimension) is part of the
-   *  boundary. This is true, if
-   *  the @p ith neighbor does not
-   *  exist.
+   * Return whether the @p ith vertex or face (depending on the dimension) is
+   * part of the boundary. This is true, if the @p ith neighbor does not
+   * exist.
    */
   bool at_boundary (const unsigned int i) const;
 
   /**
-   *  Return whether the cell is at
-   *  the boundary. Being at the
-   *  boundary is defined by one
-   *  face being on the
-   *  boundary. Note that this does
-   *  not catch cases where only one
-   *  vertex of a quad or of a hex
-   *  is at the boundary, or where
-   *  only one line of a hex is at
-   *  the boundary while the
-   *  interiors of all faces are in
-   *  the interior of the
-   *  domain. For the latter case,
-   *  the @p has_boundary_lines
-   *  function is the right one to
-   *  ask.
+   * Return whether the cell is at the boundary. Being at the boundary is
+   * defined by one face being on the boundary. Note that this does not catch
+   * cases where only one vertex of a quad or of a hex is at the boundary, or
+   * where only one line of a hex is at the boundary while the interiors of
+   * all faces are in the interior of the domain. For the latter case, the @p
+   * has_boundary_lines function is the right one to ask.
    */
   bool at_boundary () const;
 
   /**
-   * This is a slight variation to
-   * the @p at_boundary function:
-   * for 1 and 2 dimensions,
-   * it is equivalent, for three
-   * dimensions it returns
-   * whether at least one of the 12
-   * lines of the hexahedron is at
-   * a boundary. This, of course,
-   * includes the case where a
-   * whole face is at the boundary,
-   * but also some other cases.
+   * This is a slight variation to the @p at_boundary function: for 1 and 2
+   * dimensions, it is equivalent, for three dimensions it returns whether at
+   * least one of the 12 lines of the hexahedron is at a boundary. This, of
+   * course, includes the case where a whole face is at the boundary, but also
+   * some other cases.
    */
   bool has_boundary_lines () const;
   /**
@@ -2757,7 +2131,7 @@ public:
    */
 
   /**
-   *  @name Dealing with refinement indicators
+   * @name Dealing with refinement indicators
    */
   /**
    * @{
@@ -2780,75 +2154,57 @@ public:
   RefinementCase<dim> refine_flag_set () const;
 
   /**
-   *  Flag the cell pointed to for
-   *  refinement. This function is
-   *  only allowed for active
-   *  cells. Keeping the default value for @p ref_case will mark this cell for
-   *  isotropic refinement.
+   * Flag the cell pointed to for refinement. This function is only allowed
+   * for active cells. Keeping the default value for @p ref_case will mark
+   * this cell for isotropic refinement.
    */
   void set_refine_flag (const RefinementCase<dim> ref_case = RefinementCase<dim>::isotropic_refinement) const;
 
   /**
-   *  Clear the refinement flag.
+   * Clear the refinement flag.
    */
   void clear_refine_flag () const;
 
   /**
-   *  Modify the refinement flag of the cell
-   *  to ensure (at least) the given
-   *  refinement case @p face_refinement_case at
-   *  face <tt>face_no</tt>, taking into
-   *  account orientation, flip and rotation
-   *  of the face. Return, whether the
-   *  refinement flag had to be
-   *  modified. This function is only allowed
-   *  for active cells.
+   * Modify the refinement flag of the cell to ensure (at least) the given
+   * refinement case @p face_refinement_case at face <tt>face_no</tt>, taking
+   * into account orientation, flip and rotation of the face. Return, whether
+   * the refinement flag had to be modified. This function is only allowed for
+   * active cells.
    */
   bool flag_for_face_refinement (const unsigned int face_no,
                                  const RefinementCase<dim-1> &face_refinement_case=RefinementCase<dim-1>::isotropic_refinement) const;
 
   /**
-   *  Modify the refinement flag of the cell
-   *  to ensure that line <tt>face_no</tt>
-   *  will be refined. Return, whether the
-   *  refinement flag had to be
-   *  modified. This function is only allowed
-   *  for active cells.
+   * Modify the refinement flag of the cell to ensure that line
+   * <tt>face_no</tt> will be refined. Return, whether the refinement flag had
+   * to be modified. This function is only allowed for active cells.
    */
   bool flag_for_line_refinement (const unsigned int line_no) const;
 
   /**
-   * Return the SubfaceCase of face
-   * <tt>face_no</tt>. Note that this is not
-   * identical to asking
-   * <tt>cell->face(face_no)->refinement_case()</tt>
-   * since the latter returns a RefinementCase<dim-1>
-   * and thus only considers one
-   * (anisotropic) refinement, whereas this
-   * function considers the complete
-   * refinement situation including possible
-   * refinement of the face's children. This
-   * function may only be called for active
-   * cells in 2d and 3d.
+   * Return the SubfaceCase of face <tt>face_no</tt>. Note that this is not
+   * identical to asking <tt>cell->face(face_no)->refinement_case()</tt> since
+   * the latter returns a RefinementCase<dim-1> and thus only considers one
+   * (anisotropic) refinement, whereas this function considers the complete
+   * refinement situation including possible refinement of the face's
+   * children. This function may only be called for active cells in 2d and 3d.
    */
   dealii::internal::SubfaceCase<dim> subface_case(const unsigned int face_no) const;
 
   /**
-   *  Return whether the coarsen flag
-   *  is set or not.
+   * Return whether the coarsen flag is set or not.
    */
   bool coarsen_flag_set () const;
 
   /**
-   *  Flag the cell pointed to for
-   *  coarsening. This function is
-   *  only allowed for active
-   *  cells.
+   * Flag the cell pointed to for coarsening. This function is only allowed
+   * for active cells.
    */
   void set_coarsen_flag () const;
 
   /**
-   *  Clear the coarsen flag.
+   * Clear the coarsen flag.
    */
   void clear_coarsen_flag () const;
   /**
@@ -2856,49 +2212,37 @@ public:
    */
 
   /**
-   *  @name Dealing with material indicators
+   * @name Dealing with material indicators
    */
   /**
    * @{
    */
 
   /**
-   * Return the material id of this
-   * cell.
+   * Return the material id of this cell.
    *
-   * For a typical use of this
-   * function, see the @ref step_28
-   * "step-28" tutorial program.
+   * For a typical use of this function, see the @ref step_28 "step-28"
+   * tutorial program.
    *
-   * See the @ref GlossMaterialId
-   * "glossary" for more
-   * information.
+   * See the @ref GlossMaterialId "glossary" for more information.
    */
   types::material_id material_id () const;
 
   /**
-   * Set the material id of this
-   * cell.
+   * Set the material id of this cell.
    *
-   * For a typical use of this
-   * function, see the @ref step_28
-   * "step-28" tutorial program.
+   * For a typical use of this function, see the @ref step_28 "step-28"
+   * tutorial program.
    *
-   * See the @ref GlossMaterialId
-   * "glossary" for more
-   * information.
+   * See the @ref GlossMaterialId "glossary" for more information.
    */
   void set_material_id (const types::material_id new_material_id) const;
 
   /**
-   * Set the material id of this
-   * cell and all its children (and
-   * grand-children, and so on) to
-   * the given value.
+   * Set the material id of this cell and all its children (and grand-
+   * children, and so on) to the given value.
    *
-   * See the @ref GlossMaterialId
-   * "glossary" for more
-   * information.
+   * See the @ref GlossMaterialId "glossary" for more information.
    */
   void recursively_set_material_id (const types::material_id new_material_id) const;
   /**
@@ -2906,59 +2250,51 @@ public:
    */
 
   /**
-   *  @name Dealing with subdomain indicators
+   * @name Dealing with subdomain indicators
    */
   /**
    * @{
    */
 
   /**
-   * Return the subdomain id of
-   * this cell.
+   * Return the subdomain id of this cell.
    *
-   * See the @ref GlossSubdomainId
-   * "glossary" for more
-   * information.
+   * See the @ref GlossSubdomainId "glossary" for more information.
    *
-   * @note The subdomain of a cell is a property only defined
-   * for active cells, i.e., cells that are not further
-   * refined. Consequently, you can only call this function if
-   * the cell it refers to has no children. For multigrid
-   * methods in parallel, it is also important to know which
+   * @note The subdomain of a cell is a property only defined for active
+   * cells, i.e., cells that are not further refined. Consequently, you can
+   * only call this function if the cell it refers to has no children. For
+   * multigrid methods in parallel, it is also important to know which
    * processor owns non-active cells, and for this you can call
    * level_subdomain_id().
    */
   types::subdomain_id subdomain_id () const;
 
   /**
-   * Set the subdomain id of this
-   * cell.
+   * Set the subdomain id of this cell.
    *
-   * See the @ref GlossSubdomainId
-   * "glossary" for more
-   * information. This function
-   * should not be called if you
-   * use a
-   * parallel::distributed::Triangulation
-   * object.
+   * See the @ref GlossSubdomainId "glossary" for more information. This
+   * function should not be called if you use a
+   * parallel::distributed::Triangulation object.
    *
-   * @note The subdomain of a cell is a property only defined
-   * for active cells, i.e., cells that are not further
-   * refined. Consequently, you can only call this function if
-   * the cell it refers to has no children. For multigrid
-   * methods in parallel, it is also important to know which
+   * @note The subdomain of a cell is a property only defined for active
+   * cells, i.e., cells that are not further refined. Consequently, you can
+   * only call this function if the cell it refers to has no children. For
+   * multigrid methods in parallel, it is also important to know which
    * processor owns non-active cells, and for this you can call
    * level_subdomain_id().
    */
   void set_subdomain_id (const types::subdomain_id new_subdomain_id) const;
 
   /**
-   * Get the level subdomain id of this cell. This is used for parallel multigrid.
+   * Get the level subdomain id of this cell. This is used for parallel
+   * multigrid.
    */
   types::subdomain_id level_subdomain_id () const;
 
   /**
-   * Set the level subdomain id of this cell. This is used for parallel multigrid.
+   * Set the level subdomain id of this cell. This is used for parallel
+   * multigrid.
    */
   void set_level_subdomain_id (const types::subdomain_id new_level_subdomain_id) const;
 
@@ -2967,19 +2303,15 @@ public:
    * Set the subdomain id of this cell (if it is active) or all its terminal
    * children (and grand-children, and so on, as long as they have no children
    * of their own) to the given value. Since the subdomain id is a concept
-   * that is only defined for cells that are active (i.e., have no children
-   * of their own), this function only sets the subdomain ids for all
-   * children and grand children of this cell that are actually active,
-   * skipping intermediate child cells.
-   *
-   * See the @ref GlossSubdomainId
-   * "glossary" for more
-   * information. This function
-   * should not be called if you
-   * use a
-   * parallel::distributed::Triangulation
-   * object since there the subdomain id is implicitly defined by which
-   * processor you're on.
+   * that is only defined for cells that are active (i.e., have no children of
+   * their own), this function only sets the subdomain ids for all children
+   * and grand children of this cell that are actually active, skipping
+   * intermediate child cells.
+   *
+   * See the @ref GlossSubdomainId "glossary" for more information. This
+   * function should not be called if you use a
+   * parallel::distributed::Triangulation object since there the subdomain id
+   * is implicitly defined by which processor you're on.
    */
   void recursively_set_subdomain_id (const types::subdomain_id new_subdomain_id) const;
   /**
@@ -2987,35 +2319,32 @@ public:
    */
 
   /**
-   *  @name Dealing with codim 1 cell orientation
+   * @name Dealing with codim 1 cell orientation
    */
   /**
    * @{
    */
 
   /**
-   * Return the orientation of
-   * this cell.
+   * Return the orientation of this cell.
    *
-   * For the meaning of this flag, see
-   * @ref GlossDirectionFlag .
+   * For the meaning of this flag, see @ref GlossDirectionFlag .
    */
   bool direction_flag () const;
 
   /**
-   *  Index of the parent of this cell within the level of the triangulation
-   *  to which the parent cell belongs. The level of the parent is of course
-   *  one lower than that of the present cell. If the parent does not exist
-   *  (i.e., if the object is at the coarsest level of the mesh hierarchy), an
-   *  exception is generated.
+   * Index of the parent of this cell within the level of the triangulation to
+   * which the parent cell belongs. The level of the parent is of course one
+   * lower than that of the present cell. If the parent does not exist (i.e.,
+   * if the object is at the coarsest level of the mesh hierarchy), an
+   * exception is generated.
    */
   int parent_index () const;
 
   /**
-   *  Return an iterator to the
-   *  parent. If the
-   *  parent does not exist (i.e., if the object is at the coarsest level of
-   *  the mesh hierarchy), an exception is generated.
+   * Return an iterator to the parent. If the parent does not exist (i.e., if
+   * the object is at the coarsest level of the mesh hierarchy), an exception
+   * is generated.
    */
   TriaIterator<CellAccessor<dim,spacedim> >
   parent () const;
@@ -3025,42 +2354,35 @@ public:
    */
 
   /**
-   *  @name Other functions
+   * @name Other functions
    */
   /**
    * @{
    */
 
   /**
-   * Test whether the cell has children
-   * (this is the criterion for activity
-   * of a cell).
+   * Test whether the cell has children (this is the criterion for activity of
+   * a cell).
    *
-   * See the @ref GlossActive "glossary"
-   * for more information.
+   * See the @ref GlossActive "glossary" for more information.
    */
   bool active () const;
 
   /**
-   * Return whether this cell is owned by the current processor
-   * or is owned by another processor. The function always returns
-   * true if applied to an object of type dealii::Triangulation,
-   * but may yield false if the triangulation is of type
-   * parallel::distributed::Triangulation.
+   * Return whether this cell is owned by the current processor or is owned by
+   * another processor. The function always returns true if applied to an
+   * object of type dealii::Triangulation, but may yield false if the
+   * triangulation is of type parallel::distributed::Triangulation.
    *
-   * See the @ref GlossGhostCell
-   * "glossary" and the @ref
-   * distributed module for more
-   * information.
+   * See the @ref GlossGhostCell "glossary" and the @ref distributed module
+   * for more information.
    *
    * @post The returned value is equal to <code>!is_ghost() &&
    * !is_artificial()</code>.
    *
-   * @note Whether a cell is a ghost cell, artificial, or is
-   * locally owned or is a property that only pertains to cells
-   * that are active. Consequently,
-   * you can only call this function if the cell it refers to has
-   * no children.
+   * @note Whether a cell is a ghost cell, artificial, or is locally owned or
+   * is a property that only pertains to cells that are active. Consequently,
+   * you can only call this function if the cell it refers to has no children.
    */
   bool is_locally_owned () const;
 
@@ -3071,120 +2393,74 @@ public:
   bool is_locally_owned_on_level () const;
 
   /**
-   * Return whether this cell
-   * exists in the global mesh but
-   * (i) is owned by another
-   * processor, i.e. has a
-   * subdomain_id different from
-   * the one the current processor
-   * owns and (ii) is adjacent to a
-   * cell owned by the current
-   * processor.
-   *
-   * This function only makes sense
-   * if the triangulation used is
-   * of kind
-   * parallel::distributed::Triangulation. In
-   * all other cases, the returned
+   * Return whether this cell exists in the global mesh but (i) is owned by
+   * another processor, i.e. has a subdomain_id different from the one the
+   * current processor owns and (ii) is adjacent to a cell owned by the
+   * current processor.
+   *
+   * This function only makes sense if the triangulation used is of kind
+   * parallel::distributed::Triangulation. In all other cases, the returned
    * value is always false.
    *
-   * See the @ref GlossGhostCell
-   * "glossary" and the @ref
-   * distributed module for more
-   * information.
+   * See the @ref GlossGhostCell "glossary" and the @ref distributed module
+   * for more information.
    *
-   * @post The returned value is equal to
-   * <code>!is_locally_owned() &&
+   * @post The returned value is equal to <code>!is_locally_owned() &&
    * !is_artificial()</code>.
    *
-   * @note Whether a cell is a ghost cell, artificial, or is
-   * locally owned or is a property that only pertains to cells
-   * that are active. Consequently,
-   * you can only call this function if the cell it refers to has
-   * no children.
+   * @note Whether a cell is a ghost cell, artificial, or is locally owned or
+   * is a property that only pertains to cells that are active. Consequently,
+   * you can only call this function if the cell it refers to has no children.
    */
   bool is_ghost () const;
 
   /**
-   * Return whether this cell is
-   * artificial, i.e. it isn't one
-   * of the cells owned by the
-   * current processor, and it also
-   * doesn't border on one. As a
-   * consequence, it exists in the
-   * mesh to ensure that each
-   * processor has all coarse mesh
-   * cells and that the 2:1 ratio
-   * of neighboring cells is
-   * maintained, but it is not one
-   * of the cells we should work on
-   * on the current processor. In
-   * particular, there is no
-   * guarantee that this cell
-   * isn't, in fact, further
-   * refined on one of the other
-   * processors.
-   *
-   * This function only makes sense
-   * if the triangulation used is
-   * of kind
-   * parallel::distributed::Triangulation. In
-   * all other cases, the returned
+   * Return whether this cell is artificial, i.e. it isn't one of the cells
+   * owned by the current processor, and it also doesn't border on one. As a
+   * consequence, it exists in the mesh to ensure that each processor has all
+   * coarse mesh cells and that the 2:1 ratio of neighboring cells is
+   * maintained, but it is not one of the cells we should work on on the
+   * current processor. In particular, there is no guarantee that this cell
+   * isn't, in fact, further refined on one of the other processors.
+   *
+   * This function only makes sense if the triangulation used is of kind
+   * parallel::distributed::Triangulation. In all other cases, the returned
    * value is always false.
    *
-   * See the @ref
-   * GlossArtificialCell "glossary"
-   * and the @ref distributed
+   * See the @ref GlossArtificialCell "glossary" and the @ref distributed
    * module for more information.
    *
-   * @post The returned value is equal to
-   * <code>!is_ghost() &&
+   * @post The returned value is equal to <code>!is_ghost() &&
    * !is_locally_owned()</code>.
    *
-   * @note Whether a cell is a ghost cell, artificial, or is
-   * locally owned is a property that only pertains to cells
-   * that are active. Consequently,
-   * you can only call this function if the cell it refers to has
-   * no children.
+   * @note Whether a cell is a ghost cell, artificial, or is locally owned is
+   * a property that only pertains to cells that are active. Consequently, you
+   * can only call this function if the cell it refers to has no children.
    */
   bool is_artificial () const;
 
   /**
-   * Test whether the point @p p
-   * is inside this cell. Points on
-   * the boundary are counted as
-   * being inside the cell.
+   * Test whether the point @p p is inside this cell. Points on the boundary
+   * are counted as being inside the cell.
    *
-   * Note that this function
-   * assumes that the mapping
-   * between unit cell and real
-   * cell is (bi-, tri-)linear,
-   * i.e. that faces in 2d and
-   * edges in 3d are straight
-   * lines. If you have higher
-   * order transformations, results
-   * may be different as to whether
-   * a point is in- or outside the
-   * cell in real space.
+   * Note that this function assumes that the mapping between unit cell and
+   * real cell is (bi-, tri-)linear, i.e. that faces in 2d and edges in 3d are
+   * straight lines. If you have higher order transformations, results may be
+   * different as to whether a point is in- or outside the cell in real space.
    *
-   * In case of codim>0, the point is first projected
-   * to the manifold where the cell is embedded and
-   * then check if this projection is inside the cell.
+   * In case of codim>0, the point is first projected to the manifold where
+   * the cell is embedded and then check if this projection is inside the
+   * cell.
    */
   bool point_inside (const Point<spacedim> &p) const;
 
   /**
-   *  Set the neighbor @p i of
-   *  this cell to the cell pointed
-   *  to by @p pointer.
+   * Set the neighbor @p i of this cell to the cell pointed to by @p pointer.
    *
-   * This function shouldn't really be
-   * public (but needs to for various
-   * reasons in order not to make a long
-   * list of functions friends): it
-   * modifies internal data structures and
-   * may leave things. Do not use it from
-   * application codes.
+   * This function shouldn't really be public (but needs to for various
+   * reasons in order not to make a long list of functions friends): it
+   * modifies internal data structures and may leave things. Do not use it
+   * from application codes.
    */
   void set_neighbor (const unsigned int i,
                      const TriaIterator<CellAccessor<dim, spacedim> > &pointer) const;
@@ -3224,46 +2500,27 @@ public:
 
 protected:
   /**
-   * This function assumes that the
-   * neighbor is not coarser than
-   * the current cell. In this case
-   * it returns the
-   * neighbor_of_neighbor() value.
-   * If, however, the neighbor is
-   * coarser this function returns
-   * an
+   * This function assumes that the neighbor is not coarser than the current
+   * cell. In this case it returns the neighbor_of_neighbor() value. If,
+   * however, the neighbor is coarser this function returns an
    * <code>invalid_unsigned_int</code>.
    *
-   * This function is not for
-   * public use. Use the function
-   * neighbor_of_neighbor() instead
-   * which throws an exception if
-   * called for a coarser
-   * neighbor. If neighbor is
-   * indeed coarser (you get to
-   * know this by e.g. the
-   * neighbor_is_coarser()
-   * function) then the
-   * neighbor_of_coarser_neighbor()
-   * function should be call. If
-   * you'd like to know only the
-   * <code>face_no</code> which is
-   * required to get back from the
-   * neighbor to the present cell
-   * then simply use the
-   * neighbor_face_no() function
-   * which can be used for coarser
-   * as well as noncoarser
-   * neighbors.
+   * This function is not for public use. Use the function
+   * neighbor_of_neighbor() instead which throws an exception if called for a
+   * coarser neighbor. If neighbor is indeed coarser (you get to know this by
+   * e.g. the neighbor_is_coarser() function) then the
+   * neighbor_of_coarser_neighbor() function should be call. If you'd like to
+   * know only the <code>face_no</code> which is required to get back from the
+   * neighbor to the present cell then simply use the neighbor_face_no()
+   * function which can be used for coarser as well as noncoarser neighbors.
    */
   unsigned int neighbor_of_neighbor_internal (const unsigned int neighbor) const;
 
   /**
-     As for any codim>0 we can use a similar code
-     and c++ does not allow partial templates.
-     we use this auxiliary function that is then
-     called from point_inside.
-  */
+   * As for any codim>0 we can use a similar code and c++ does not allow
+   * partial templates. we use this auxiliary function that is then called
+   * from point_inside.
+   */
   template<int dim_,int spacedim_ >
   bool point_inside_codim(const Point<spacedim_> &p) const;
 
@@ -3276,32 +2533,19 @@ private:
   void set_parent (const unsigned int parent_index);
 
   /**
-   * Set the orientation of this
-   * cell.
+   * Set the orientation of this cell.
    *
-   * For the meaning of this flag, see
-   * @ref GlossDirectionFlag .
+   * For the meaning of this flag, see @ref GlossDirectionFlag .
    */
   void set_direction_flag (const bool new_direction_flag) const;
   /**
-   *  Copy operator. This is
-   *  normally used in a context
-   *  like <tt>iterator a,b;
-   *  *a=*b;</tt>. Since the meaning is
-   *  to copy the object pointed to
-   *  by @p b to the object
-   *  pointed to by @p a and since
-   *  accessors are not real but
-   *  virtual objects, this
-   *  operation is not useful for
-   *  iterators on
-   *  triangulations. We declare
-   *  this function here private,
-   *  thus it may not be used from
-   *  outside.  Furthermore it is
-   *  not implemented and will give
-   *  a linker error if used
-   *  anyway.
+   * Copy operator. This is normally used in a context like <tt>iterator a,b;
+   * *a=*b;</tt>. Since the meaning is to copy the object pointed to by @p b
+   * to the object pointed to by @p a and since accessors are not real but
+   * virtual objects, this operation is not useful for iterators on
+   * triangulations. We declare this function here private, thus it may not be
+   * used from outside.  Furthermore it is not implemented and will give a
+   * linker error if used anyway.
    */
   void operator = (const CellAccessor<dim, spacedim> &);
 
index 9781cc01da11515c5f1b262b3309d26d88331ae8..edf89df1899404d8a27f4401013ab09ce37000df 100644 (file)
@@ -286,9 +286,8 @@ namespace internal
   namespace TriaAccessorBase
   {
     /**
-     * Out of a face object, get the
-     * sub-objects of dimensionality
-     * given by the last argument.
+     * Out of a face object, get the sub-objects of dimensionality given by
+     * the last argument.
      */
     template <int dim>
     inline
@@ -337,9 +336,8 @@ namespace internal
     }
 
     /**
-     * This function should never be
-     * used, but we need it for the
-     * template instantiation of TriaAccessorBase<dim,dim,spacedim>::objects() const
+     * This function should never be used, but we need it for the template
+     * instantiation of TriaAccessorBase<dim,dim,spacedim>::objects() const
      */
     template <int dim>
     inline
@@ -352,8 +350,7 @@ namespace internal
     }
 
     /**
-     * Copy the above functions for
-     * cell objects.
+     * Copy the above functions for cell objects.
      */
     template <int structdim, int dim>
     inline
@@ -539,9 +536,7 @@ namespace internal
     struct Implementation
     {
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int dim, int spacedim>
       static
@@ -617,9 +612,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -681,9 +674,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -729,9 +720,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -769,9 +758,7 @@ namespace internal
       }
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int dim, int spacedim>
       static
@@ -906,9 +893,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -945,9 +930,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -983,9 +966,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int structdim, int dim, int spacedim>
       static
@@ -1019,9 +1000,7 @@ namespace internal
       }
 
       /**
-       * Implementation of the function
-       * of some name in the mother
-       * class.
+       * Implementation of the function of some name in the mother class.
        */
       template <int dim, int spacedim>
       static
@@ -1084,8 +1063,7 @@ namespace internal
 
 
       /**
-       * Implementation of the function of same
-       * name in the enclosing class.
+       * Implementation of the function of same name in the enclosing class.
        */
       template <int dim, int spacedim>
       static
index f5e52f56e6a434584cc5f3ccf4c491cff0a9b78e..c5d59a4ddf4aaf45ca2af3921d0fa20129faac62 100644 (file)
@@ -34,20 +34,20 @@ template <int dim, int space_dim> class Triangulation;
 
 
 /**
- *   This class is used to represent a boundary to a triangulation.
- *   When a triangulation creates a new vertex on the boundary of the
- *   domain, it determines the new vertex' coordinates through the
- *   following code (here in two dimensions):
+ * This class is used to represent a boundary to a triangulation. When a
+ * triangulation creates a new vertex on the boundary of the domain, it
+ * determines the new vertex' coordinates through the following code (here in
+ * two dimensions):
  *   @code
  *     ...
  *     Point<2> new_vertex = boundary.get_new_point_on_line (line);
  *     ...
  *   @endcode
- *   @p line denotes the line at the boundary that shall be refined
- *   and for which we seek the common point of the two child lines.
+ * @p line denotes the line at the boundary that shall be refined and for
+ * which we seek the common point of the two child lines.
  *
- *   In 3D, a new vertex may be placed on the middle of a line or on
- *   the middle of a side. Respectively, the library calls
+ * In 3D, a new vertex may be placed on the middle of a line or on the middle
+ * of a side. Respectively, the library calls
  *   @code
  *     ...
  *     Point<3> new_line_vertices[4]
@@ -57,29 +57,29 @@ template <int dim, int space_dim> class Triangulation;
  *           boundary.get_new_point_on_line (face->line(3))  };
  *     ...
  *   @endcode
- *   to get the four midpoints of the lines bounding the quad at the
- *   boundary, and after that
+ * to get the four midpoints of the lines bounding the quad at the boundary,
+ * and after that
  *   @code
  *     ...
  *     Point<3> new_quad_vertex = boundary.get_new_point_on_quad (face);
  *     ...
  *   @endcode
- *   to get the midpoint of the face. It is guaranteed that this order
- *   (first lines, then faces) holds, so you can use information from
- *   the children of the four lines of a face, since these already exist
- *   at the time the midpoint of the face is to be computed.
+ * to get the midpoint of the face. It is guaranteed that this order (first
+ * lines, then faces) holds, so you can use information from the children of
+ * the four lines of a face, since these already exist at the time the
+ * midpoint of the face is to be computed.
  *
- *   Since iterators are passed to the functions, you may use information
- *   about boundary indicators and the like, as well as all other information
- *   provided by these objects.
+ * Since iterators are passed to the functions, you may use information about
+ * boundary indicators and the like, as well as all other information provided
+ * by these objects.
  *
- *   There are specializations, StraightBoundary, which places
- *   the new point right into the middle of the given points, and
- *   HyperBallBoundary creating a hyperball with given radius
- *   around a given center point.
+ * There are specializations, StraightBoundary, which places the new point
+ * right into the middle of the given points, and HyperBallBoundary creating a
+ * hyperball with given radius around a given center point.
  *
  * @ingroup boundary
- * @author Wolfgang Bangerth, 1999, 2001, 2009, Ralf Hartmann, 2001, 2008, Luca Heltai, 2014
+ * @author Wolfgang Bangerth, 1999, 2001, 2009, Ralf Hartmann, 2001, 2008,
+ * Luca Heltai, 2014
  */
 template <int dim, int spacedim=dim>
 class Boundary : public FlatManifold<dim, spacedim>
@@ -178,9 +178,9 @@ public:
    * have a kink at the vertices itself).
    *
    * @note Implementations of this function should be able to assume that the
-   * point p lies within or close to the face described by the first
-   * argument. In turn, callers of this function should ensure that this is in
-   * fact the case.
+   * point p lies within or close to the face described by the first argument.
+   * In turn, callers of this function should ensure that this is in fact the
+   * case.
    */
   virtual
   Tensor<1,spacedim>
@@ -189,8 +189,8 @@ public:
 
   /**
    * Compute the normal vectors to the boundary at each vertex of the given
-   * face. It is not required that the normal vectors be normed
-   * somehow. Neither is it required that the normals actually point outward.
+   * face. It is not required that the normal vectors be normed somehow.
+   * Neither is it required that the normals actually point outward.
    *
    * This function is needed to compute data for C1 mappings. The default
    * implementation is to throw an error, so you need not overload this
@@ -279,19 +279,18 @@ private:
 
 
 /**
- *   Specialization of Boundary<dim,spacedim>, which places the new point
- *   right into the middle of the given points. The middle is defined
- *   as the arithmetic mean of the points.
+ * Specialization of Boundary<dim,spacedim>, which places the new point right
+ * into the middle of the given points. The middle is defined as the
+ * arithmetic mean of the points.
  *
- *   This class does not really describe a boundary in the usual
- *   sense. By placing new points in the middle of old ones, it rather
- *   assumes that the boundary of the domain is given by the
- *   polygon/polyhedron defined by the boundary of the initial coarse
- *   triangulation.
+ * This class does not really describe a boundary in the usual sense. By
+ * placing new points in the middle of old ones, it rather assumes that the
+ * boundary of the domain is given by the polygon/polyhedron defined by the
+ * boundary of the initial coarse triangulation.
  *
- *   @ingroup boundary
+ * @ingroup boundary
  *
- *   @author Wolfgang Bangerth, 1998, 2001, Ralf Hartmann, 2001
+ * @author Wolfgang Bangerth, 1998, 2001, Ralf Hartmann, 2001
  */
 template <int dim, int spacedim=dim>
 class StraightBoundary : public Boundary<dim,spacedim>
index 2a544eb9fe1f80d21736b4713b99b5ce6abac05e..06d1965a1865eee3efe39ae164e2676988b56bb8 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Boundary object for the hull of a cylinder.  In three dimensions,
- * points are projected on a circular tube along the <tt>x-</tt>,
- * <tt>y-</tt> or <tt>z</tt>-axis (when using the first constructor of
- * this class), or an arbitrarily oriented cylinder described by the
- * direction of its axis and a point located on the axis. The radius
- * of the tube can be given independently. Similar to
- * HyperBallBoundary, new points are projected by dividing the
- * straight line between the old two points and adjusting the radius
- * from the axis.
+ * Boundary object for the hull of a cylinder.  In three dimensions, points
+ * are projected on a circular tube along the <tt>x-</tt>, <tt>y-</tt> or
+ * <tt>z</tt>-axis (when using the first constructor of this class), or an
+ * arbitrarily oriented cylinder described by the direction of its axis and a
+ * point located on the axis. The radius of the tube can be given
+ * independently. Similar to HyperBallBoundary, new points are projected by
+ * dividing the straight line between the old two points and adjusting the
+ * radius from the axis.
  *
- * This class was developed to be used in conjunction with the
- * @p cylinder function of GridGenerator. It should be used for
- * the hull of the cylinder only (boundary indicator 0). Its use is
- * discussed in detail in the results section of step-49.
+ * This class was developed to be used in conjunction with the @p cylinder
+ * function of GridGenerator. It should be used for the hull of the cylinder
+ * only (boundary indicator 0). Its use is discussed in detail in the results
+ * section of step-49.
  *
- * This class is derived from StraightBoundary rather than from
- * Boundary, which would seem natural, since this way we can use the
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
  * StraightBoundary::in_between() function.
  *
  * @ingroup boundary
@@ -59,72 +58,54 @@ public:
                     const unsigned int axis = 0);
 
   /**
-   * Constructor. If constructed
-   * with this constructor, the
-   * boundary described is a
-   * cylinder with an axis that
-   * points in direction #direction
-   * and goes through the given
-   * #point_on_axis. The direction
-   * may be arbitrarily scaled, and
-   * the given point may be any
-   * point on the axis.
+   * Constructor. If constructed with this constructor, the boundary described
+   * is a cylinder with an axis that points in direction #direction and goes
+   * through the given #point_on_axis. The direction may be arbitrarily
+   * scaled, and the given point may be any point on the axis.
    */
   CylinderBoundary (const double           radius,
                     const Point<spacedim> &direction,
                     const Point<spacedim> &point_on_axis);
 
   /**
-   * Refer to the general documentation of
-   * this class and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual Point<spacedim>
   get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
 
   /**
-   * Refer to the general documentation of
-   * this class and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual Point<spacedim>
   get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Calls
-   * @p get_intermediate_points_between_points.
+   * Calls @p get_intermediate_points_between_points.
    */
   virtual void
   get_intermediate_points_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line,
                                    std::vector<Point<spacedim> > &points) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Only implemented for <tt>dim=3</tt>
-   * and for <tt>points.size()==1</tt>.
+   * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
    */
   virtual void
   get_intermediate_points_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad,
                                    std::vector<Point<spacedim> > &points) const;
 
   /**
-   * Compute the normals to the
-   * boundary at the vertices of
-   * the given face.
+   * Compute the normals to the boundary at the vertices of the given face.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual void
   get_normals_at_vertices (const typename Triangulation<dim,spacedim>::face_iterator &face,
@@ -136,10 +117,8 @@ public:
   double get_radius () const;
 
   /**
-   * Exception. Thrown by the
-   * @p get_radius if the
-   * @p compute_radius_automatically,
-   * see below, flag is set true.
+   * Exception. Thrown by the @p get_radius if the @p
+   * compute_radius_automatically, see below, flag is set true.
    */
   DeclException0 (ExcRadiusNotSet);
 
@@ -163,24 +142,17 @@ protected:
 private:
 
   /**
-   * Called by
-   * @p get_intermediate_points_on_line
-   * and by
-   * @p get_intermediate_points_on_quad.
+   * Called by @p get_intermediate_points_on_line and by @p
+   * get_intermediate_points_on_quad.
    *
-   * Refer to the general
-   * documentation of
-   * @p get_intermediate_points_on_line
-   * in the documentation of the
-   * base class.
+   * Refer to the general documentation of @p get_intermediate_points_on_line
+   * in the documentation of the base class.
    */
   void get_intermediate_points_between_points (const Point<spacedim> &p0, const Point<spacedim> &p1,
                                                std::vector<Point<spacedim> > &points) const;
 
   /**
-   * Given a number for the axis,
-   * return a vector that denotes
-   * this direction.
+   * Given a number for the axis, return a vector that denotes this direction.
    */
   static Point<spacedim> get_axis_vector (const unsigned int axis);
 };
@@ -188,17 +160,16 @@ private:
 
 
 /**
- * Boundary object for the hull of a (truncated) cone with two
- * different radii at the two ends. If one radius is chosen to be 0
- * the object describes the boundary of a cone. In three dimensions,
- * points are projected on an arbitrarily oriented (truncated) cone
- * described by the two endpoints and the corresponding radii. Similar
- * to HyperBallBoundary, new points are projected by dividing the
- * straight line between the old two points and adjusting the radius
- * from the axis.
+ * Boundary object for the hull of a (truncated) cone with two different radii
+ * at the two ends. If one radius is chosen to be 0 the object describes the
+ * boundary of a cone. In three dimensions, points are projected on an
+ * arbitrarily oriented (truncated) cone described by the two endpoints and
+ * the corresponding radii. Similar to HyperBallBoundary, new points are
+ * projected by dividing the straight line between the old two points and
+ * adjusting the radius from the axis.
  *
- * This class is derived from StraightBoundary rather than from
- * Boundary, which would seem natural, since this way we can use the
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
  * StraightBoundary::in_between() function.
  *
  * As an example of use, consider the following code snippet:
@@ -212,11 +183,10 @@ private:
  *  triangulation.set_boundary (0, boundary);
  *  triangulation.refine_global (2);
  * @endcode
- * This will produce the following meshes after the two
- * refinements we perform, in 2d and 3d, respectively:
+ * This will produce the following meshes after the two refinements we
+ * perform, in 2d and 3d, respectively:
  *
- * @image html cone_2d.png
- * @image html cone_3d.png
+ * @image html cone_2d.png @image html cone_3d.png
  *
  * @author Markus B&uuml;rg, 2009
  */
@@ -225,17 +195,11 @@ class ConeBoundary : public StraightBoundary<dim>
 {
 public:
   /**
-   * Constructor. Here the boundary
-   * object is constructed. The
-   * points <tt>x_0</tt> and
-   * <tt>x_1</tt> describe the
-   * starting and ending points of
-   * the axis of the (truncated)
-   * cone. <tt>radius_0</tt>
-   * denotes the radius
-   * corresponding to <tt>x_0</tt>
-   * and <tt>radius_1</tt> the one
-   * corresponding to <tt>x_1</tt>.
+   * Constructor. Here the boundary object is constructed. The points
+   * <tt>x_0</tt> and <tt>x_1</tt> describe the starting and ending points of
+   * the axis of the (truncated) cone. <tt>radius_0</tt> denotes the radius
+   * corresponding to <tt>x_0</tt> and <tt>radius_1</tt> the one corresponding
+   * to <tt>x_1</tt>.
    */
   ConeBoundary (const double radius_0,
                 const double radius_1,
@@ -243,40 +207,32 @@ public:
                 const Point<dim> x_1);
 
   /**
-   * Return the radius of the
-   * (truncated) cone at given point
-   * <tt>x</tt> on the axis.
+   * Return the radius of the (truncated) cone at given point <tt>x</tt> on
+   * the axis.
    */
   double get_radius (const Point<dim> x) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   Point<dim>
   get_new_point_on_line (const typename Triangulation<dim>::line_iterator &line) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   Point<dim>
   get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Calls @p
-   * get_intermediate_points_between_points.
+   * Calls @p get_intermediate_points_between_points.
    */
   virtual
   void
@@ -284,14 +240,10 @@ public:
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Only implemented for
-   * <tt>dim=3</tt> and for
-   * <tt>points.size()==1</tt>.
+   * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
    */
   virtual
   void
@@ -299,14 +251,10 @@ public:
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Compute the normals to the
-   * boundary at the vertices of
-   * the given face.
+   * Compute the normals to the boundary at the vertices of the given face.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   void
@@ -315,14 +263,12 @@ public:
 
 protected:
   /**
-   * First radius of the (truncated)
-   * cone.
+   * First radius of the (truncated) cone.
    */
   const double radius_0;
 
   /**
-   * Second radius of the (truncated)
-   * cone.
+   * Second radius of the (truncated) cone.
    */
   const double radius_1;
 
@@ -338,16 +284,11 @@ protected:
 
 private:
   /**
-   * Called by @p
-   * get_intermediate_points_on_line
-   * and by @p
+   * Called by @p get_intermediate_points_on_line and by @p
    * get_intermediate_points_on_quad.
    *
-   * Refer to the general
-   * documentation of @p
-   * get_intermediate_points_on_line
-   * in the documentation of the
-   * base class.
+   * Refer to the general documentation of @p get_intermediate_points_on_line
+   * in the documentation of the base class.
    */
   void
   get_intermediate_points_between_points (const Point<dim> &p0,
@@ -358,21 +299,21 @@ private:
 
 
 /**
- *   Specialization of Boundary<dim>, which places the new point on
- *   the boundary of a ball in arbitrary dimension. It works by projecting
- *   the point in the middle of the old points onto the ball. The middle is
- *   defined as the arithmetic mean of the points.
+ * Specialization of Boundary<dim>, which places the new point on the boundary
+ * of a ball in arbitrary dimension. It works by projecting the point in the
+ * middle of the old points onto the ball. The middle is defined as the
+ * arithmetic mean of the points.
  *
- *   The center of the ball and its radius may be given upon construction of
- *   an object of this type. They default to the origin and a radius of 1.0.
+ * The center of the ball and its radius may be given upon construction of an
+ * object of this type. They default to the origin and a radius of 1.0.
  *
- *   This class is derived from StraightBoundary rather than from
- *   Boundary, which would seem natural, since this way we can use the
- *   StraightBoundary::in_between() function.
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
+ * StraightBoundary::in_between() function.
  *
- *   @ingroup boundary
+ * @ingroup boundary
  *
- *   @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
+ * @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
  */
 template <int dim, int spacedim=dim>
 class HyperBallBoundary : public StraightBoundary<dim,spacedim>
@@ -385,31 +326,26 @@ public:
                      const double     radius = 1.0);
 
   /**
-   * Refer to the general documentation of
-   * this class and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   Point<spacedim>
   get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
 
   /**
-   * Refer to the general documentation of
-   * this class and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   Point<spacedim>
   get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Calls
-   * @p get_intermediate_points_between_points.
+   * Calls @p get_intermediate_points_between_points.
    */
   virtual
   void
@@ -417,13 +353,10 @@ public:
                                    std::vector<Point<spacedim> > &points) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Only implemented for <tt>dim=3</tt>
-   * and for <tt>points.size()==1</tt>.
+   * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
    */
   virtual
   void
@@ -431,13 +364,10 @@ public:
                                    std::vector<Point<spacedim> > &points) const;
 
   /**
-   * Implementation of the function
-   * declared in the base class.
+   * Implementation of the function declared in the base class.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   Tensor<1,spacedim>
@@ -445,14 +375,10 @@ public:
                  const Point<spacedim> &p) const;
 
   /**
-   * Compute the normals to the
-   * boundary at the vertices of
-   * the given face.
+   * Compute the normals to the boundary at the vertices of the given face.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual
   void
@@ -472,10 +398,8 @@ public:
   get_radius () const;
 
   /**
-   * Exception. Thrown by the
-   * @p get_radius if the
-   * @p compute_radius_automatically,
-   * see below, flag is set true.
+   * Exception. Thrown by the @p get_radius if the @p
+   * compute_radius_automatically, see below, flag is set true.
    */
   DeclException0 (ExcRadiusNotSet);
 
@@ -493,37 +417,23 @@ protected:
   const double radius;
 
   /**
-   * This flag is @p false for
-   * this class and for all derived
-   * classes that set the radius by
-   * the constructor. For example
-   * this flag is @p false for the
-   * HalfHyperBallBoundary
-   * class but it is @p true for
-   * the HyperShellBoundary
-   * class, for example.  The
-   * latter class doesn't get its
-   * radii by the constructor but
-   * need to compute the radii
-   * automatically each time one of
-   * the virtual functions is
-   * called.
+   * This flag is @p false for this class and for all derived classes that set
+   * the radius by the constructor. For example this flag is @p false for the
+   * HalfHyperBallBoundary class but it is @p true for the HyperShellBoundary
+   * class, for example.  The latter class doesn't get its radii by the
+   * constructor but need to compute the radii automatically each time one of
+   * the virtual functions is called.
    */
   bool compute_radius_automatically;
 
 private:
 
   /**
-   * Called by
-   * @p get_intermediate_points_on_line
-   * and by
-   * @p get_intermediate_points_on_quad.
+   * Called by @p get_intermediate_points_on_line and by @p
+   * get_intermediate_points_on_quad.
    *
-   * Refer to the general
-   * documentation of
-   * @p get_intermediate_points_on_line
-   * in the documentation of the
-   * base class.
+   * Refer to the general documentation of @p get_intermediate_points_on_line
+   * in the documentation of the base class.
    */
   void get_intermediate_points_between_points (const Point<spacedim> &p0, const Point<spacedim> &p1,
                                                std::vector<Point<spacedim> > &points) const;
@@ -532,12 +442,12 @@ private:
 
 
 /**
- * Variant of HyperBallBoundary which denotes a half hyper ball
- * where the first coordinate is restricted to the range $x>=0$ (or
- * $x>=center(0)$). In two dimensions, this equals the right half
- * circle, in three space dimensions it is a half ball. This class
- * might be useful for computations with rotational symmetry, where
- * one dimension is the radius from the axis of rotation.
+ * Variant of HyperBallBoundary which denotes a half hyper ball where the
+ * first coordinate is restricted to the range $x>=0$ (or $x>=center(0)$). In
+ * two dimensions, this equals the right half circle, in three space
+ * dimensions it is a half ball. This class might be useful for computations
+ * with rotational symmetry, where one dimension is the radius from the axis
+ * of rotation.
  *
  * @ingroup boundary
  *
@@ -554,56 +464,42 @@ public:
                          const double     radius = 1.0);
 
   /**
-   * Check if on the line <tt>x==0</tt>,
-   * otherwise pass to the base
-   * class.
+   * Check if on the line <tt>x==0</tt>, otherwise pass to the base class.
    */
   virtual Point<dim>
   get_new_point_on_line (const typename Triangulation<dim>::line_iterator &line) const;
 
   /**
-   * Check if on the line <tt>x==0</tt>,
-   * otherwise pass to the base
-   * class.
+   * Check if on the line <tt>x==0</tt>, otherwise pass to the base class.
    */
   virtual Point<dim>
   get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Calls
-   * @p get_intermediate_points_between_points.
+   * Calls @p get_intermediate_points_between_points.
    */
   virtual void
   get_intermediate_points_on_line (const typename Triangulation<dim>::line_iterator &line,
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Only implemented for <tt>dim=3</tt>
-   * and for <tt>points.size()==1</tt>.
+   * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
    */
   virtual void
   get_intermediate_points_on_quad (const typename Triangulation<dim>::quad_iterator &quad,
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Compute the normals to the
-   * boundary at the vertices of
-   * the given face.
+   * Compute the normals to the boundary at the vertices of the given face.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual void
   get_normals_at_vertices (const typename Triangulation<dim>::face_iterator &face,
@@ -613,10 +509,9 @@ public:
 
 
 /**
- * Class describing the boundaries of a hyper shell. Only the center
- * of the two spheres needs to be given, the radii of inner and outer
- * sphere are computed automatically upon calling one of the virtual
- * functions.
+ * Class describing the boundaries of a hyper shell. Only the center of the
+ * two spheres needs to be given, the radii of inner and outer sphere are
+ * computed automatically upon calling one of the virtual functions.
  *
  * @ingroup boundary
  *
@@ -627,15 +522,10 @@ class HyperShellBoundary : public HyperBallBoundary<dim>
 {
 public:
   /**
-   * Constructor. The center of the
-   * spheres defaults to the
-   * origin.
+   * Constructor. The center of the spheres defaults to the origin.
    *
-   * Calls the constructor of its
-   * base @p HyperBallBoundary
-   * class with a dummy radius as
-   * argument. This radius will be
-   * ignored
+   * Calls the constructor of its base @p HyperBallBoundary class with a dummy
+   * radius as argument. This radius will be ignored
    */
   HyperShellBoundary (const Point<dim> &center = Point<dim>());
 };
@@ -643,12 +533,12 @@ public:
 
 
 /**
- * Variant of HyperShellBoundary which denotes a half hyper shell
- * where the first coordinate is restricted to the range $x>=0$ (or
- * $x>=center(0)$). In two dimensions, this equals the right half arc,
- * in three space dimensions it is a half shell. This class might be
- * useful for computations with rotational symmetry, where one
- * dimension is the radius from the axis of rotation.
+ * Variant of HyperShellBoundary which denotes a half hyper shell where the
+ * first coordinate is restricted to the range $x>=0$ (or $x>=center(0)$). In
+ * two dimensions, this equals the right half arc, in three space dimensions
+ * it is a half shell. This class might be useful for computations with
+ * rotational symmetry, where one dimension is the radius from the axis of
+ * rotation.
  *
  * @ingroup boundary
  *
@@ -659,16 +549,11 @@ class HalfHyperShellBoundary : public HyperShellBoundary<dim>
 {
 public:
   /**
-   * Constructor. The center of the
-   * spheres defaults to the
-   * origin.
+   * Constructor. The center of the spheres defaults to the origin.
    *
-   * If the radii are not specified, the
-   * class tries to infer them from the
-   * location of points on the
-   * boundary. This works in 2d, but not in
-   * 3d. As a consequence, in 3d these
-   * radii must be given.
+   * If the radii are not specified, the class tries to infer them from the
+   * location of points on the boundary. This works in 2d, but not in 3d. As a
+   * consequence, in 3d these radii must be given.
    */
   HalfHyperShellBoundary (const Point<dim> &center = Point<dim>(),
                           const double inner_radius = -1,
@@ -687,40 +572,30 @@ public:
   get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Calls
-   * @p get_intermediate_points_between_points.
+   * Calls @p get_intermediate_points_between_points.
    */
   virtual void
   get_intermediate_points_on_line (const typename Triangulation<dim>::line_iterator &line,
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    *
-   * Only implemented for <tt>dim=3</tt>
-   * and for <tt>points.size()==1</tt>.
+   * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
    */
   virtual void
   get_intermediate_points_on_quad (const typename Triangulation<dim>::quad_iterator &quad,
                                    std::vector<Point<dim> > &points) const;
 
   /**
-   * Compute the normals to the
-   * boundary at the vertices of
-   * the given face.
+   * Compute the normals to the boundary at the vertices of the given face.
    *
-   * Refer to the general
-   * documentation of this class
-   * and the documentation of the
-   * base class.
+   * Refer to the general documentation of this class and the documentation of
+   * the base class.
    */
   virtual void
   get_normals_at_vertices (const typename Triangulation<dim>::face_iterator &face,
@@ -740,16 +615,15 @@ private:
  * $y$-axis while the plane of the torus is the $x$-$z$ plane. A torus of this
  * kind can be generated by GridGenerator::torus.
  *
- * This class is only implemented for
- * <tt>dim=2</tt>,<tt>spacedim=3</tt>, that is, just the surface.
+ * This class is only implemented for <tt>dim=2</tt>,<tt>spacedim=3</tt>, that
+ * is, just the surface.
  */
 template <int dim, int spacedim>
 class TorusBoundary : public Boundary<dim,spacedim>
 {
 public:
   /**
-   * Constructor.<tt>R</tt> has to be
-   * greater than <tt>r</tt>.
+   * Constructor.<tt>R</tt> has to be greater than <tt>r</tt>.
    */
   TorusBoundary (const double R, const double r);
 
@@ -781,9 +655,8 @@ public:
     std::vector< Point< spacedim > >         &points ) const ;
 
   /**
-   * Get the normal from cartesian
-   * coordinates. This normal does not have
-   * unit length.
+   * Get the normal from cartesian coordinates. This normal does not have unit
+   * length.
    */
   virtual void get_normals_at_vertices (
     const typename Triangulation< dim, spacedim >::face_iterator &face,
@@ -792,41 +665,34 @@ public:
 private:
   //Handy functions
   /**
-   * Function that corrects the value and
-   * sign of angle, that is, given
-   * <tt>angle=tan(abs(y/x))</tt>; if <tt>
-   * (y > 0) && (x < 0) </tt> then
-   * <tt>correct_angle = Pi - angle</tt>,
-   * etc.
+   * Function that corrects the value and sign of angle, that is, given
+   * <tt>angle=tan(abs(y/x))</tt>; if <tt> (y > 0) && (x < 0) </tt> then
+   * <tt>correct_angle = Pi - angle</tt>, etc.
    */
 
   double           get_correct_angle(const double angle,const double x,const double y) const;
 
   /**
-   * Get the cartesian coordinates of the
-   * Torus, i.e., from <tt>(theta,phi)</tt>
-   * to <tt>(x,y,z)</tt>.
+   * Get the cartesian coordinates of the Torus, i.e., from
+   * <tt>(theta,phi)</tt> to <tt>(x,y,z)</tt>.
    */
   Point<spacedim>  get_real_coord(const Point<dim> &surfP) const ;
 
   /**
-   * Get the surface coordinates of the
-   * Torus, i.e., from <tt>(x,y,z)</tt> to
+   * Get the surface coordinates of the Torus, i.e., from <tt>(x,y,z)</tt> to
    * <tt>(theta,phi)</tt>.
    */
   Point<dim>       get_surf_coord(const Point<spacedim> &p) const ;
 
   /**
-   * Get the normal from surface
-   * coordinates. This normal does not have
-   * unit length.
+   * Get the normal from surface coordinates. This normal does not have unit
+   * length.
    */
   Point<spacedim>  get_surf_norm_from_sp(const Point<dim> &surfP)      const ;
 
   /**
-   * Get the normal from cartesian
-   * coordinates. This normal does not have
-   * unit length.
+   * Get the normal from cartesian coordinates. This normal does not have unit
+   * length.
    */
   Point<spacedim>  get_surf_norm(const Point<spacedim> &p) const ;
 
index a8fd738f24d08e13d20275c3ffcb67d2884a00d0..873548b12c52f71c1e5e352eb9c388e63d907b61 100644 (file)
@@ -28,16 +28,19 @@ namespace internal
   namespace Triangulation
   {
     /**
-     * General template for information belonging to the faces of a triangulation. These classes
-     * are similar to the TriaLevel classes. As cells are organised in a hierarchical
-     * structure of levels, each triangulation consists of several such TriaLevels. However the
-     * faces of a triangulation, lower dimensional objects like lines in 2D or lines and quads
-     * in 3D, do not have to be based on such a hierarchical structure. In fact we have to
-     * organise them in only one object if we want to enable anisotropic refinement. Therefore
-     * the TriaFaces classes store the information belonging to the faces of a
-     * triangulation separately from the TriaLevel classes.
+     * General template for information belonging to the faces of a
+     * triangulation. These classes are similar to the TriaLevel classes. As
+     * cells are organised in a hierarchical structure of levels, each
+     * triangulation consists of several such TriaLevels. However the faces of
+     * a triangulation, lower dimensional objects like lines in 2D or lines
+     * and quads in 3D, do not have to be based on such a hierarchical
+     * structure. In fact we have to organise them in only one object if we
+     * want to enable anisotropic refinement. Therefore the TriaFaces classes
+     * store the information belonging to the faces of a triangulation
+     * separately from the TriaLevel classes.
      *
-     * This general template is only provided to enable a specialization below.
+     * This general template is only provided to enable a specialization
+     * below.
      *
      * @author Tobias Leicht, 2006
      */
@@ -47,9 +50,8 @@ namespace internal
     {
     private:
       /**
-       * Make the constructor private so no one can use
-       * this general template. Only the specializations
-       * should be used.
+       * Make the constructor private so no one can use this general template.
+       * Only the specializations should be used.
        */
       TriaFaces();
     };
@@ -57,9 +59,10 @@ namespace internal
 
 
     /**
-     * Faces only have a meaning in <tt>dim@>=1</tt>. In <tt>dim=1</tt> they are vertices,
-     * which are handled differently, so only for <tt>dim@>=2</tt> the use of TriaFaces
-     * is reasonable, for <tt>dim=1</tt> the class is empty.
+     * Faces only have a meaning in <tt>dim@>=1</tt>. In <tt>dim=1</tt> they
+     * are vertices, which are handled differently, so only for
+     * <tt>dim@>=2</tt> the use of TriaFaces is reasonable, for <tt>dim=1</tt>
+     * the class is empty.
      */
     template<>
     class TriaFaces<1>
@@ -67,16 +70,14 @@ namespace internal
 
     public:
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
-       * Of course this returns 0.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object. Of course this returns 0.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -91,21 +92,20 @@ namespace internal
     {
     public:
       /**
-       *  The TriaObject containing the data of lines.
+       * The TriaObject containing the data of lines.
        */
       TriaObjects<TriaObject<1> > lines;
 
     public:
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -113,35 +113,34 @@ namespace internal
     };
 
     /**
-     * In <tt>dim=3</tt> the cells are hexes, the faces accordingly are quads. In
-     * addition to that we also have to enable the storage of lines.
+     * In <tt>dim=3</tt> the cells are hexes, the faces accordingly are quads.
+     * In addition to that we also have to enable the storage of lines.
      */
     template<>
     class TriaFaces<3>
     {
     public:
       /**
-       *  The TriaObject containing the data of quads.
+       * The TriaObject containing the data of quads.
        */
 
       TriaObjectsQuad3D quads;
 
       /**
-       *  The TriaObject containing the data of lines.
+       * The TriaObject containing the data of lines.
        */
       TriaObjects<TriaObject<1> > lines;
 
     public:
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
index 2ee7bf9a5d9a491b26613d74943bfab7219d15a3..79578f7f4852a0bca0c144e9166c1ed5349fff72 100644 (file)
@@ -49,21 +49,20 @@ template <typename> class TriaActiveIterator;
 
 
 /**
- * This class implements an iterator, analogous to those of the
- * standard template library (STL). It fulfills the requirements of a
- * bidirectional iterator.  See the C++ documentation for further
- * details of iterator specification and usage.
+ * This class implements an iterator, analogous to those of the standard
+ * template library (STL). It fulfills the requirements of a bidirectional
+ * iterator.  See the C++ documentation for further details of iterator
+ * specification and usage.
  *
  *
- * In addition to the STL
- * iterators an iterator of this class provides a <tt>-@></tt>
- * operator, i.e. you can write statements like
+ * In addition to the STL iterators an iterator of this class provides a
+ * <tt>-@></tt> operator, i.e. you can write statements like
  * @code
  * i->set_refine_flag ();
  * @endcode
  *
- * Iterators are used whenever a loop over all lines, quads, cells
- * etc.  is to be performed. These loops can then be coded like this:
+ * Iterators are used whenever a loop over all lines, quads, cells etc.  is to
+ * be performed. These loops can then be coded like this:
  * @code
  *   cell_iterator i   = tria.begin();
  *   cell_iterator end = tria.end();
@@ -72,36 +71,33 @@ template <typename> class TriaActiveIterator;
  *       cell->set_refine_flag();
  * @endcode
  *
- * Note the usage of <tt>++i</tt> instead of <tt>i++</tt> since this
- * does not involve temporaries and copying. It is recommended to use
- * a fixed value <tt>end</tt> inside the loop instead of
- * <tt>tria.end()</tt>, since the creation and copying of these
- * iterators is rather expensive compared to normal pointers.
+ * Note the usage of <tt>++i</tt> instead of <tt>i++</tt> since this does not
+ * involve temporaries and copying. It is recommended to use a fixed value
+ * <tt>end</tt> inside the loop instead of <tt>tria.end()</tt>, since the
+ * creation and copying of these iterators is rather expensive compared to
+ * normal pointers.
  *
- * The objects pointed to are accessors, derived from
- * TriaAccessorBase. Which kind of accessor is determined by the template
- * argument <em>Accessor</em>. These accessors are not so much data
- * structures as they are a collection of functions providing access
- * to the data stored in Tringulation or DoFHandler objects. Using
- * these accessors, the structure of these classes is hidden from the
- * application program.
+ * The objects pointed to are accessors, derived from TriaAccessorBase. Which
+ * kind of accessor is determined by the template argument <em>Accessor</em>.
+ * These accessors are not so much data structures as they are a collection of
+ * functions providing access to the data stored in Tringulation or DoFHandler
+ * objects. Using these accessors, the structure of these classes is hidden
+ * from the application program.
  *
  * <h3>Which iterator to use when</h3>
  *
- * @attention Application programs will rarely use TriaRawIterator,
- * but rather one of the derived classes TriaIterator or
- * TriaActiveIterator.
+ * @attention Application programs will rarely use TriaRawIterator, but rather
+ * one of the derived classes TriaIterator or TriaActiveIterator.
  *
  * <ul>
- * <li> TriaRawIterator objects point to lines, cells, etc in the
- * lists whether they are used or not (in the vectors, also
- * <i>dead</i> objects are stored, since deletion in vectors is
- * expensive and we also do not want to destroy the ordering induced
- * by the numbering in the vectors). Therefore not all raw iterators
- * point to valid objects.
+ * <li> TriaRawIterator objects point to lines, cells, etc in the lists
+ * whether they are used or not (in the vectors, also <i>dead</i> objects are
+ * stored, since deletion in vectors is expensive and we also do not want to
+ * destroy the ordering induced by the numbering in the vectors). Therefore
+ * not all raw iterators point to valid objects.
  *
- * <li> The derived class TriaIterator selects the valid cells, that
- * is, cells used somewhere in the triangulation hierarchy.
+ * <li> The derived class TriaIterator selects the valid cells, that is, cells
+ * used somewhere in the triangulation hierarchy.
  *
  * <li> TriaActiveIterator objects which only loop over active cells.
  * </ul>
@@ -109,119 +105,115 @@ template <typename> class TriaActiveIterator;
  * <h3>Purpose</h3>
  *
  * Iterators are not much slower than operating directly on the data
- * structures, since they perform the loops that you had to handcode
- * yourself anyway. Most iterator and accessor functions are inlined.
+ * structures, since they perform the loops that you had to handcode yourself
+ * anyway. Most iterator and accessor functions are inlined.
  *
  * The main functionality of iterators, resides in the <tt>++</tt> and
- * <tt>--</tt> operators. These move the iterator forward or backward
- * just as if it were a pointer into an array. Here, this operation is
- * not so easy, since it may include skipping some elements and the
- * transition between the triangulation levels. This is completely
- * hidden from the user, though you can still create an iterator
- * pointing to an arbitrary element.  Actually, the operation of
- * moving iterators back and forth is not done in the iterator
- * classes, but rather in the accessor classes. Since these are passed
- * as template arguments, you can write your own versions here to add
+ * <tt>--</tt> operators. These move the iterator forward or backward just as
+ * if it were a pointer into an array. Here, this operation is not so easy,
+ * since it may include skipping some elements and the transition between the
+ * triangulation levels. This is completely hidden from the user, though you
+ * can still create an iterator pointing to an arbitrary element.  Actually,
+ * the operation of moving iterators back and forth is not done in the
+ * iterator classes, but rather in the accessor classes. Since these are
+ * passed as template arguments, you can write your own versions here to add
  * more functionality.
  *
- * Furthermore, the iterators described here satisfy the requirement of
- * input and bidirectional iterators as stated by the C++ standard and
- * the STL documentation. It is therefore possible to use the
- * functions from the algorithm section of the C++ standard,
- * e.g. <em>count_if</em> (see the documentation for Triangulation for
- * an example) and several others.
+ * Furthermore, the iterators described here satisfy the requirement of input
+ * and bidirectional iterators as stated by the C++ standard and the STL
+ * documentation. It is therefore possible to use the functions from the
+ * algorithm section of the C++ standard, e.g. <em>count_if</em> (see the
+ * documentation for Triangulation for an example) and several others.
  *
  * <h3>Implementation</h3>
  *
- * The iterator class itself does not have much functionality. It only
- * becomes useful when assigned an Accessor (the second template
- * parameter), which really does the access to data. An Accessor
- * has to fulfil some requirements:
+ * The iterator class itself does not have much functionality. It only becomes
+ * useful when assigned an Accessor (the second template parameter), which
+ * really does the access to data. An Accessor has to fulfil some
+ * requirements:
  *
  * <ul>
  * <li> It must have two members named <tt>present_level</tt> and
  * <tt>present_index</tt> storing the address of the element in the
- * triangulation presently pointed to. These data have to be
- * accessible by all triangulation iterators listed above.
+ * triangulation presently pointed to. These data have to be accessible by all
+ * triangulation iterators listed above.
  *
- * <li> It must have a constructor which takes a Triangulation* and
- * two unsigned integers, denoting the initial level and index, as
- * well as a data object depending on its type.
+ * <li> It must have a constructor which takes a Triangulation* and two
+ * unsigned integers, denoting the initial level and index, as well as a data
+ * object depending on its type.
  *
- * <li> For the TriaIterator and the TriaActiveIterator class, it must
- * have a member function <tt>bool used()</tt>, for the latter a
- * member function <tt>bool active()</tt>.
+ * <li> For the TriaIterator and the TriaActiveIterator class, it must have a
+ * member function <tt>bool used()</tt>, for the latter a member function
+ * <tt>bool active()</tt>.
  *
  * <li> It must have void operators <tt>++</tt> and <tt>--</tt>.
  *
- * <li> It must declare a local <tt>typedef AccessorData</tt> which
- * states the data type the accessor expects to get passed as fourth
- * constructor argument. By declaring a local data type, the
- * respective iterator class may type-safely enforce that data type to
- * be one of its own constructor argument types. If an accessor class
- * does not need additional data, this type shall be <tt>void</tt>.
+ * <li> It must declare a local <tt>typedef AccessorData</tt> which states the
+ * data type the accessor expects to get passed as fourth constructor
+ * argument. By declaring a local data type, the respective iterator class may
+ * type-safely enforce that data type to be one of its own constructor
+ * argument types. If an accessor class does not need additional data, this
+ * type shall be <tt>void</tt>.
  * </ul>
  *
  * Then the iterator is able to do what it is supposed to. All of the
- * necessary functions are implemented in the <tt>Accessor</tt> base
- * class, but you may write your own version (non-virtual, since we
- * use templates) to add functionality.
+ * necessary functions are implemented in the <tt>Accessor</tt> base class,
+ * but you may write your own version (non-virtual, since we use templates) to
+ * add functionality.
  *
- * The accessors provided by the library are distributed in three
- * groups, determined by whether they access the data of
- * Triangulation, DoFHandler or MGDoFHandler. They are derived from
- * TriaAccessor, DoFAccessor and MGDoFAccessor,
- * respectively. In each group, there is an accessor to cells, which
- * have more functionality.
+ * The accessors provided by the library are distributed in three groups,
+ * determined by whether they access the data of Triangulation, DoFHandler or
+ * MGDoFHandler. They are derived from TriaAccessor, DoFAccessor and
+ * MGDoFAccessor, respectively. In each group, there is an accessor to cells,
+ * which have more functionality.
  *
- * @attention It seems impossible to preserve constness of a
- * triangulation through iterator usage. Thus, if you declare pointers
- * to a <tt>const</tt> triangulation object, you should be well aware
- * that you might involuntarily alter the data stored in the
- * triangulation.
+ * @attention It seems impossible to preserve constness of a triangulation
+ * through iterator usage. Thus, if you declare pointers to a <tt>const</tt>
+ * triangulation object, you should be well aware that you might involuntarily
+ * alter the data stored in the triangulation.
  *
- * @note More information on valid and invalid iterators can be found
- * in the documentation of TriaAccessorBase, where the iterator states are
- * checked and implemented.
+ * @note More information on valid and invalid iterators can be found in the
+ * documentation of TriaAccessorBase, where the iterator states are checked
+ * and implemented.
  *
  *
  * <h3>Past-the-end iterators</h3>
  *
  * There is a representation of past-the-end-pointers, denoted by special
- * values of the member variables @p present_level and @p present_index:
- * If <tt>present_level>=0</tt> and <tt>present_index>=0</tt>, then the object is valid
- * (there is no check whether the triangulation really has that
- * many levels or that many cells on the present level when we investigate
- * the state of an iterator; however, in many places where an iterator is
- * dereferenced we make this check);
- * if <tt>present_level==-1</tt> and <tt>present_index==-1</tt>, then the iterator points
- * past the end; in all other cases, the iterator is considered invalid.
- * You can check this by calling the <tt>state()</tt> function.
+ * values of the member variables @p present_level and @p present_index: If
+ * <tt>present_level>=0</tt> and <tt>present_index>=0</tt>, then the object is
+ * valid (there is no check whether the triangulation really has that many
+ * levels or that many cells on the present level when we investigate the
+ * state of an iterator; however, in many places where an iterator is
+ * dereferenced we make this check); if <tt>present_level==-1</tt> and
+ * <tt>present_index==-1</tt>, then the iterator points past the end; in all
+ * other cases, the iterator is considered invalid. You can check this by
+ * calling the <tt>state()</tt> function.
  *
  * An iterator is also invalid, if the pointer pointing to the Triangulation
  * object is invalid or zero.
  *
- * Finally, an iterator is invalid, if the element pointed to by
- * @p present_level and @p present_index is not used, i.e. if the @p used
- * flag is set to false.
+ * Finally, an iterator is invalid, if the element pointed to by @p
+ * present_level and @p present_index is not used, i.e. if the @p used flag is
+ * set to false.
  *
- * The last two checks are not made in <tt>state()</tt> since both cases should only
- * occur upon unitialized construction through @p memcpy and the like (the
- * parent triangulation can only be set upon construction). If
- * an iterator is constructed empty through the empty constructor,
- * <tt>present_level==-2</tt> and <tt>present_index==-2</tt>. Thus, the iterator is
- * invalid anyway, regardless of the state of the triangulation pointer
- * and the state of the element pointed to.
+ * The last two checks are not made in <tt>state()</tt> since both cases
+ * should only occur upon unitialized construction through @p memcpy and the
+ * like (the parent triangulation can only be set upon construction). If an
+ * iterator is constructed empty through the empty constructor,
+ * <tt>present_level==-2</tt> and <tt>present_index==-2</tt>. Thus, the
+ * iterator is invalid anyway, regardless of the state of the triangulation
+ * pointer and the state of the element pointed to.
  *
- * Past-the-end iterators may also be used to compare an iterator with the
- * <i>before-the-start</i> value, when running backwards. There is no
+ * Past-the-end iterators may also be used to compare an iterator with the <i
+ * >before-the-start</i> value, when running backwards. There is no
  * distinction between the iterators pointing past the two ends of a vector.
  *
  * By defining only one value to be past-the-end and making all other values
- * invalid provides a second track of security: if we should have forgotten
- * a check in the library when an iterator is incremented or decremented,
- * we automatically convert the iterator from the allowed state "past-the-end"
- * to the disallowed state "invalid" which increases the chance that somehwen
+ * invalid provides a second track of security: if we should have forgotten a
+ * check in the library when an iterator is incremented or decremented, we
+ * automatically convert the iterator from the allowed state "past-the-end" to
+ * the disallowed state "invalid" which increases the chance that somehwen
  * earlier than for past-the-end iterators an exception is raised.
  *
  * @ref Triangulation
@@ -235,34 +227,28 @@ class TriaRawIterator : public std::iterator<std::bidirectional_iterator_tag,Acc
 {
 public:
   /**
-   * Declare the type of the Accessor for
-   * use in the outside world. This way other
-   * functions can use the Accessor's type
-   * without knowledge of how the exact
-   * implementation actually is.
+   * Declare the type of the Accessor for use in the outside world. This way
+   * other functions can use the Accessor's type without knowledge of how the
+   * exact implementation actually is.
    */
   typedef Accessor AccessorType;
 
   /**
-   *  Empty constructor. Such an object
-   *  is not usable!
+   * Empty constructor. Such an object is not usable!
    */
   TriaRawIterator ();
 
   /**
-   *  Copy constructor.
+   * Copy constructor.
    */
   TriaRawIterator (const TriaRawIterator &);
 
   /**
-   * Construct an iterator from the given
-   * accessor; the given accessor needs not
-   * be of the same type as the accessor of
-   * this class is, but it needs to be
-   * convertible.
+   * Construct an iterator from the given accessor; the given accessor needs
+   * not be of the same type as the accessor of this class is, but it needs to
+   * be convertible.
    *
-   * Through this constructor, it is also
-   * possible to construct objects for
+   * Through this constructor, it is also possible to construct objects for
    * derived iterators:
    * @code
    * DoFCellAccessor dof_accessor;
@@ -273,21 +259,16 @@ public:
   explicit TriaRawIterator (const Accessor &a);
 
   /**
-   * Constructor. Assumes that the
-   * other accessor type is
-   * convertible to the current
-   * one.
+   * Constructor. Assumes that the other accessor type is convertible to the
+   * current one.
    */
   template <typename OtherAccessor>
   explicit TriaRawIterator (const OtherAccessor &a);
 
   /**
-   *  Proper constructor, initialized
-   *  with the triangulation, the
-   *  level and index of the object
-   *  pointed to. The last parameter is
-   *  of a type declared by the accessor
-   *  class.
+   * Proper constructor, initialized with the triangulation, the level and
+   * index of the object pointed to. The last parameter is of a type declared
+   * by the accessor class.
    */
   TriaRawIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
                    const int level,
@@ -295,149 +276,119 @@ public:
                    const typename AccessorType::AccessorData *local_data = 0);
 
   /**
-   * This is a conversion operator
-   * (constructor) which takes another
-   * iterator type and copies the data;
-   * this conversion works, if there is
-   * a conversion path from the
-   * @p OtherAccessor class to the @p Accessor
-   * class of this object. One such path
-   * would be derived class to base class,
-   * which for example may be used to get
-   * a Triangulation::raw_cell_iterator from
-   * a DoFHandler::raw_cell_iterator, since
-   * the DoFAccessor class is derived from
-   * the TriaAccessorBase class.
+   * This is a conversion operator (constructor) which takes another iterator
+   * type and copies the data; this conversion works, if there is a conversion
+   * path from the @p OtherAccessor class to the @p Accessor class of this
+   * object. One such path would be derived class to base class, which for
+   * example may be used to get a Triangulation::raw_cell_iterator from a
+   * DoFHandler::raw_cell_iterator, since the DoFAccessor class is derived
+   * from the TriaAccessorBase class.
    */
   template <typename OtherAccessor>
   TriaRawIterator (const TriaRawIterator<OtherAccessor> &i);
 
   /**
-   * Another conversion operator,
-   * where we use the pointers to
-   * the Triangulation from a
-   * TriaAccessorBase object, while
-   * the additional data is used
-   * according to the actual type
-   * of Accessor.
+   * Another conversion operator, where we use the pointers to the
+   * Triangulation from a TriaAccessorBase object, while the additional data
+   * is used according to the actual type of Accessor.
    */
   TriaRawIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
                    const typename Accessor::AccessorData *local_data);
 
   /**
-   * Conversion constructor. Same
-   * as above with the difference
-   * that it converts from
-   * TriaIterator classes (not
-   * TriaRawIterator).
+   * Conversion constructor. Same as above with the difference that it
+   * converts from TriaIterator classes (not TriaRawIterator).
    */
   template <typename OtherAccessor>
   TriaRawIterator (const TriaIterator<OtherAccessor> &i);
 
   /**
-   * Conversion constructor. Same
-   * as above with the difference
-   * that it converts from
-   * TriaActiveIterator classes
-   * (not TriaRawIterator).
+   * Conversion constructor. Same as above with the difference that it
+   * converts from TriaActiveIterator classes (not TriaRawIterator).
    */
   template <typename OtherAccessor>
   TriaRawIterator (const TriaActiveIterator<OtherAccessor> &i);
 
   /**
-   *  @name Dereferencing
+   * @name Dereferencing
    */
   /*@{*/
   /**
-   *  Dereferencing operator, returns a
-   *  reference to an accessor.
-   *  Usage is thus like <tt>(*i).index ();</tt>
+   * Dereferencing operator, returns a reference to an accessor. Usage is thus
+   * like <tt>(*i).index ();</tt>
    *
-   *  This function has to be specialized
-   *  explicitly for the different
-   *  @p Pointees, to allow an
-   *  <tt>iterator<1,TriangulationLevel<1>::LinesData></tt>
-   *  to point to <tt>tria->lines.cells[index]</tt> while
-   *  for one dimension higher it has
-   *  to point to <tt>tria->quads.cells[index]</tt>.
+   * This function has to be specialized explicitly for the different @p
+   * Pointees, to allow an
+   * <tt>iterator<1,TriangulationLevel<1>::LinesData></tt> to point to
+   * <tt>tria->lines.cells[index]</tt> while for one dimension higher it has
+   * to point to <tt>tria->quads.cells[index]</tt>.
    *
-   *  You must not dereference invalid or
-   *  past the end iterators.
+   * You must not dereference invalid or past the end iterators.
    */
   const Accessor &operator * () const;
 
   /**
-   *  Dereferencing operator, non-@p const
-   *  version.
+   * Dereferencing operator, non-@p const version.
    */
   Accessor &operator * ();
 
   /**
-   *  Dereferencing operator, returns a
-   *  reference of the cell pointed to.
-   *  Usage is thus like <tt>i->index ();</tt>
+   * Dereferencing operator, returns a reference of the cell pointed to. Usage
+   * is thus like <tt>i->index ();</tt>
    *
-   *  There is a @p const and a non-@p const
-   *  version.
+   * There is a @p const and a non-@p const version.
    */
   const Accessor *operator -> () const;
 
   /**
-   *  Dereferencing operator, non-@p const
-   *  version.
+   * Dereferencing operator, non-@p const version.
    */
   Accessor *operator -> ();
 
 
   /**
-  * In order be able to assign
-  * end-iterators for different
-  * accessors to each other, we
-  * need an access function which
-  * returns the accessor
-  * regardless of its state.
-  *
-  * @warning This function should
-  * not be used in application
-  * programs. It is only intended
-  * for limited purposes inside
-  * the library and it makes
-  * debugging much harder.
-  */
+   * In order be able to assign end-iterators for different accessors to each
+   * other, we need an access function which returns the accessor regardless
+   * of its state.
+   *
+   * @warning This function should not be used in application programs. It is
+   * only intended for limited purposes inside the library and it makes
+   * debugging much harder.
+   */
   const Accessor &access_any () const;
 
   /*@}*/
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   TriaRawIterator &operator = (const TriaRawIterator &);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
 //    template <class OtherAccessor>
 //    TriaRawIterator & operator = (const TriaRawIterator<OtherAccessor>&);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
 //    template <class OtherAccessor>
 //    TriaRawIterator & operator = (const TriaIterator<OtherAccessor>&);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
 //    template <class OtherAccessor>
 //    TriaRawIterator & operator = (const TriaActiveIterator<OtherAccessor>&);
 
   /**
-   *  Compare for equality.
+   * Compare for equality.
    */
   bool operator == (const TriaRawIterator &) const;
 
   /**
-   *  Compare for inequality.
+   * Compare for inequality.
    */
   bool operator != (const TriaRawIterator &) const;
 
@@ -449,97 +400,80 @@ public:
    * The relation is defined as follows:
    *
    * For objects of <tt>Accessor::structure_dimension <
-   * Accessor::dimension</tt>, we simply compare the index of such an
-   * object. The ordering is lexicographic
-   * according to the following hierarchy (in the sense, that the next
-   * test is only applied if the previous was inconclusive):
+   * Accessor::dimension</tt>, we simply compare the index of such an object.
+   * The ordering is lexicographic according to the following hierarchy (in
+   * the sense, that the next test is only applied if the previous was
+   * inconclusive):
    *
    * <ol>
-   * <li> The past-the-end iterator is always ordered last. Two
-   * past-the-end iterators rank the same, thus false is returned in
-   * that case.</li>
+   * <li> The past-the-end iterator is always ordered last. Two past-the-end
+   * iterators rank the same, thus false is returned in that case.</li>
    *
    * <li> The level of the cell.</li>
    * <li> The index of a cell inside the level.</li>
    * </ol>
    *
-   * @note The ordering is not consistent between different processor in
-   * a parallel::distributed::Triangulation because we rely on index(),
-   * which is likely not the same.
+   * @note The ordering is not consistent between different processor in a
+   * parallel::distributed::Triangulation because we rely on index(), which is
+   * likely not the same.
    */
   bool operator < (const TriaRawIterator &) const;
 
   /**@name Advancement of iterators*/
   /*@{*/
   /**
-   *  Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This
-   *  operator advances the iterator to
-   *  the next element and returns
-   *  a reference to <tt>*this</tt>.
+   * Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This operator advances
+   * the iterator to the next element and returns a reference to
+   * <tt>*this</tt>.
    */
   TriaRawIterator &operator ++ ();
 
   /**
-   *  Postfix <tt>++</tt> operator: <tt>iterator++</tt>. This
-   *  operator advances the iterator to
-   *  the next element, but
-   *  returns an iterator to the element
-   *  previously pointed to.
+   * Postfix <tt>++</tt> operator: <tt>iterator++</tt>. This operator advances
+   * the iterator to the next element, but returns an iterator to the element
+   * previously pointed to.
    *
-   *  Since this operation
-   *  involves a temporary and a copy
-   *  operation and since an
-   *  @p iterator is quite a large
-   *  object for a pointer, use the
-   *  prefix operator <tt>++iterator</tt> whenever
-   *  possible, especially in the header
-   *  of for loops
-   *  (<tt>for (; iterator!=end; ++iterator)</tt>) since there
-   *  you normally never need the
-   *  returned value.
+   * Since this operation involves a temporary and a copy operation and since
+   * an @p iterator is quite a large object for a pointer, use the prefix
+   * operator <tt>++iterator</tt> whenever possible, especially in the header
+   * of for loops (<tt>for (; iterator!=end; ++iterator)</tt>) since there you
+   * normally never need the returned value.
    */
   TriaRawIterator operator ++ (int);
 
   /**
-   *  Prefix @p -- operator: @p --iterator. This
-   *  operator moves the iterator to
-   *  the previous element and returns
-   *  a reference to <tt>*this</tt>.
+   * Prefix @p -- operator: @p --iterator. This operator moves the iterator to
+   * the previous element and returns a reference to <tt>*this</tt>.
    */
   TriaRawIterator &operator -- ();
 
   /**
-   *  Postfix @p -- operator: @p iterator--. This
-   *  operator moves the iterator to
-   *  the previous element, but
-   *  returns an iterator to the element
-   *  previously pointed to.
+   * Postfix @p -- operator: @p iterator--. This operator moves the iterator
+   * to the previous element, but returns an iterator to the element
+   * previously pointed to.
    *
-   *  The same applies as for the postfix operator++: If possible,
-   *  avoid it by using the prefix operator form to avoid the use
-   *  of a temporary variable.
+   * The same applies as for the postfix operator++: If possible, avoid it by
+   * using the prefix operator form to avoid the use of a temporary variable.
    */
   TriaRawIterator operator -- (int);
   /*@}*/
 
   /**
-   *  Return the state of the iterator.
+   * Return the state of the iterator.
    */
   IteratorState::IteratorStates state () const;
 
   /**
-   * Print the iterator to a stream
-   * <code>out</code>. The
-   * format is <tt>level.index</tt>.
+   * Print the iterator to a stream <code>out</code>. The format is
+   * <tt>level.index</tt>.
    */
   template <class STREAM>
   void print (STREAM &out) const;
 
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -547,8 +481,7 @@ public:
   /**@name Exceptions*/
   /*@{*/
   /**
-   *  Exception for TriaObjects with
-   *  level, i.e. cells.
+   * Exception for TriaObjects with level, i.e. cells.
    */
   DeclException1 (ExcDereferenceInvalidCell,
                   Accessor,
@@ -562,10 +495,8 @@ public:
                        "past_the_end" : "invalid")));
 
   /**
-   *  Exception for
-   *  lower-dimensional TriaObjects
-   *  without level, i.e. objects
-   *  faces are constructed with.
+   * Exception for lower-dimensional TriaObjects without level, i.e. objects
+   * faces are constructed with.
    */
   DeclException1 (ExcDereferenceInvalidObject,
                   Accessor,
@@ -578,7 +509,7 @@ public:
                        "past_the_end" : "invalid")));
 
   /**
-   *  Exception
+   * Exception
    */
   DeclException0 (ExcAdvanceInvalidObject);
   /**
@@ -595,17 +526,13 @@ protected:
 
 
   /**
-   * Make all other iterator class templates
-   * friends of this class. This is
-   * necessary for the implementation of
-   * conversion constructors.
+   * Make all other iterator class templates friends of this class. This is
+   * necessary for the implementation of conversion constructors.
    *
-   * In fact, we would not need them to
-   * be friends if they were for different
-   * dimensions, but the compiler dislikes
-   * giving a fixed dimension and variable
-   * accessor since then it says that would
-   * be a artial specialization.
+   * In fact, we would not need them to be friends if they were for different
+   * dimensions, but the compiler dislikes giving a fixed dimension and
+   * variable accessor since then it says that would be a artial
+   * specialization.
    */
   template <typename SomeAccessor> friend class TriaRawIterator;
   template <typename SomeAccessor> friend class TriaIterator;
@@ -614,8 +541,8 @@ protected:
 
 
 /**
- *   This specialization of TriaRawIterator provides access only to
- *   the <em>used</em> lines, quads, cells, etc.
+ * This specialization of TriaRawIterator provides access only to the
+ * <em>used</em> lines, quads, cells, etc.
  *
  * @ingroup grid
  * @ingroup Iterators
@@ -625,40 +552,31 @@ class TriaIterator : public TriaRawIterator<Accessor>
 {
 public:
   /**
-   *  Empty constructor. Such an object
-   *  is not usable!
+   * Empty constructor. Such an object is not usable!
    */
   TriaIterator ();
 
   /**
-   *  Copy constructor.
+   * Copy constructor.
    */
   TriaIterator (const TriaIterator<Accessor> &);
 
   /**
-   *  Cross copy constructor from
-   *  iterators pointing also to
-   *  non-active objects.
+   * Cross copy constructor from iterators pointing also to non-active
+   * objects.
    *
-   *  If the object pointed to is not
-   *  past-the-end and is not
-   *  used, the debug version raises
-   *  an error!
+   * If the object pointed to is not past-the-end and is not used, the debug
+   * version raises an error!
    */
   TriaIterator (const TriaRawIterator<Accessor> &);
 
   /**
-   *  Proper constructor, initialized
-   *  with the triangulation, the
-   *  level and index of the object
-   *  pointed to. The last parameter is
-   *  of a type declared by the accessor
-   *  class.
+   * Proper constructor, initialized with the triangulation, the level and
+   * index of the object pointed to. The last parameter is of a type declared
+   * by the accessor class.
    *
-   *  If the object pointed to is not
-   *  past-the-end and is not
-   *  used, the debug version raises
-   *  an error!
+   * If the object pointed to is not past-the-end and is not used, the debug
+   * version raises an error!
    */
   TriaIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
                 const int                 level,
@@ -666,92 +584,72 @@ public:
                 const typename Accessor::AccessorData *local_data = 0);
 
   /**
-   * Construct from an accessor of type OtherAccessor that is convertible
-   * to the type Accessor.
+   * Construct from an accessor of type OtherAccessor that is convertible to
+   * the type Accessor.
    */
   template <typename OtherAccessor>
   explicit TriaIterator (const OtherAccessor &a);
 
   /**
-   * This is a conversion operator
-   * (constructor) which takes another
-   * iterator type and copies the data;
-   * this conversion works, if there is
-   * a conversion path from the
-   * @p OtherAccessor class to the @p Accessor
-   * class of this object. One such path
-   * would be derived class to base class,
-   * which for example may be used to get
-   * a Triangulation::cell_iterator from
-   * a DoFHandler::cell_iterator, since
-   * the DoFAccessor class is derived from
+   * This is a conversion operator (constructor) which takes another iterator
+   * type and copies the data; this conversion works, if there is a conversion
+   * path from the @p OtherAccessor class to the @p Accessor class of this
+   * object. One such path would be derived class to base class, which for
+   * example may be used to get a Triangulation::cell_iterator from a
+   * DoFHandler::cell_iterator, since the DoFAccessor class is derived from
    * the TriaAccessorBase class.
    */
   template <typename OtherAccessor>
   TriaIterator (const TriaIterator<OtherAccessor> &i);
 
   /**
-   * Another conversion operator,
-   * where we use the pointers to
-   * the Triangulation from a
-   * TriaAccessorBase object, while
-   * the additional data is used
-   * according to the actual type
-   * of Accessor.
+   * Another conversion operator, where we use the pointers to the
+   * Triangulation from a TriaAccessorBase object, while the additional data
+   * is used according to the actual type of Accessor.
    */
   TriaIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
                 const typename Accessor::AccessorData *local_data);
 
   /**
-   * Similar conversion operator to the above
-   * one, but does a check whether the
-   * iterator points to a used element,
-   * which is necessary for raw iterators.
+   * Similar conversion operator to the above one, but does a check whether
+   * the iterator points to a used element, which is necessary for raw
+   * iterators.
    */
   template <typename OtherAccessor>
   TriaIterator (const TriaRawIterator<OtherAccessor> &i);
 
   /**
-   * Similar conversion operator to
-   * the above one, but for
-   * conversion from active
-   * iterators.
+   * Similar conversion operator to the above one, but for conversion from
+   * active iterators.
    */
   template <typename OtherAccessor>
   TriaIterator (const TriaActiveIterator<OtherAccessor> &i);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   TriaIterator<Accessor> &
   operator = (const TriaIterator<Accessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to a used
-   *  element.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to a used element.
    */
   TriaIterator<Accessor> &
   operator = (const TriaRawIterator<Accessor> &);
 
   /**
-   *  Assignment
-   *  operator. Requires, that
-   *  Accessor can be copied from
-   *  OtherAccessor.
+   * Assignment operator. Requires, that Accessor can be copied from
+   * OtherAccessor.
    */
   template <class OtherAccessor>
   TriaIterator<Accessor> &
   operator = (const TriaIterator<OtherAccessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to a used
-   *  element. Requires, that
-   *  Accessor can be copied from
-   *  OtherAccessor.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to a used element. Requires, that Accessor can be copied
+   * from OtherAccessor.
    */
   template <class OtherAccessor>
   TriaIterator<Accessor> &
@@ -760,58 +658,47 @@ public:
   /**@name Advancement of iterators*/
   /*@{*/
   /**
-   *  Prefix <tt>++</tt> operator: <tt>++i</tt>. This
-   *  operator advances the iterator to
-   *  the next used element and returns
-   *  a reference to <tt>*this</tt>.
+   * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
+   * iterator to the next used element and returns a reference to
+   * <tt>*this</tt>.
    */
   TriaIterator<Accessor> &operator ++ ();
 
   /**
-   *  Postfix <tt>++</tt> operator: <tt>i++</tt>. This
-   *  operator advances the iterator to
-   *  the next used element, but
-   *  returns an iterator to the element
-   *  previously pointed to. Since this
-   *  involves a temporary and a copy
-   *  operation and since an
-   *  @p active_iterator is quite a large
-   *  object for a pointer, use the
-   *  prefix operator <tt>++i</tt> whenever
-   *  possible, especially in the head
-   *  of for loops
-   *  (<tt>for (; i!=end; ++i)</tt>) since there
-   *  you normally never need the
-   *  returned value.
+   * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
+   * iterator to the next used element, but returns an iterator to the element
+   * previously pointed to. Since this involves a temporary and a copy
+   * operation and since an @p active_iterator is quite a large object for a
+   * pointer, use the prefix operator <tt>++i</tt> whenever possible,
+   * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
+   * there you normally never need the returned value.
    */
   TriaIterator<Accessor> operator ++ (int);
 
   /**
-   *  Prefix @p -- operator: @p --i. This
-   *  operator advances the iterator to
-   *  the previous used element and returns
-   *  a reference to <tt>*this</tt>.
+   * Prefix @p -- operator: @p --i. This operator advances the iterator to the
+   * previous used element and returns a reference to <tt>*this</tt>.
    */
   TriaIterator<Accessor> &operator -- ();
 
   /**
-   *  Postfix @p -- operator: @p i--.
+   * Postfix @p -- operator: @p i--.
    */
   TriaIterator<Accessor> operator -- (int);
   /*@}*/
 
   /**
-   *  Exception
+   * Exception
    */
   DeclException0 (ExcAssignmentOfUnusedObject);
 };
 
 
 /**
- *   This specialization of TriaIterator provides access only to the
- *   <em>active</em> lines, quads, cells, etc. An active cell is a
- *   cell which is not refined and thus a cell on which calculations
- *   on the finest level are done.
+ * This specialization of TriaIterator provides access only to the
+ * <em>active</em> lines, quads, cells, etc. An active cell is a cell which is
+ * not refined and thus a cell on which calculations on the finest level are
+ * done.
  *
  * @ingroup grid
  * @ingroup Iterators
@@ -821,52 +708,40 @@ class TriaActiveIterator : public TriaIterator<Accessor>
 {
 public:
   /**
-   *  Empty constructor. Such an object
-   *  is not usable!
+   * Empty constructor. Such an object is not usable!
    */
   TriaActiveIterator ();
 
   /**
-   *  Copy constructor.
+   * Copy constructor.
    */
   TriaActiveIterator (const TriaActiveIterator<Accessor> &);
 
   /**
-   *  Cross copy constructor from
-   *  iterators pointing also to
-   *  non-active objects.
+   * Cross copy constructor from iterators pointing also to non-active
+   * objects.
    *
-   *  If the object pointed to is not
-   *  past-the-end and is not
-   *  active, the debug version raises
-   *  an error!
+   * If the object pointed to is not past-the-end and is not active, the debug
+   * version raises an error!
    */
   TriaActiveIterator (const TriaRawIterator<Accessor> &);
 
   /**
-   *  Cross copy constructor from
-   *  iterators pointing also to
-   *  non-active objects.
+   * Cross copy constructor from iterators pointing also to non-active
+   * objects.
    *
-   *  If the object pointed to is not
-   *  past-the-end and is not
-   *  active, the debug version raises
-   *  an error!
+   * If the object pointed to is not past-the-end and is not active, the debug
+   * version raises an error!
    */
   TriaActiveIterator (const TriaIterator<Accessor> &);
 
   /**
-   *  Proper constructor, initialized
-   *  with the triangulation, the
-   *  level and index of the object
-   *  pointed to. The last parameter is
-   *  of a type declared by the accessor
-   *  class.
+   * Proper constructor, initialized with the triangulation, the level and
+   * index of the object pointed to. The last parameter is of a type declared
+   * by the accessor class.
    *
-   *  If the object pointed to is not
-   *  past-the-end and is not
-   *  active, the debug version raises
-   *  an error!
+   * If the object pointed to is not past-the-end and is not active, the debug
+   * version raises an error!
    */
   TriaActiveIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
                       const int level,
@@ -874,150 +749,115 @@ public:
                       const typename Accessor::AccessorData *local_data = 0);
 
   /**
-   * This is a conversion operator
-   * (constructor) which takes another
-   * iterator type and copies the data;
-   * this conversion works, if there is
-   * a conversion path from the
-   * @p OtherAccessor class to the @p Accessor
-   * class of this object. One such path
-   * would be derived class to base class,
-   * which for example may be used to get
-   * a Triangulation::active_cell_iterator from
-   * a DoFHandler::active_cell_iterator, since
-   * the DoFAccessor class is derived from
-   * the TriaAccessorBase class.
+   * This is a conversion operator (constructor) which takes another iterator
+   * type and copies the data; this conversion works, if there is a conversion
+   * path from the @p OtherAccessor class to the @p Accessor class of this
+   * object. One such path would be derived class to base class, which for
+   * example may be used to get a Triangulation::active_cell_iterator from a
+   * DoFHandler::active_cell_iterator, since the DoFAccessor class is derived
+   * from the TriaAccessorBase class.
    */
   template <typename OtherAccessor>
   TriaActiveIterator (const TriaActiveIterator<OtherAccessor> &i);
 
   /**
-  * Another conversion operator,
-  * where we use the pointers to
-  * the Triangulation from a
-  * TriaAccessorBase object, while
-  * the additional data is used
-  * according to the actual type
-  * of Accessor.
-  */
+   * Another conversion operator, where we use the pointers to the
+   * Triangulation from a TriaAccessorBase object, while the additional data
+   * is used according to the actual type of Accessor.
+   */
   TriaActiveIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
                       const typename Accessor::AccessorData *local_data);
 
   /**
-   * Similar conversion operator to the above
-   * one, but does a check whether the
-   * iterator points to a used element,
-   * and is active, which is necessary for
-   * raw iterators. Since usual iterators
-   * are also raw iterators, this constructor
-   * works also for parameters of type
+   * Similar conversion operator to the above one, but does a check whether
+   * the iterator points to a used element, and is active, which is necessary
+   * for raw iterators. Since usual iterators are also raw iterators, this
+   * constructor works also for parameters of type
    * <tt>TriaIterator<OtherAccessor></tt>.
    */
   template <typename OtherAccessor>
   TriaActiveIterator (const TriaRawIterator<OtherAccessor> &i);
 
   /**
-   *  Assignment operator.
+   * Assignment operator.
    */
   TriaActiveIterator<Accessor> &
   operator = (const TriaActiveIterator<Accessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to an active
-   *  element.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to an active element.
    */
   TriaActiveIterator<Accessor> &
   operator = (const TriaIterator<Accessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to an active
-   *  element or past the end.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to an active element or past the end.
    */
   TriaActiveIterator<Accessor> &
   operator = (const TriaRawIterator<Accessor> &);
 
   /**
-   *  Assignment operator. Requires, that
-   *  Accessor can be copied from
-   *  OtherAccessor.
+   * Assignment operator. Requires, that Accessor can be copied from
+   * OtherAccessor.
    */
   template <class OtherAccessor>
   TriaActiveIterator<Accessor> &
   operator = (const TriaActiveIterator<OtherAccessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to an active
-   *  element or past the end. Requires, that
-   *  Accessor can be copied from
-   *  OtherAccessor.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to an active element or past the end. Requires, that
+   * Accessor can be copied from OtherAccessor.
    */
   template <class OtherAccessor>
   TriaActiveIterator<Accessor> &
   operator = (const TriaRawIterator<OtherAccessor> &);
 
   /**
-   *  Cross assignment operator. This
-   *  assignment is only valid if the
-   *  given iterator points to an active
-   *  element. Requires, that
-   *  Accessor can be copied from
-   *  OtherAccessor.
+   * Cross assignment operator. This assignment is only valid if the given
+   * iterator points to an active element. Requires, that Accessor can be
+   * copied from OtherAccessor.
    */
   template <class OtherAccessor>
   TriaActiveIterator<Accessor> &
   operator = (const TriaIterator<OtherAccessor> &);
 
   /**
-   *  Prefix <tt>++</tt> operator: <tt>++i</tt>. This
-   *  operator advances the iterator to
-   *  the next active element and returns
-   *  a reference to <tt>*this</tt>.
+   * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
+   * iterator to the next active element and returns a reference to
+   * <tt>*this</tt>.
    */
   TriaActiveIterator<Accessor> &operator ++ ();
 
   /**@name Advancement of iterators*/
   /*@{*/
   /**
-   *  Postfix <tt>++</tt> operator: <tt>i++</tt>. This
-   *  operator advances the iterator to
-   *  the next active element, but
-   *  returns an iterator to the element
-   *  previously pointed to. Since this
-   *  involves a temporary and a copy
-   *  operation and since an
-   *  @p active_iterator is quite a large
-   *  object for a pointer, use the
-   *  prefix operator <tt>++i</tt> whenever
-   *  possible, especially in the head
-   *  of for loops
-   *  (<tt>for (; i!=end; ++i)</tt>) since there
-   *  you normally never need the
-   *  returned value.
+   * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
+   * iterator to the next active element, but returns an iterator to the
+   * element previously pointed to. Since this involves a temporary and a copy
+   * operation and since an @p active_iterator is quite a large object for a
+   * pointer, use the prefix operator <tt>++i</tt> whenever possible,
+   * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
+   * there you normally never need the returned value.
    */
   TriaActiveIterator<Accessor> operator ++ (int);
 
   /**
-   *  Prefix @p -- operator: @p --i. This
-   *  operator advances the iterator to
-   *  the previous active element and
-   *  returns a reference to <tt>*this</tt>.
+   * Prefix @p -- operator: @p --i. This operator advances the iterator to the
+   * previous active element and returns a reference to <tt>*this</tt>.
    */
   TriaActiveIterator<Accessor> &operator -- ();
 
   /**
-   *  Postfix @p -- operator: @p i--.
+   * Postfix @p -- operator: @p i--.
    */
   TriaActiveIterator<Accessor> operator -- (int);
   /*@}*/
 
   /**
-   *  Exception
+   * Exception
    */
   DeclException0 (ExcAssignmentOfInactiveObject);
 };
@@ -1317,10 +1157,9 @@ TriaActiveIterator<Accessor>::TriaActiveIterator (const TriaRawIterator<OtherAcc
 
 
 /**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
  *
  * @author Wolfgang Bangerth, 1998
  */
@@ -1336,10 +1175,9 @@ std::ostream &operator << (std::ostream                        &out,
 
 
 /**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
  *
  * @author Wolfgang Bangerth, 1998
  */
@@ -1355,10 +1193,9 @@ std::ostream &operator << (std::ostream                     &out,
 
 
 /**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
  *
  * @author Wolfgang Bangerth, 1998
  */
index ff2afe3666c60f36b57b60834e2b418520b3a87e..2a6ef5aaa8d11437db44e959d7b6f616aadca845 100644 (file)
@@ -22,8 +22,8 @@
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Namespace in which an enumeration is declared that denotes the
- * states in which an iterator can be in.
+ * Namespace in which an enumeration is declared that denotes the states in
+ * which an iterator can be in.
  *
  * @ingroup Iterators
  */
@@ -31,8 +31,7 @@ namespace IteratorState
 {
 
   /**
-   *   The three states an iterator can be in: valid, past-the-end and
-   *   invalid.
+   * The three states an iterator can be in: valid, past-the-end and invalid.
    */
   enum IteratorStates
   {
index 28d2a8ab1bf56d9f4c5a4e130efcdfa230d8643e..355d62a1059843cad00bf5f9b7ff3538042115ff 100644 (file)
@@ -38,31 +38,31 @@ namespace internal
     struct Iterators;
 
     /**
-     *  This class implements some types which differ between the dimensions.
-     *  These are the declararions for the 1D case only. See the @ref Iterators
-     *  module for more information.
+     * This class implements some types which differ between the dimensions.
+     * These are the declararions for the 1D case only. See the @ref Iterators
+     * module for more information.
      *
-     *  A @p line_iterator is typdef'd to an iterator operating on the
-     *  @p lines member variable of a <tt>Triangulation<1></tt> object. An
-     *  @p active_line_iterator only operates on the active lines.
-     *  @p raw_line_iterator objects operate on all lines, used or not.
+     * A @p line_iterator is typdef'd to an iterator operating on the @p lines
+     * member variable of a <tt>Triangulation<1></tt> object. An @p
+     * active_line_iterator only operates on the active lines. @p
+     * raw_line_iterator objects operate on all lines, used or not.
      *
-     *  Since we are in one dimension, the following identities are declared:
+     * Since we are in one dimension, the following identities are declared:
      *  @code
      *    typedef raw_line_iterator    raw_cell_iterator;
      *    typedef line_iterator        cell_iterator;
      *    typedef active_line_iterator active_cell_iterator;
      *  @endcode
      *
-     *  To enable the declaration of @p begin_quad and the like in
-     *  <tt>Triangulation<1></tt>, the @p quad_iterators are declared as
-     *  iterators over InvalidAccessor. Thus these types exist, but
-     *  are useless and will certainly make any involuntary use
-     *  visible. The same holds for hexahedron iterators.
+     * To enable the declaration of @p begin_quad and the like in
+     * <tt>Triangulation<1></tt>, the @p quad_iterators are declared as
+     * iterators over InvalidAccessor. Thus these types exist, but are useless
+     * and will certainly make any involuntary use visible. The same holds for
+     * hexahedron iterators.
      *
-     *  The same applies for the @p face_iterator types, since lines
-     *  have no substructures apart from vertices, which are handled in
-     *  a different way, however.
+     * The same applies for the @p face_iterator types, since lines have no
+     * substructures apart from vertices, which are handled in a different
+     * way, however.
      *
      * @author Wolfgang Bangerth, 1998
      */
@@ -87,28 +87,28 @@ namespace internal
 
 
     /**
-     *  This class implements some types which differ between the dimensions.
-     *  These are the declararions for the 2D case only. See the @ref Iterators
-     *  module for more information.
+     * This class implements some types which differ between the dimensions.
+     * These are the declararions for the 2D case only. See the @ref Iterators
+     * module for more information.
      *
-     *  A @p line_iterator is typdef'd to an iterator operating on the
-     *  @p lines member variable of a <tt>Triangulation<2></tt> object. An
-     *  @p active_line_iterator only operates on the active lines.
-     *  @p raw_line_iterator objects operate on all lines, used or not.
-     *  Using @p active_line_iterators may not be particularly in 2D useful since it
-     *  only operates on unrefined lines. However, also refined lines may bound
-     *  unrefined cells if the neighboring cell is refined once more than the
-     *  present one.
+     * A @p line_iterator is typdef'd to an iterator operating on the @p lines
+     * member variable of a <tt>Triangulation<2></tt> object. An @p
+     * active_line_iterator only operates on the active lines. @p
+     * raw_line_iterator objects operate on all lines, used or not. Using @p
+     * active_line_iterators may not be particularly in 2D useful since it
+     * only operates on unrefined lines. However, also refined lines may bound
+     * unrefined cells if the neighboring cell is refined once more than the
+     * present one.
      *
-     *  Similarly to line iterators, @p quad_iterator, @p raw_quad_iterator and
-     *  @p active_quad_iterator are declared.
+     * Similarly to line iterators, @p quad_iterator, @p raw_quad_iterator and
+     * @p active_quad_iterator are declared.
      *
-     *  To enable the declaration of @p begin_hex and the like in
-     *  <tt>Triangulation<[12]></tt>, the @p hex_iterators are declared as
-     *  iterators over InvalidAccessor. Thus these types exist, but
-     *  are useless and will certainly make any involuntary use visible.
+     * To enable the declaration of @p begin_hex and the like in
+     * <tt>Triangulation<[12]></tt>, the @p hex_iterators are declared as
+     * iterators over InvalidAccessor. Thus these types exist, but are useless
+     * and will certainly make any involuntary use visible.
      *
-     *  Since we are in two dimension, the following identities are declared:
+     * Since we are in two dimension, the following identities are declared:
      *  @code
      *    typedef raw_quad_iterator    raw_cell_iterator;
      *    typedef quad_iterator        cell_iterator;
@@ -141,13 +141,13 @@ namespace internal
 
 
     /**
-     *  This class implements some types which differ between the dimensions.
-     *  These are the declararions for the 3D case only. See the @ref Iterators
-     *  module for more information.
+     * This class implements some types which differ between the dimensions.
+     * These are the declararions for the 3D case only. See the @ref Iterators
+     * module for more information.
      *
-     *  For the declarations of the data types, more or less the same holds
-     *  as for lower dimensions (see <tt>Iterators<[12]></tt>). The
-     *  dimension specific data types are here, since we are in three dimensions:
+     * For the declarations of the data types, more or less the same holds as
+     * for lower dimensions (see <tt>Iterators<[12]></tt>). The dimension
+     * specific data types are here, since we are in three dimensions:
      *  @code
      *    typedef raw_hex_iterator    raw_cell_iterator;
      *    typedef hex_iterator        cell_iterator;
index 6e7e1db41137f68deca7071d788e50b448736c98..23a00fe22fca658e1103ab15abc31dda2043de8f 100644 (file)
@@ -40,14 +40,13 @@ namespace internal
      * (what a cell actually is is declared elsewhere), etc. See also
      * TriaObjects for non level-oriented data.
      *
-     * There is another field, which may fit in here, namely the
-     * material data (for cells) or the boundary indicators (for faces),
-     * but since we need for a line or quad either boundary information or
-     * material data, we store them with the lines and quads rather than
-     * with the common data. Likewise, in 3d, we need boundary indicators
-     * for lines and quads (we need to know how to refine a line if the
-     * two adjacent faces have different boundary indicators), and
-     * material data for cells.
+     * There is another field, which may fit in here, namely the material data
+     * (for cells) or the boundary indicators (for faces), but since we need
+     * for a line or quad either boundary information or material data, we
+     * store them with the lines and quads rather than with the common data.
+     * Likewise, in 3d, we need boundary indicators for lines and quads (we
+     * need to know how to refine a line if the two adjacent faces have
+     * different boundary indicators), and material data for cells.
      *
      * @author Wolfgang Bangerth, Guido Kanschat, 1998, 2007
      */
@@ -56,90 +55,60 @@ namespace internal
     {
     public:
       /**
-       *  @p RefinementCase<dim>::Type flags
-       *  for the cells to be
-       *  refined with or not
-       *  (RefinementCase<dim>::no_refinement). The
-       *  meaning what a cell is,
-       *  is dimension specific,
-       *  therefore also the length
-       *  of this vector depends on
-       *  the dimension: in one
-       *  dimension, the length of
-       *  this vector equals the
-       *  length of the @p lines
-       *  vector, in two dimensions
-       *  that of the @p quads
-       *  vector, etc.
+       * @p RefinementCase<dim>::Type flags for the cells to be refined with
+       * or not (RefinementCase<dim>::no_refinement). The meaning what a cell
+       * is, is dimension specific, therefore also the length of this vector
+       * depends on the dimension: in one dimension, the length of this vector
+       * equals the length of the @p lines vector, in two dimensions that of
+       * the @p quads vector, etc.
        */
       std::vector<unsigned char> refine_flags;
 
       /**
-       * Same meaning as the one above, but
-       * specifies whether a cell must be
+       * Same meaning as the one above, but specifies whether a cell must be
        * coarsened.
        */
       std::vector<bool> coarsen_flags;
 
       /**
-       *  Levels and indices of the neighbors
-       *  of the cells. Convention is, that the
-       *  neighbors of the cell with index @p i
-       *  are stored in the fields following
-       *  $i*(2*real\_space\_dimension)$, e.g. in
-       *  one spatial dimension, the neighbors
-       *  of cell 0 are stored in <tt>neighbors[0]</tt>
-       *  and <tt>neighbors[1]</tt>, the neighbors of
-       *  cell 1 are stored in <tt>neighbors[2]</tt>
-       *  and <tt>neighbors[3]</tt>, and so on.
+       * Levels and indices of the neighbors of the cells. Convention is, that
+       * the neighbors of the cell with index @p i are stored in the fields
+       * following $i*(2*real\_space\_dimension)$, e.g. in one spatial
+       * dimension, the neighbors of cell 0 are stored in
+       * <tt>neighbors[0]</tt> and <tt>neighbors[1]</tt>, the neighbors of
+       * cell 1 are stored in <tt>neighbors[2]</tt> and <tt>neighbors[3]</tt>,
+       * and so on.
        *
-       *  In neighbors, <tt>neighbors[i].first</tt> is
-       *  the level, while <tt>neighbors[i].first</tt>
-       *  is the index of the neighbor.
+       * In neighbors, <tt>neighbors[i].first</tt> is the level, while
+       * <tt>neighbors[i].first</tt> is the index of the neighbor.
        *
-       *  If a neighbor does not exist (cell is
-       *  at the boundary), <tt>level=index=-1</tt>
-       *  is set.
+       * If a neighbor does not exist (cell is at the boundary),
+       * <tt>level=index=-1</tt> is set.
        *
-       *  <em>Conventions:</em> The
-       *  @p ith neighbor of a cell is
-       *  the one which shares the
-       *  @p ith face (@p Line in 2D,
-       *  @p Quad in 3D) of this cell.
+       * <em>Conventions:</em> The @p ith neighbor of a cell is the one which
+       * shares the @p ith face (@p Line in 2D, @p Quad in 3D) of this cell.
        *
-       *  The neighbor of a cell has at most the
-       *  same level as this cell, i.e. it may
-       *  or may not be refined.
+       * The neighbor of a cell has at most the same level as this cell, i.e.
+       * it may or may not be refined.
        *
-       *  In one dimension, a neighbor may have
-       *  any level less or equal the level of
-       *  this cell. If it has the same level,
-       *  it may be refined an arbitrary number
-       *  of times, but the neighbor pointer
-       *  still points to the cell on the same
-       *  level, while the neighbors of the
-       *  childs of the neighbor may point to
-       *  this cell or its children.
+       * In one dimension, a neighbor may have any level less or equal the
+       * level of this cell. If it has the same level, it may be refined an
+       * arbitrary number of times, but the neighbor pointer still points to
+       * the cell on the same level, while the neighbors of the childs of the
+       * neighbor may point to this cell or its children.
        *
-       *  In two and more dimensions, the
-       *  neighbor is either on the same level
-       *  and refined (in which case its children
-       *  have neighbor pointers to this cell or
-       *  its direct children), unrefined on
-       *  the same level or one level down (in
-       *  which case its neighbor pointer points
-       *  to the mother cell of this cell).
+       * In two and more dimensions, the neighbor is either on the same level
+       * and refined (in which case its children have neighbor pointers to
+       * this cell or its direct children), unrefined on the same level or one
+       * level down (in which case its neighbor pointer points to the mother
+       * cell of this cell).
        */
       std::vector<std::pair<int,int> > neighbors;
 
       /**
-       * One integer per cell to store
-       * which subdomain it belongs
-       * to. This field is most often
-       * used in parallel computations,
-       * where it denotes which
-       * processor shall work on the
-       * cells with a given subdomain
+       * One integer per cell to store which subdomain it belongs to. This
+       * field is most often used in parallel computations, where it denotes
+       * which processor shall work on the cells with a given subdomain
        * number.
        */
       std::vector<types::subdomain_id> subdomain_ids;
@@ -150,9 +119,8 @@ namespace internal
       std::vector<types::subdomain_id> level_subdomain_ids;
 
       /**
-       * One integer for every consecutive
-       * pair of cells to store which
-       * index their parent has.
+       * One integer for every consecutive pair of cells to store which index
+       * their parent has.
        *
        * (We store this information once for each pair of cells since every
        * refinement, isotropic or anisotropic, and in any space dimension,
@@ -162,38 +130,29 @@ namespace internal
       std::vector<int> parents;
 
       /**
-       * One bool per cell to indicate the
-       * direction of the normal
-       * true:  use orientation from vertex
-       * false: revert the orientation. See
-       * @ref GlossDirectionFlag .
+       * One bool per cell to indicate the direction of the normal true:  use
+       * orientation from vertex false: revert the orientation. See @ref
+       * GlossDirectionFlag .
        *
-       * This is only used for
-       * codim==1 meshes.
+       * This is only used for codim==1 meshes.
        */
       std::vector<bool> direction_flags;
 
       /**
-       * The object containing the data on lines and
-       * related functions
+       * The object containing the data on lines and related functions
        */
       TriaObjects<TriaObject<dim> > cells;
 
 
       /**
-       *  Reserve enough space to accommodate
-       *  @p total_cells cells on this level.
-       *  Since there are no @p used flags on this
-       *  level, you have to give the total number
-       *  of cells, not only the number of newly
-       *  to accommodate ones, like in the
-       *  <tt>TriaLevel<N>::reserve_space</tt>
-       *  functions, with <tt>N>0</tt>.
+       * Reserve enough space to accommodate @p total_cells cells on this
+       * level. Since there are no @p used flags on this level, you have to
+       * give the total number of cells, not only the number of newly to
+       * accommodate ones, like in the <tt>TriaLevel<N>::reserve_space</tt>
+       * functions, with <tt>N>0</tt>.
        *
-       *  Since the
-       *  number of neighbors per cell depends
-       *  on the dimensions, you have to pass
-       *  that additionally.
+       * Since the number of neighbors per cell depends on the dimensions, you
+       * have to pass that additionally.
        */
 
       void reserve_space (const unsigned int total_cells,
@@ -201,32 +160,28 @@ namespace internal
                           const unsigned int space_dimension);
 
       /**
-       *  Check the memory consistency of the
-       *  different containers. Should only be
-       *  called with the prepro flag @p DEBUG
-       *  set. The function should be called from
-       *  the functions of the higher
-       *  TriaLevel classes.
+       * Check the memory consistency of the different containers. Should only
+       * be called with the prepro flag @p DEBUG set. The function should be
+       * called from the functions of the higher TriaLevel classes.
        */
       void monitor_memory (const unsigned int true_dimension) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
                      const unsigned int version);
 
       /**
-       *  Exception
+       * Exception
        */
       DeclException3 (ExcMemoryWasted,
                       char *, int, int,
@@ -234,7 +189,7 @@ namespace internal
                       << arg2 << " elements, but it`s capacity is "
                       << arg3 << ".");
       /**
-       *  Exception
+       * Exception
        */
       DeclException2 (ExcMemoryInexact,
                       int, int,
@@ -246,8 +201,8 @@ namespace internal
 
     /**
      * Specialization of TriaLevels for 3D. Since we need TriaObjectsHex
-     * instead of TriaObjects. Refer to the documentation of the template
-     * for details.
+     * instead of TriaObjects. Refer to the documentation of the template for
+     * details.
      */
     template<>
     class TriaLevel<3>
@@ -278,15 +233,15 @@ namespace internal
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
                      const unsigned int version);
 
       /**
-       *  Exception
+       * Exception
        */
       DeclException3 (ExcMemoryWasted,
                       char *, int, int,
@@ -294,7 +249,7 @@ namespace internal
                       << arg2 << " elements, but it`s capacity is "
                       << arg3 << ".");
       /**
-       *  Exception
+       * Exception
        */
       DeclException2 (ExcMemoryInexact,
                       int, int,
index 53e07294d03c2877f8359b9926a4e55bd3ff90db..c43bb485eec174372a5dd12e6585cbddb1f5e019 100644 (file)
@@ -29,10 +29,10 @@ namespace internal
   {
 
     /**
-     * Class template for the <tt>structdim</tt>-dimensional cells constituting
-     * a dealii::Triangulation of dimension <tt>structdim</tt> or lower dimensional
-     * objects of higher dimensions.  They are characterized by the
-     * (global) indices of their faces, which are cells of dimension
+     * Class template for the <tt>structdim</tt>-dimensional cells
+     * constituting a dealii::Triangulation of dimension <tt>structdim</tt> or
+     * lower dimensional objects of higher dimensions.  They are characterized
+     * by the (global) indices of their faces, which are cells of dimension
      * <tt>structdim-1</tt> or vertices if <tt>structdim=1</tt>.
      *
      * @author Guido Kanschat, 2007
@@ -44,40 +44,31 @@ namespace internal
       static const unsigned int dimension = structdim;
 
       /**
-       * Default constructor,
-       * setting all face indices
-       * to invalid values.
+       * Default constructor, setting all face indices to invalid values.
        */
       TriaObject ();
 
       /**
-       * Constructor for a line
-       * object with the numbers of
-       * its two end points.
+       * Constructor for a line object with the numbers of its two end points.
        *
-       * Throws an exception if
-       * dimension is not one.
+       * Throws an exception if dimension is not one.
        */
       TriaObject (const int i0, const int i1);
 
       /**
-       * Constructor for a quadrilateral
-       * object with the numbers of
-       * its four lines.
+       * Constructor for a quadrilateral object with the numbers of its four
+       * lines.
        *
-       * Throws an exception if
-       * dimension is not two.
+       * Throws an exception if dimension is not two.
        */
       TriaObject (const int i0, const int i1,
                   const int i2, const int i3);
 
       /**
-       * Constructor for a hexahedron
-       * object with the numbers of
-       * its six quadrilaterals.
+       * Constructor for a hexahedron object with the numbers of its six
+       * quadrilaterals.
        *
-       * Throws an exception if
-       * dimension is not two.
+       * Throws an exception if dimension is not two.
        */
       TriaObject (const int i0, const int i1,
                   const int i2, const int i3,
@@ -85,27 +76,24 @@ namespace internal
 
 
       /**
-       * Return the index of the
-       * ith face object.
+       * Return the index of the ith face object.
        */
       int face (const unsigned int i) const;
 
       /**
-       * Set the index of the ith
-       * face object.
+       * Set the index of the ith face object.
        */
       void set_face (const unsigned int i, const int index);
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       static std::size_t memory_consumption ();
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -113,11 +101,8 @@ namespace internal
 
     protected:
       /**
-       *  Global indices of the
-       *  face iterators bounding
-       *  this cell if dim@>1, and
-       *  the two vertex indices in
-       *  1d.
+       * Global indices of the face iterators bounding this cell if dim@>1,
+       * and the two vertex indices in 1d.
        */
       int faces[GeometryInfo<structdim>::faces_per_cell];
     };
index 8b377e42b4a332f77c05cd4f041805e627aeb04a..25958b3f10b5e8f398650118ec7609495843d947 100644 (file)
@@ -47,10 +47,10 @@ namespace internal
   {
 
     /**
-     * General template for information belonging to the geometrical objects of a
-     * triangulation, i.e. lines, quads, hexahedra...  Apart from the vector of
-     * objects additional information is included, namely vectors indicating the
-     * children, the used-status, user-flags, material-ids..
+     * General template for information belonging to the geometrical objects
+     * of a triangulation, i.e. lines, quads, hexahedra...  Apart from the
+     * vector of objects additional information is included, namely vectors
+     * indicating the children, the used-status, user-flags, material-ids..
      *
      * Objects of these classes are included in the TriaLevel and TriaFaces
      * classes.
@@ -68,79 +68,56 @@ namespace internal
       TriaObjects();
 
       /**
-       *  Vector of the objects belonging to
-       *  this level. The index of the object
-       *  equals the index in this container.
+       * Vector of the objects belonging to this level. The index of the
+       * object equals the index in this container.
        */
       std::vector<G> cells;
 
       /**
-       *  Index of the even children of an object.
-       *  Since when objects are refined, all
-       *  children are created at the same
-       *  time, they are appended to the list
-       *  at least in pairs after each other.
-       *  We therefore only store the index
-       *  of the even children, the uneven
-       *  follow immediately afterwards.
+       * Index of the even children of an object. Since when objects are
+       * refined, all children are created at the same time, they are appended
+       * to the list at least in pairs after each other. We therefore only
+       * store the index of the even children, the uneven follow immediately
+       * afterwards.
        *
-       *  If an object has no children, -1 is
-       *  stored in this list. An object is
-       *  called active if it has no
-       *  children. The function
-       *  TriaAccessorBase::has_children()
-       *  tests for this.
+       * If an object has no children, -1 is stored in this list. An object is
+       * called active if it has no children. The function
+       * TriaAccessorBase::has_children() tests for this.
        */
       std::vector<int>  children;
 
       /**
-       * Store the refinement
-       * case each of the
-       * cells is refined
-       * with. This vector
-       * might be replaced by
-       * vector<vector<bool> >
-       * (dim, vector<bool>
-       * (n_cells)) which is
-       * more memory efficient.
+       * Store the refinement case each of the cells is refined with. This
+       * vector might be replaced by vector<vector<bool> > (dim, vector<bool>
+       * (n_cells)) which is more memory efficient.
        */
       std::vector<RefinementCase<G::dimension> > refinement_cases;
 
       /**
-       *  Vector storing whether an object is
-       *  used in the @p cells vector.
+       * Vector storing whether an object is used in the @p cells vector.
        *
-       *  Since it is difficult to delete
-       *  elements in a @p vector, when an
-       *  element is not needed any more
-       *  (e.g. after derefinement), it is
-       *  not deleted from the list, but
-       *  rather the according @p used flag
-       *  is set to @p false.
+       * Since it is difficult to delete elements in a @p vector, when an
+       * element is not needed any more (e.g. after derefinement), it is not
+       * deleted from the list, but rather the according @p used flag is set
+       * to @p false.
        */
       std::vector<bool> used;
 
       /**
-       *  Make available a field for user data,
-       *  one bit per object. This field is usually
-       *  used when an operation runs over all
-       *  cells and needs information whether
-       *  another cell (e.g. a neighbor) has
-       *  already been processed.
+       * Make available a field for user data, one bit per object. This field
+       * is usually used when an operation runs over all cells and needs
+       * information whether another cell (e.g. a neighbor) has already been
+       * processed.
        *
-       *  You can clear all used flags using
-       *  dealii::Triangulation::clear_user_flags().
+       * You can clear all used flags using
+       * dealii::Triangulation::clear_user_flags().
        */
       std::vector<bool> user_flags;
 
 
       /**
-       * We use this union to store
-       * boundary and material
-       * data. Because only one one
-       * out of these two is
-       * actually needed here, we
-       * use an union.
+       * We use this union to store boundary and material data. Because only
+       * one one out of these two is actually needed here, we use an union.
        */
       struct BoundaryOrMaterialId
       {
@@ -157,18 +134,14 @@ namespace internal
         BoundaryOrMaterialId ();
 
         /**
-         * Return the size of objects
-         * of this kind.
+         * Return the size of objects of this kind.
          */
         static
         std::size_t memory_consumption ();
 
         /**
-         * Read or write the data
-         * of this object to or
-         * from a stream for the
-         * purpose of
-         * serialization
+         * Read or write the data of this object to or from a stream for the
+         * purpose of serialization
          */
         template <class Archive>
         void serialize(Archive &ar,
@@ -176,118 +149,73 @@ namespace internal
       };
 
       /**
-       * Store boundary and material data. For
-       * example, in one dimension, this field
-       * stores the material id of a line, which
-       * is a number between 0 and
-       * numbers::invalid_material_id-1. In more
-       * than one dimension, lines have no
-       * material id, but they may be at the
-       * boundary; then, we store the
-       * boundary indicator in this field,
-       * which denotes to which part of the
-       * boundary this line belongs and which
-       * boundary conditions hold on this
-       * part. The boundary indicator also
-       * is a number between zero and
-       * numbers::internal_face_boundary_id-1;
-       * the id numbers::internal_face_boundary_id
-       * is reserved for lines
-       * in the interior and may be used
-       * to check whether a line is at the
-       * boundary or not, which otherwise
-       * is not possible if you don't know
-       * which cell it belongs to.
+       * Store boundary and material data. For example, in one dimension, this
+       * field stores the material id of a line, which is a number between 0
+       * and numbers::invalid_material_id-1. In more than one dimension, lines
+       * have no material id, but they may be at the boundary; then, we store
+       * the boundary indicator in this field, which denotes to which part of
+       * the boundary this line belongs and which boundary conditions hold on
+       * this part. The boundary indicator also is a number between zero and
+       * numbers::internal_face_boundary_id-1; the id
+       * numbers::internal_face_boundary_id is reserved for lines in the
+       * interior and may be used to check whether a line is at the boundary
+       * or not, which otherwise is not possible if you don't know which cell
+       * it belongs to.
        */
       std::vector<BoundaryOrMaterialId> boundary_or_material_id;
 
       /**
-       * Store manifold ids. This field
-       * stores the manifold id of each object, which
-       * is a number between 0 and
-       * numbers::invalid_manifold_id-1.
+       * Store manifold ids. This field stores the manifold id of each object,
+       * which is a number between 0 and numbers::invalid_manifold_id-1.
        */
       std::vector<types::manifold_id> manifold_id;
 
       /**
-       *  Assert that enough space
-       *  is allocated to
-       *  accommodate
-       *  <code>new_objs_in_pairs</code>
-       *  new objects, stored in
-       *  pairs, plus
-       *  <code>new_obj_single</code>
-       *  stored individually.
-       *  This function does not
-       *  only call
-       *  <code>vector::reserve()</code>,
-       *  but does really append
-       *  the needed elements.
+       * Assert that enough space is allocated to accommodate
+       * <code>new_objs_in_pairs</code> new objects, stored in pairs, plus
+       * <code>new_obj_single</code> stored individually. This function does
+       * not only call <code>vector::reserve()</code>, but does really append
+       * the needed elements.
        *
-       *  In 2D e.g. refined lines have to be
-       *  stored in pairs, whereas new lines in the
-       *  interior of refined cells can be stored as
-       *  single lines.
+       * In 2D e.g. refined lines have to be stored in pairs, whereas new
+       * lines in the interior of refined cells can be stored as single lines.
        */
       void reserve_space (const unsigned int new_objs_in_pairs,
                           const unsigned int new_objs_single = 0);
 
       /**
-       * Return an iterator to the
-       * next free slot for a
-       * single object. This
-       * function is only used by
-       * dealii::Triangulation::execute_refinement()
+       * Return an iterator to the next free slot for a single object. This
+       * function is only used by dealii::Triangulation::execute_refinement()
        * in 3D.
        *
-       * @warning Interestingly,
-       * this function is not used
-       * for 1D or 2D
-       * triangulations, where it
-       * seems the authors of the
-       * refinement function insist
-       * on reimplementing its
-       * contents.
+       * @warning Interestingly, this function is not used for 1D or 2D
+       * triangulations, where it seems the authors of the refinement function
+       * insist on reimplementing its contents.
        *
-       * @todo This function is
-       * not instantiated for the
-       * codim-one case
+       * @todo This function is not instantiated for the codim-one case
        */
       template <int dim, int spacedim>
       dealii::TriaRawIterator<dealii::TriaAccessor<G::dimension,dim,spacedim> >
       next_free_single_object (const dealii::Triangulation<dim,spacedim> &tria);
 
       /**
-       * Return an iterator to the
-       * next free slot for a pair
-       * of objects. This
-       * function is only used by
-       * dealii::Triangulation::execute_refinement()
+       * Return an iterator to the next free slot for a pair of objects. This
+       * function is only used by dealii::Triangulation::execute_refinement()
        * in 3D.
        *
-       * @warning Interestingly,
-       * this function is not used
-       * for 1D or 2D
-       * triangulations, where it
-       * seems the authors of the
-       * refinement function insist
-       * on reimplementing its
-       * contents.
+       * @warning Interestingly, this function is not used for 1D or 2D
+       * triangulations, where it seems the authors of the refinement function
+       * insist on reimplementing its contents.
        *
-       * @todo This function is
-       * not instantiated for the
-       * codim-one case
+       * @todo This function is not instantiated for the codim-one case
        */
       template <int dim, int spacedim>
       dealii::TriaRawIterator<dealii::TriaAccessor<G::dimension,dim,spacedim> >
       next_free_pair_object (const dealii::Triangulation<dim,spacedim> &tria);
 
       /**
-       * Return an iterator to the
-       * next free slot for a pair
-       * of hexes. Only implemented
-       * for
-       * <code>G=Hexahedron</code>.
+       * Return an iterator to the next free slot for a pair of hexes. Only
+       * implemented for <code>G=Hexahedron</code>.
        */
       template <int dim, int spacedim>
       typename dealii::Triangulation<dim,spacedim>::raw_hex_iterator
@@ -295,37 +223,23 @@ namespace internal
                      const unsigned int               level);
 
       /**
-       *  Clear all the data contained in this object.
+       * Clear all the data contained in this object.
        */
       void clear();
 
       /**
-       * The orientation of the
-       * face number <code>face</code>
-       * of the cell with number
-       * <code>cell</code>. The return
-       * value is <code>true</code>, if
-       * the normal vector points
-       * the usual way
-       * (GeometryInfo::unit_normal_orientation)
-       * and <code>false</code> else.
+       * The orientation of the face number <code>face</code> of the cell with
+       * number <code>cell</code>. The return value is <code>true</code>, if
+       * the normal vector points the usual way
+       * (GeometryInfo::unit_normal_orientation) and <code>false</code> else.
        *
-       * The result is always
-       * <code>true</code> in this
-       * class, but derived classes
-       * will reimplement this.
+       * The result is always <code>true</code> in this class, but derived
+       * classes will reimplement this.
        *
-       * @warning There is a bug in
-       * the class hierarchy right
-       * now. Avoid ever calling
-       * this function through a
-       * reference, since you might
-       * end up with the base class
-       * function instead of the
-       * derived class. Still, we
-       * do not want to make it
-       * virtual for efficiency
-       * reasons.
+       * @warning There is a bug in the class hierarchy right now. Avoid ever
+       * calling this function through a reference, since you might end up
+       * with the base class function instead of the derived class. Still, we
+       * do not want to make it virtual for efficiency reasons.
        */
       bool face_orientation(const unsigned int cell, const unsigned int face) const;
 
@@ -356,10 +270,8 @@ namespace internal
       void clear_user_data(const unsigned int i);
 
       /**
-       * Clear all user pointers or
-       * indices and reset their
-       * type, such that the next
-       * access may be aither or.
+       * Clear all user pointers or indices and reset their type, such that
+       * the next access may be aither or.
        */
       void clear_user_data();
 
@@ -369,32 +281,28 @@ namespace internal
       void clear_user_flags();
 
       /**
-       *  Check the memory consistency of the
-       *  different containers. Should only be
-       *  called with the prepro flag @p DEBUG
-       *  set. The function should be called from
-       *  the functions of the higher
-       *  TriaLevel classes.
+       * Check the memory consistency of the different containers. Should only
+       * be called with the prepro flag @p DEBUG set. The function should be
+       * called from the functions of the higher TriaLevel classes.
        */
       void monitor_memory (const unsigned int true_dimension) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
                      const unsigned int version);
 
       /**
-       *  Exception
+       * Exception
        */
       DeclException3 (ExcMemoryWasted,
                       char *, int, int,
@@ -402,7 +310,7 @@ namespace internal
                       << arg2 << " elements, but it`s capacity is "
                       << arg3 << ".");
       /**
-       *  Exception
+       * Exception
        * @ingroup Exceptions
        */
       DeclException2 (ExcMemoryInexact,
@@ -411,7 +319,7 @@ namespace internal
                       << arg2 << ", which is not as expected.");
 
       /**
-       *  Exception
+       * Exception
        */
       DeclException2 (ExcWrongIterator,
                       char *, char *,
@@ -419,13 +327,9 @@ namespace internal
                       "but you can only ask for " << arg2 <<"_iterators.");
 
       /**
-       * dealii::Triangulation objects can
-       * either access a user
-       * pointer or a user
-       * index. What you tried to
-       * do is trying to access one
-       * of those after using the
-       * other.
+       * dealii::Triangulation objects can either access a user pointer or a
+       * user index. What you tried to do is trying to access one of those
+       * after using the other.
        *
        * @ingroup Exceptions
        */
@@ -448,8 +352,7 @@ namespace internal
       bool reverse_order_next_free_single;
 
       /**
-       * The data type storing user
-       * pointers or user indices.
+       * The data type storing user pointers or user indices.
        */
       struct UserData
       {
@@ -472,8 +375,7 @@ namespace internal
         }
 
         /**
-         * Write the data of this object
-         * to a stream for the purpose of
+         * Write the data of this object to a stream for the purpose of
          * serialization.
          */
         template <class Archive>
@@ -481,9 +383,7 @@ namespace internal
       };
 
       /**
-       * Enum descibing the
-       * possible types of
-       * userdata.
+       * Enum descibing the possible types of userdata.
        */
       enum UserDataType
       {
@@ -497,94 +397,57 @@ namespace internal
 
 
       /**
-       * Pointer which is not used by the
-       * library but may be accessed and set
-       * by the user to handle data local to
-       * a line/quad/etc.
+       * Pointer which is not used by the library but may be accessed and set
+       * by the user to handle data local to a line/quad/etc.
        */
       std::vector<UserData> user_data;
 
       /**
-       * In order to avoid
-       * confusion between user
-       * pointers and indices, this
-       * enum is set by the first
-       * function accessing either
-       * and subsequent access will
-       * not be allowed to change
-       * the type of data accessed.
+       * In order to avoid confusion between user pointers and indices, this
+       * enum is set by the first function accessing either and subsequent
+       * access will not be allowed to change the type of data accessed.
        */
       mutable UserDataType user_data_type;
     };
 
     /**
-     * For hexahedra the data of TriaObjects needs to be extended, as we can obtain faces
-     * (quads) in non-standard-orientation, therefore we declare a class TriaObjectsHex, which
-     * additionally contains a bool-vector of the face-orientations.
+     * For hexahedra the data of TriaObjects needs to be extended, as we can
+     * obtain faces (quads) in non-standard-orientation, therefore we declare
+     * a class TriaObjectsHex, which additionally contains a bool-vector of
+     * the face-orientations.
      */
     class TriaObjectsHex : public TriaObjects<TriaObject<3> >
     {
     public:
       /**
-       * The orientation of the
-       * face number <code>face</code>
-       * of the cell with number
-       * <code>cell</code>. The return
-       * value is <code>true</code>, if
-       * the normal vector points
-       * the usual way
-       * (GeometryInfo::unit_normal_orientation)
-       * and <code>false</code> if they
-       * point in opposite
-       * direction.
+       * The orientation of the face number <code>face</code> of the cell with
+       * number <code>cell</code>. The return value is <code>true</code>, if
+       * the normal vector points the usual way
+       * (GeometryInfo::unit_normal_orientation) and <code>false</code> if
+       * they point in opposite direction.
        */
       bool face_orientation(const unsigned int cell, const unsigned int face) const;
 
 
       /**
-       * For edges, we enforce a
-       * standard convention that
-       * opposite edges should be
-       * parallel. Now, that's
-       * enforcable in most cases,
-       * and we have code that
-       * makes sure that if a mesh
-       * allows this to happen,
-       * that we have this
-       * convention. We also know
-       * that it is always possible
-       * to have opposite faces
-       * have parallel normal
-       * vectors. (For both things,
-       * see the Agelek, Anderson,
-       * Bangerth, Barth paper
-       * mentioned in the
+       * For edges, we enforce a standard convention that opposite edges
+       * should be parallel. Now, that's enforcable in most cases, and we have
+       * code that makes sure that if a mesh allows this to happen, that we
+       * have this convention. We also know that it is always possible to have
+       * opposite faces have parallel normal vectors. (For both things, see
+       * the Agelek, Anderson, Bangerth, Barth paper mentioned in the
        * publications list.)
        *
-       * The problem is that we
-       * originally had another
-       * condition, namely that
-       * faces 0, 2 and 6 have
-       * normals that point into
-       * the cell, while the other
-       * faces have normals that
-       * point outward. It turns
-       * out that this is not
-       * always possible. In
-       * effect, we have to store
-       * whether the normal vector
-       * of each face of each cell
-       * follows this convention or
-       * not. If this is so, then
-       * this variable stores a
-       * @p true value, otherwise
-       * a @p false value.
+       * The problem is that we originally had another condition, namely that
+       * faces 0, 2 and 6 have normals that point into the cell, while the
+       * other faces have normals that point outward. It turns out that this
+       * is not always possible. In effect, we have to store whether the
+       * normal vector of each face of each cell follows this convention or
+       * not. If this is so, then this variable stores a @p true value,
+       * otherwise a @p false value.
        *
-       * In effect, this field has
-       * <code>6*n_cells</code> elements,
-       * being the number of cells
-       * times the six faces each
-       * has.
+       * In effect, this field has <code>6*n_cells</code> elements, being the
+       * number of cells times the six faces each has.
        */
       std::vector<bool> face_orientations;
 
@@ -599,41 +462,34 @@ namespace internal
       std::vector<bool> face_rotations;
 
       /**
-       *  Assert that enough space is
-       *  allocated to accommodate
-       *  <code>new_objs</code> new objects.
-       *  This function does not only call
-       *  <code>vector::reserve()</code>, but
-       *  does really append the needed
-       *  elements.
+       * Assert that enough space is allocated to accommodate
+       * <code>new_objs</code> new objects. This function does not only call
+       * <code>vector::reserve()</code>, but does really append the needed
+       * elements.
        */
       void reserve_space (const unsigned int new_objs);
 
       /**
-       *  Clear all the data contained in this object.
+       * Clear all the data contained in this object.
        */
       void clear();
 
       /**
-       *  Check the memory consistency of the
-       *  different containers. Should only be
-       *  called with the prepro flag @p DEBUG
-       *  set. The function should be called from
-       *  the functions of the higher
-       *  TriaLevel classes.
+       * Check the memory consistency of the different containers. Should only
+       * be called with the prepro flag @p DEBUG set. The function should be
+       * called from the functions of the higher TriaLevel classes.
        */
       void monitor_memory (const unsigned int true_dimension) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
@@ -642,82 +498,61 @@ namespace internal
 
 
     /**
-     * For quadrilaterals in 3D the data of TriaObjects needs to be extended, as we
-     * can obtain faces (quads) with lines in non-standard-orientation, therefore we
-     * declare a class TriaObjectsQuad3D, which additionally contains a bool-vector
-     * of the line-orientations.
+     * For quadrilaterals in 3D the data of TriaObjects needs to be extended,
+     * as we can obtain faces (quads) with lines in non-standard-orientation,
+     * therefore we declare a class TriaObjectsQuad3D, which additionally
+     * contains a bool-vector of the line-orientations.
      */
     class TriaObjectsQuad3D: public TriaObjects<TriaObject<2> >
     {
     public:
       /**
-       * The orientation of the
-       * face number <code>face</code>
-       * of the cell with number
-       * <code>cell</code>. The return
-       * value is <code>true</code>, if
-       * the normal vector points
-       * the usual way
-       * (GeometryInfo::unit_normal_orientation)
-       * and <code>false</code> if they
-       * point in opposite
-       * direction.
+       * The orientation of the face number <code>face</code> of the cell with
+       * number <code>cell</code>. The return value is <code>true</code>, if
+       * the normal vector points the usual way
+       * (GeometryInfo::unit_normal_orientation) and <code>false</code> if
+       * they point in opposite direction.
        */
       bool face_orientation(const unsigned int cell, const unsigned int face) const;
 
 
       /**
-       * In effect, this field has
-       * <code>4*n_quads</code> elements,
-       * being the number of quads
-       * times the four lines each
-       * has.
+       * In effect, this field has <code>4*n_quads</code> elements, being the
+       * number of quads times the four lines each has.
        */
       std::vector<bool> line_orientations;
 
       /**
-       *  Assert that enough space
-       *  is allocated to
-       *  accommodate
-       *  <code>new_quads_in_pairs</code>
-       *  new quads, stored in
-       *  pairs, plus
-       *  <code>new_quads_single</code>
-       *  stored individually.
-       *  This function does not
-       *  only call
-       *  <code>vector::reserve()</code>,
-       *  but does really append
-       *  the needed elements.
+       * Assert that enough space is allocated to accommodate
+       * <code>new_quads_in_pairs</code> new quads, stored in pairs, plus
+       * <code>new_quads_single</code> stored individually. This function does
+       * not only call <code>vector::reserve()</code>, but does really append
+       * the needed elements.
        */
       void reserve_space (const unsigned int new_quads_in_pairs,
                           const unsigned int new_quads_single = 0);
 
       /**
-       *  Clear all the data contained in this object.
+       * Clear all the data contained in this object.
        */
       void clear();
 
       /**
-       *  Check the memory consistency of the
-       *  different containers. Should only be
-       *  called with the prepro flag @p DEBUG
-       *  set. The function should be called from
-       *  the functions of the higher
-       *  TriaLevel classes.
+       * Check the memory consistency of the different containers. Should only
+       * be called with the prepro flag @p DEBUG set. The function should be
+       * called from the functions of the higher TriaLevel classes.
        */
       void monitor_memory (const unsigned int true_dimension) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
       /**
-       * Read or write the data of this object to or
-       * from a stream for the purpose of serialization
+       * Read or write the data of this object to or from a stream for the
+       * purpose of serialization
        */
       template <class Archive>
       void serialize(Archive &ar,
index eb393894d36f5a436ef0996d7e00ff0b545c7713..ec43c576bb18d347a08fa7ef08d74c65aab39a30 100644 (file)
@@ -37,63 +37,61 @@ namespace internal
   {
     /**
      * Store the indices of the degrees of freedom which are located on
-     * objects of dimension @p structdim < dim, i.e., for faces or edges
-     * of cells. This is opposed to the internal::hp::DoFLevels class
-     * that stores the DoF indices on cells.
+     * objects of dimension @p structdim < dim, i.e., for faces or edges of
+     * cells. This is opposed to the internal::hp::DoFLevels class that stores
+     * the DoF indices on cells.
      *
      * The things we store here is very similar to what is stored in the
      * internal::DoFHandler::DoFObjects classes (see there for more
-     * information, in particular on the layout of the class hierarchy,
-     * and the use of file names).
+     * information, in particular on the layout of the class hierarchy, and
+     * the use of file names).
      *
      * <h4>Offset computations</h4>
      *
-     * For hp methods, not all cells may use the same finite element, and
-     * it is consequently more complicated to determine where the DoF
-     * indices for a given line, quad, or hex are stored. As described in
-     * the documentation of the internal::DoFHandler::DoFLevel class, we
-     * can compute the location of the first line DoF, for example, by
-     * calculating the offset as <code>line_index *
-     * dof_handler.get_fe().dofs_per_line</code>. This of course doesn't
-     * work any more if different lines may have different numbers of
-     * degrees of freedom associated with them. Consequently, rather than
-     * using this simple multiplication, the dofs array has an associated
-     * array dof_offsets. The data corresponding to a
-     * line then starts at index <code>line_dof_offsets[line_index]</code>
-     * within the <code>line_dofs</code> array.
+     * For hp methods, not all cells may use the same finite element, and it
+     * is consequently more complicated to determine where the DoF indices for
+     * a given line, quad, or hex are stored. As described in the
+     * documentation of the internal::DoFHandler::DoFLevel class, we can
+     * compute the location of the first line DoF, for example, by calculating
+     * the offset as <code>line_index *
+     * dof_handler.get_fe().dofs_per_line</code>. This of course doesn't work
+     * any more if different lines may have different numbers of degrees of
+     * freedom associated with them. Consequently, rather than using this
+     * simple multiplication, the dofs array has an associated array
+     * dof_offsets. The data corresponding to a line then starts at index
+     * <code>line_dof_offsets[line_index]</code> within the
+     * <code>line_dofs</code> array.
      *
      *
      * <h4>Multiple data sets per object</h4>
      *
-     * If two adjacent cells use different finite elements, then
-     * the face that they share needs to store DoF indices for both
-     * involved finite elements. While faces therefore have to have at
-     * most two sets of DoF indices, it is easy to see that edges and
-     * vertices can have as many sets of DoF indices associated with them
-     * as there are adjacent cells.
+     * If two adjacent cells use different finite elements, then the face that
+     * they share needs to store DoF indices for both involved finite
+     * elements. While faces therefore have to have at most two sets of DoF
+     * indices, it is easy to see that edges and vertices can have as many
+     * sets of DoF indices associated with them as there are adjacent cells.
      *
-     * Consequently, for objects that have a lower dimensionality than
-     * cells, we have to store a map from the finite element index to the
-     * set of DoF indices associated. Since real sets are typically very
-     * inefficient to store, and since most of the time we expect the
-     * number of individual keys to be small (frequently, adjacent cells
-     * will have the same finite element, and only a single entry will
-     * exist in the map), what we do is instead to store a linked list. In
-     * this format, the first entry starting at position
-     * <code>lines.dofs[lines.dof_offsets[line_index]]</code> will denote
-     * the finite element index of the set of DoF indices following; after
-     * this set, we will store the finite element index of the second set
-     * followed by the corresponding DoF indices; and so on. Finally, when
-     * all finite element indices adjacent to this object have been
-     * covered, we write a -1 to indicate the end of the list.
+     * Consequently, for objects that have a lower dimensionality than cells,
+     * we have to store a map from the finite element index to the set of DoF
+     * indices associated. Since real sets are typically very inefficient to
+     * store, and since most of the time we expect the number of individual
+     * keys to be small (frequently, adjacent cells will have the same finite
+     * element, and only a single entry will exist in the map), what we do is
+     * instead to store a linked list. In this format, the first entry
+     * starting at position
+     * <code>lines.dofs[lines.dof_offsets[line_index]]</code> will denote the
+     * finite element index of the set of DoF indices following; after this
+     * set, we will store the finite element index of the second set followed
+     * by the corresponding DoF indices; and so on. Finally, when all finite
+     * element indices adjacent to this object have been covered, we write a
+     * -1 to indicate the end of the list.
      *
-     * Access to this kind of data, as well as the distinction between
-     * cells and objects of lower dimensionality are encoded in the
-     * accessor functions, DoFObjects::set_dof_index() and
-     * DoFLevel::get_dof_index(). They are able to traverse this
-     * list and pick out or set a DoF index given the finite element index
-     * and its location within the set of DoFs corresponding to this
-     * finite element.
+     * Access to this kind of data, as well as the distinction between cells
+     * and objects of lower dimensionality are encoded in the accessor
+     * functions, DoFObjects::set_dof_index() and DoFLevel::get_dof_index().
+     * They are able to traverse this list and pick out or set a DoF index
+     * given the finite element index and its location within the set of DoFs
+     * corresponding to this finite element.
      *
      *
      * @ingroup hp
@@ -104,45 +102,30 @@ namespace internal
     {
     public:
       /**
-       * Store the start index for
-       * the degrees of freedom of each
-       * object in the @p dofs array.
+       * Store the start index for the degrees of freedom of each object in
+       * the @p dofs array.
        *
-       * The type we store is then obviously the type the @p dofs array
-       * uses for indexing.
+       * The type we store is then obviously the type the @p dofs array uses
+       * for indexing.
        */
       std::vector<unsigned int> dof_offsets;
 
       /**
-       * Store the global indices of
-       * the degrees of freedom. See
-       * DoFLevel() for detailed
-       * information.
+       * Store the global indices of the degrees of freedom. See DoFLevel()
+       * for detailed information.
        */
       std::vector<types::global_dof_index> dofs;
 
       /**
-       * Set the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index to the value
-       * given by @p global_index. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Set the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index to the value given by
+       * @p global_index. The @p dof_handler argument is used to access the
+       * finite element that is to be used to compute the location where this
+       * data is stored.
        *
-       * The third argument, @p
-       * fe_index, denotes which of
-       * the finite elements
-       * associated with this
-       * object we shall
-       * access. Refer to the
-       * general documentation of
-       * the internal::hp::DoFLevel
-       * class template for more
+       * The third argument, @p fe_index, denotes which of the finite elements
+       * associated with this object we shall access. Refer to the general
+       * documentation of the internal::hp::DoFLevel class template for more
        * information.
        */
       template <int dim, int spacedim>
@@ -155,26 +138,14 @@ namespace internal
                      const unsigned int               obj_level);
 
       /**
-       * Return the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Return the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index. The @p dof_handler
+       * argument is used to access the finite element that is to be used to
+       * compute the location where this data is stored.
        *
-       * The third argument, @p
-       * fe_index, denotes which of
-       * the finite elements
-       * associated with this
-       * object we shall
-       * access. Refer to the
-       * general documentation of
-       * the internal::hp::DoFLevel
-       * class template for more
+       * The third argument, @p fe_index, denotes which of the finite elements
+       * associated with this object we shall access. Refer to the general
+       * documentation of the internal::hp::DoFLevel class template for more
        * information.
        */
       template <int dim, int spacedim>
@@ -186,27 +157,15 @@ namespace internal
                      const unsigned int               obj_level) const;
 
       /**
-       * Return the number of
-       * finite elements that are
-       * active on a given
-       * object. If this is a cell,
-       * the answer is of course
-       * one. If it is a face, the
-       * answer may be one or two,
-       * depending on whether the
-       * two adjacent cells use the
-       * same finite element or
-       * not. If it is an edge in
-       * 3d, the possible return
-       * value may be one or any
-       * other value larger than
-       * that.
+       * Return the number of finite elements that are active on a given
+       * object. If this is a cell, the answer is of course one. If it is a
+       * face, the answer may be one or two, depending on whether the two
+       * adjacent cells use the same finite element or not. If it is an edge
+       * in 3d, the possible return value may be one or any other value larger
+       * than that.
        *
-       * If the object is not part
-       * of an active cell, then no
-       * degrees of freedom have
-       * been distributed and zero
-       * is returned.
+       * If the object is not part of an active cell, then no degrees of
+       * freedom have been distributed and zero is returned.
        */
       template <int dim, int spacedim>
       unsigned int
@@ -214,9 +173,7 @@ namespace internal
                            const unsigned int               obj_index) const;
 
       /**
-       * Return the fe_index of the
-       * n-th active finite element
-       * on this object.
+       * Return the fe_index of the n-th active finite element on this object.
        */
       template <int dim, int spacedim>
       types::global_dof_index
@@ -226,9 +183,7 @@ namespace internal
                            const unsigned int               n) const;
 
       /**
-       * Check whether a given
-       * finite element index is
-       * used on the present
+       * Check whether a given finite element index is used on the present
        * object or not.
        */
       template <int dim, int spacedim>
@@ -239,9 +194,8 @@ namespace internal
                           const unsigned int               obj_level) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
     };
@@ -249,25 +203,28 @@ namespace internal
 
 
     /**
-     * These classes are similar to the internal::hp::DoFLevel classes. We here store
-     * information that is associated with faces, rather than cells, as this information is
-     * independent of the hierarchical structure of cells, which are organized in levels. In 2D
-     * we store information on degrees of freedom located on lines whereas in 3D we store
-     * information on drefrees of freedom located on quads and lines. In 1D we do nothing, as
-     * the faces of lines are vertices which are treated separately.
+     * These classes are similar to the internal::hp::DoFLevel classes. We
+     * here store information that is associated with faces, rather than
+     * cells, as this information is independent of the hierarchical structure
+     * of cells, which are organized in levels. In 2D we store information on
+     * degrees of freedom located on lines whereas in 3D we store information
+     * on drefrees of freedom located on quads and lines. In 1D we do nothing,
+     * as the faces of lines are vertices which are treated separately.
      *
-     * Apart from the internal::hp::DoFObjects object containing the data to store
-     * (degree of freedom indices) and all the access-functionality to this data, we do not
-     * store any data or provide any functionality. However, we do implement a function to
-     * determine an estimate of the memory consumption of the contained
-     * internal::hp::DoFObjects object(s).
+     * Apart from the internal::hp::DoFObjects object containing the data to
+     * store (degree of freedom indices) and all the access-functionality to
+     * this data, we do not store any data or provide any functionality.
+     * However, we do implement a function to determine an estimate of the
+     * memory consumption of the contained internal::hp::DoFObjects object(s).
      *
-     * The data contained isn't usually directly accessed. Rather, except for some access from
-     * the DoFHandler class, access is usually through the DoFAccessor::set_dof_index() and
-     * DoFAccessor::dof_index() functions or similar functions of derived classes that in turn
-     * access the member variables using the DoFHandler::get_dof_index() and corresponding
-     * setter functions. Knowledge of the actual data format is therefore encapsulated to the
-     * present hierarchy of classes as well as the ::DoFHandler class.
+     * The data contained isn't usually directly accessed. Rather, except for
+     * some access from the DoFHandler class, access is usually through the
+     * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+     * similar functions of derived classes that in turn access the member
+     * variables using the DoFHandler::get_dof_index() and corresponding
+     * setter functions. Knowledge of the actual data format is therefore
+     * encapsulated to the present hierarchy of classes as well as the
+     * ::DoFHandler class.
      *
      * @ingroup dofs
      * @author Tobias Leicht, 2006
@@ -277,8 +234,8 @@ namespace internal
 
 
     /**
-     * Store the indices of degrees of freedom on faces in 1D. As these would be vertices, which
-     * are treated separately, don't do anything.
+     * Store the indices of degrees of freedom on faces in 1D. As these would
+     * be vertices, which are treated separately, don't do anything.
      *
      * @ingroup hp
      * @author Tobias Leicht, 2006
@@ -288,15 +245,15 @@ namespace internal
     {
     public:
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
     };
 
     /**
-     * Store the indices of degrees of freedom on faces in 2D, which are lines.
+     * Store the indices of degrees of freedom on faces in 2D, which are
+     * lines.
      *
      * @ingroup hp
      * @author Tobias Leicht, 2006
@@ -311,9 +268,8 @@ namespace internal
       internal::hp::DoFIndicesOnFacesOrEdges<1> lines;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
     };
@@ -340,9 +296,8 @@ namespace internal
       internal::hp::DoFIndicesOnFacesOrEdges<2> quads;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
     };
index 5bc7ada7b52692d0d7517ca8c80db571ded70d41..11097485d80dab04a6df4605d792b42bac6063df 100644 (file)
@@ -68,48 +68,45 @@ namespace hp
 {
 
   /**
-   * Manage the distribution and numbering of the degrees of freedom for
-   * hp-FEM algorithms. This class satisfies the requirements outlined in
-   * @ref GlossMeshAsAContainer "Meshes as containers".
+   * Manage the distribution and numbering of the degrees of freedom for hp-
+   * FEM algorithms. This class satisfies the requirements outlined in @ref
+   * GlossMeshAsAContainer "Meshes as containers".
    *
-   * The purpose of this class is to allow for an enumeration of degrees
-   * of freedom in the same way as the ::DoFHandler class, but it allows
-   * to use a different finite element on every cell. To this end, one
-   * assigns an <code>active_fe_index</code> to every cell that indicates which
-   * element within a collection of finite elements (represented by an object
-   * of type hp::FECollection) is the one that lives on this cell.
-   * The class then enumerates the degree of freedom associated with these
-   * finite elements on each cell of a triangulation and, if possible,
-   * identifies degrees of freedom at the interfaces of cells if they
-   * match. If neighboring cells have degrees of freedom along the common
-   * interface that do not immediate match (for example, if you have
-   * $Q_2$ and $Q_3$ elements meeting at a common face), then one needs
-   * to compute constraints to ensure that the resulting finite element
-   * space on the mesh remains conforming.
+   * The purpose of this class is to allow for an enumeration of degrees of
+   * freedom in the same way as the ::DoFHandler class, but it allows to use a
+   * different finite element on every cell. To this end, one assigns an
+   * <code>active_fe_index</code> to every cell that indicates which element
+   * within a collection of finite elements (represented by an object of type
+   * hp::FECollection) is the one that lives on this cell. The class then
+   * enumerates the degree of freedom associated with these finite elements on
+   * each cell of a triangulation and, if possible, identifies degrees of
+   * freedom at the interfaces of cells if they match. If neighboring cells
+   * have degrees of freedom along the common interface that do not immediate
+   * match (for example, if you have $Q_2$ and $Q_3$ elements meeting at a
+   * common face), then one needs to compute constraints to ensure that the
+   * resulting finite element space on the mesh remains conforming.
    *
    * The whole process of working with objects of this type is explained in
-   * step-27. Many of the algorithms this class implements are described
-   * in the @ref hp_paper "hp paper".
+   * step-27. Many of the algorithms this class implements are described in
+   * the @ref hp_paper "hp paper".
    *
    *
    * <h3>Active FE indices and their behavior under mesh refinement</h3>
    *
-   * The typical workflow for using this class is to create a mesh,
-   * assign an active FE index to every active cell, calls
-   * hp::DoFHandler::distribute_dofs(), and then assemble a linear
-   * system and solve a problem on this finite element space. However,
-   * one can skip assigning active FE indices upon mesh refinement
-   * in certain circumstances. In particular, the following rules apply:
-   * - Upon mesh refinement, child cells inherit the active FE index
-   *   of the parent.
-   * - On the other hand, when coarsening cells, the (now active) parent
-   *   cell will not have an active FE index set and you will have to
-   *   set it explicitly before calling hp::DoFHandler::distribute_dofs().
-   *   In particular, to avoid stale information to be used by accident,
-   *   this class deletes the active FE index of cells that are
-   *   refined after inheriting this index to the children; this implies
-   *   that if the children are coarsened away, the old value is no
-   *   longer available on the parent cell.
+   * The typical workflow for using this class is to create a mesh, assign an
+   * active FE index to every active cell, calls
+   * hp::DoFHandler::distribute_dofs(), and then assemble a linear system and
+   * solve a problem on this finite element space. However, one can skip
+   * assigning active FE indices upon mesh refinement in certain
+   * circumstances. In particular, the following rules apply: - Upon mesh
+   * refinement, child cells inherit the active FE index of the parent. - On
+   * the other hand, when coarsening cells, the (now active) parent cell will
+   * not have an active FE index set and you will have to set it explicitly
+   * before calling hp::DoFHandler::distribute_dofs(). In particular, to avoid
+   * stale information to be used by accident, this class deletes the active
+   * FE index of cells that are refined after inheriting this index to the
+   * children; this implies that if the children are coarsened away, the old
+   * value is no longer available on the parent cell.
    *
    * @ingroup dofs
    * @ingroup hp
@@ -135,23 +132,21 @@ namespace hp
     typedef typename ActiveSelector::active_hex_iterator  active_hex_iterator;
 
     /**
-     * A typedef that is used to to identify
-     * @ref GlossActive "active cell iterators". The
-     * concept of iterators is discussed at length in the
-     * @ref Iterators "iterators documentation module".
+     * A typedef that is used to to identify @ref GlossActive "active cell
+     * iterators". The concept of iterators is discussed at length in the @ref
+     * Iterators "iterators documentation module".
      *
      * The current typedef identifies active cells in a hp::DoFHandler object.
      * While the actual data type of the typedef is hidden behind a few layers
      * of (unfortunately necessary) indirections, it is in essence
-     * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator
-     * class works like a pointer to active objects that when you
-     * dereference it yields an object of type DoFCellAccessor.
-     * DoFCellAccessor is a class that identifies properties that
-     * are specific to cells in a DoFHandler, but it is derived
-     * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
-     * and TriaAccessor that describe
-     * what you can ask of more general objects (lines, faces, as
-     * well as cells) in a triangulation and hp::DoFHandler objects.
+     * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class works
+     * like a pointer to active objects that when you dereference it yields an
+     * object of type DoFCellAccessor. DoFCellAccessor is a class that
+     * identifies properties that are specific to cells in a DoFHandler, but
+     * it is derived (and consequently inherits) from both DoFAccessor,
+     * TriaCellAccessor and TriaAccessor that describe what you can ask of
+     * more general objects (lines, faces, as well as cells) in a
+     * triangulation and hp::DoFHandler objects.
      *
      * @ingroup Iterators
      */
@@ -160,28 +155,27 @@ namespace hp
     typedef typename LevelSelector::cell_iterator         level_cell_iterator;
 
     /**
-     * A typedef that is used to to identify cell iterators. The
-     * concept of iterators is discussed at length in the
-     * @ref Iterators "iterators documentation module".
+     * A typedef that is used to to identify cell iterators. The concept of
+     * iterators is discussed at length in the @ref Iterators "iterators
+     * documentation module".
      *
-     * The current typedef identifies cells in a DoFHandler object. Some
-     * of these cells may in fact be active (see @ref GlossActive "active cell iterators")
-     * in which case they can in fact be asked for the degrees of freedom
-     * that live on them. On the other hand, if the cell is not active,
-     * any such query will result in an error. Note that this is what distinguishes
-     * this typedef from the level_cell_iterator typedef.
+     * The current typedef identifies cells in a DoFHandler object. Some of
+     * these cells may in fact be active (see @ref GlossActive "active cell
+     * iterators") in which case they can in fact be asked for the degrees of
+     * freedom that live on them. On the other hand, if the cell is not
+     * active, any such query will result in an error. Note that this is what
+     * distinguishes this typedef from the level_cell_iterator typedef.
      *
      * While the actual data type of the typedef is hidden behind a few layers
      * of (unfortunately necessary) indirections, it is in essence
-     * TriaIterator<DoFCellAccessor>. The TriaIterator
-     * class works like a pointer to objects that when you
-     * dereference it yields an object of type DoFCellAccessor.
-     * DoFCellAccessor is a class that identifies properties that
-     * are specific to cells in a DoFHandler, but it is derived
-     * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
-     * and TriaAccessor that describe
-     * what you can ask of more general objects (lines, faces, as
-     * well as cells) in a triangulation and DoFHandler objects.
+     * TriaIterator<DoFCellAccessor>. The TriaIterator class works like a
+     * pointer to objects that when you dereference it yields an object of
+     * type DoFCellAccessor. DoFCellAccessor is a class that identifies
+     * properties that are specific to cells in a DoFHandler, but it is
+     * derived (and consequently inherits) from both DoFAccessor,
+     * TriaCellAccessor and TriaAccessor that describe what you can ask of
+     * more general objects (lines, faces, as well as cells) in a
+     * triangulation and DoFHandler objects.
      *
      * @ingroup Iterators
      */
@@ -196,68 +190,46 @@ namespace hp
     typedef typename LevelSelector::face_iterator         level_face_iterator;
 
     /**
-     * Alias the @p FunctionMap type
-     * declared elsewhere.
+     * Alias the @p FunctionMap type declared elsewhere.
      */
     typedef typename FunctionMap<spacedim>::type FunctionMap;
 
     /**
-     * Make the dimension available
-     * in function templates.
+     * Make the dimension available in function templates.
      */
     static const unsigned int dimension = dim;
 
     /**
-     * Make the space dimension available
-     * in function templates.
+     * Make the space dimension available in function templates.
      */
     static const unsigned int space_dimension = spacedim;
 
     /**
-     * When the arrays holding the
-     * DoF indices are set up, but
-     * before they are filled with
-     * actual values, they are set to
-     * an invalid value, in order to
-     * monitor possible
-     * problems. This invalid value
-     * is the constant defined here.
+     * When the arrays holding the DoF indices are set up, but before they are
+     * filled with actual values, they are set to an invalid value, in order
+     * to monitor possible problems. This invalid value is the constant
+     * defined here.
      *
-     * Please note that you should
-     * not rely on it having a
-     * certain value, but rather take
-     * its symbolic name.
+     * Please note that you should not rely on it having a certain value, but
+     * rather take its symbolic name.
      */
     static const types::global_dof_index invalid_dof_index = numbers::invalid_dof_index;
 
     /**
-     * The default index of the
-     * finite element to be used on
-     * a given cell. For the usual,
-     * non-hp dealii::DoFHandler class
-     * that only supports the same
-     * finite element to be used on
-     * all cells, the index of the
-     * finite element needs to be
-     * the same on all cells
-     * anyway, and by convention we
-     * pick zero for this
-     * value. The situation here is
-     * different, since the hp
-     * classes support the case
-     * where different finite
-     * element indices may be used
-     * on different cells. The
-     * default index consequently
-     * corresponds to an invalid
-     * value.
+     * The default index of the finite element to be used on a given cell. For
+     * the usual, non-hp dealii::DoFHandler class that only supports the same
+     * finite element to be used on all cells, the index of the finite element
+     * needs to be the same on all cells anyway, and by convention we pick
+     * zero for this value. The situation here is different, since the hp
+     * classes support the case where different finite element indices may be
+     * used on different cells. The default index consequently corresponds to
+     * an invalid value.
      */
     static const unsigned int default_fe_index = numbers::invalid_unsigned_int;
 
 
     /**
-     * Constructor. Take @p tria as the
-     * triangulation to work on.
+     * Constructor. Take @p tria as the triangulation to work on.
      */
     DoFHandler (const Triangulation<dim,spacedim> &tria);
 
@@ -267,122 +239,90 @@ namespace hp
     virtual ~DoFHandler ();
 
     /**
-     * Go through the triangulation and "distribute" the degrees of
-     * freedoms needed for the given finite element. "Distributing"
-     * degrees of freedom involved allocating memory to store the
-     * information that describes it (e.g., whether it is located on a
-     * vertex, edge, face, etc) and to sequentially enumerate all
-     * degrees of freedom. In other words, while the mesh and the finite
-     * element object by themselves simply define a finite element space
-     * $V_h$, the process of distributing degrees of freedom makes sure
-     * that there is a basis for this space and that the shape functions
-     * of this basis are enumerated in an indexable, predictable way.
+     * Go through the triangulation and "distribute" the degrees of freedoms
+     * needed for the given finite element. "Distributing" degrees of freedom
+     * involved allocating memory to store the information that describes it
+     * (e.g., whether it is located on a vertex, edge, face, etc) and to
+     * sequentially enumerate all degrees of freedom. In other words, while
+     * the mesh and the finite element object by themselves simply define a
+     * finite element space $V_h$, the process of distributing degrees of
+     * freedom makes sure that there is a basis for this space and that the
+     * shape functions of this basis are enumerated in an indexable,
+     * predictable way.
      *
-     * The purpose of this function
-     * is first discussed in the introduction
-     * to the step-2 tutorial program.
+     * The purpose of this function is first discussed in the introduction to
+     * the step-2 tutorial program.
      *
-     * @note A pointer of the finite element given as argument is
-     * stored. Therefore, the lifetime of the finite element object
-     * shall be longer than that of this object. If you don't want this
-     * behavior, you may want to call the @p clear member function which
-     * also releases the lock of this object to the finite element.
+     * @note A pointer of the finite element given as argument is stored.
+     * Therefore, the lifetime of the finite element object shall be longer
+     * than that of this object. If you don't want this behavior, you may want
+     * to call the @p clear member function which also releases the lock of
+     * this object to the finite element.
      */
     virtual void distribute_dofs (const hp::FECollection<dim,spacedim> &fe);
 
     /**
-     * Go through the triangulation and set
-     * the active FE indices of all active
-     * cells to the values given in @p
-     * active_fe_indices.
+     * Go through the triangulation and set the active FE indices of all
+     * active cells to the values given in @p active_fe_indices.
      */
     void set_active_fe_indices (const std::vector<unsigned int> &active_fe_indices);
 
     /**
-     * Go through the triangulation and
-     * store the active FE indices of all
-     * active cells to the vector @p
-     * active_fe_indices. This vector is
+     * Go through the triangulation and store the active FE indices of all
+     * active cells to the vector @p active_fe_indices. This vector is
      * resized, if necessary.
      */
     void get_active_fe_indices (std::vector<unsigned int> &active_fe_indices) const;
 
     /**
-     * Clear all data of this object and
-     * especially delete the lock this object
-     * has to the finite element used the last
-     * time when @p distribute_dofs was called.
+     * Clear all data of this object and especially delete the lock this
+     * object has to the finite element used the last time when @p
+     * distribute_dofs was called.
      */
     virtual void clear ();
 
     /**
-     * Renumber degrees of freedom based on
-     * a list of new dof numbers for all the
-     * dofs.
+     * Renumber degrees of freedom based on a list of new dof numbers for all
+     * the dofs.
      *
-     * @p new_numbers is an array of integers
-     * with size equal to the number of dofs
-     * on the present grid. It stores the new
-     * indices after renumbering in the
-     * order of the old indices.
+     * @p new_numbers is an array of integers with size equal to the number of
+     * dofs on the present grid. It stores the new indices after renumbering
+     * in the order of the old indices.
      *
-     * This function is called by
-     * the functions in
-     * DoFRenumbering function
-     * after computing the ordering
-     * of the degrees of freedom.
-     * However, you can call this
-     * function yourself, which is
-     * necessary if a user wants to
-     * implement an ordering scheme
-     * herself, for example
-     * downwind numbering.
+     * This function is called by the functions in DoFRenumbering function
+     * after computing the ordering of the degrees of freedom. However, you
+     * can call this function yourself, which is necessary if a user wants to
+     * implement an ordering scheme herself, for example downwind numbering.
      *
-     * The @p new_number array must
-     * have a size equal to the
-     * number of degrees of
-     * freedom. Each entry must
-     * state the new global DoF
-     * number of the degree of
-     * freedom referenced.
+     * The @p new_number array must have a size equal to the number of degrees
+     * of freedom. Each entry must state the new global DoF number of the
+     * degree of freedom referenced.
      */
     void renumber_dofs (const std::vector<types::global_dof_index> &new_numbers);
 
     /**
-     * Return the maximum number of
-     * degrees of freedom a degree of freedom
-     * in the given triangulation with the
-     * given finite element may couple with.
-     * This is the maximum number of entries
-     * per line in the system matrix; this
-     * information can therefore be used upon
-     * construction of the SparsityPattern
-     * object.
+     * Return the maximum number of degrees of freedom a degree of freedom in
+     * the given triangulation with the given finite element may couple with.
+     * This is the maximum number of entries per line in the system matrix;
+     * this information can therefore be used upon construction of the
+     * SparsityPattern object.
      *
-     * The returned number is not really the
-     * maximum number but an estimate based
-     * on the finite element and the maximum
-     * number of cells meeting at a vertex.
-     * The number holds for the constrained
-     * matrix also.
+     * The returned number is not really the maximum number but an estimate
+     * based on the finite element and the maximum number of cells meeting at
+     * a vertex. The number holds for the constrained matrix also.
      *
-     * As for
-     * ::DoFHandler::max_couplings_between_dofs(),
-     * the result of this function is often
-     * not very accurate for 3d and/or high
-     * polynomial degrees. The consequences
-     * are discussed in the documentation
-     * of the module on @ref Sparsity.
+     * As for ::DoFHandler::max_couplings_between_dofs(), the result of this
+     * function is often not very accurate for 3d and/or high polynomial
+     * degrees. The consequences are discussed in the documentation of the
+     * module on @ref Sparsity.
      */
     unsigned int max_couplings_between_dofs () const;
 
     /**
-     * Return the number of degrees of freedom
-     * located on the boundary another dof on
-     * the boundary can couple with.
+     * Return the number of degrees of freedom located on the boundary another
+     * dof on the boundary can couple with.
      *
-     * The number is the same as for
-     * @p max_coupling_between_dofs in one
+     * The number is the same as for @p max_coupling_between_dofs in one
      * dimension less.
      *
      * @note The same applies to this function as to max_couplings_per_dofs()
@@ -392,63 +332,56 @@ namespace hp
     unsigned int max_couplings_between_boundary_dofs () const;
 
     /**
-     @name Cell iterator functions
-    */
+     * @name Cell iterator functions
+     */
     /*@{*/
     /**
-    * Iterator to the first used
-    * cell on level @p level.
-    */
+     * Iterator to the first used cell on level @p level.
+     */
     cell_iterator        begin       (const unsigned int level = 0) const;
 
     /**
-     *  Iterator to the first active cell on level @p level. If the
-     *  given level does not contain any active cells (i.e., all cells
-     *  on this level are further refined, then this function returns
-     *  <code>end_active(level)</code> so that loops of the kind
+     * Iterator to the first active cell on level @p level. If the given level
+     * does not contain any active cells (i.e., all cells on this level are
+     * further refined, then this function returns
+     * <code>end_active(level)</code> so that loops of the kind
      *  @code
      *    for (cell=dof_handler.begin_active(level); cell!=dof_handler.end_active(level); ++cell)
      *      ...
      *  @endcode
-     *  have zero iterations, as may be expected if there are no active
-     *  cells on this level.
+     * have zero iterations, as may be expected if there are no active cells
+     * on this level.
      */
     active_cell_iterator begin_active(const unsigned int level = 0) const;
 
     /**
-    * Iterator past the end; this
-    * iterator serves for
-    * comparisons of iterators with
-    * past-the-end or
-    * before-the-beginning states.
-    */
+     * Iterator past the end; this iterator serves for comparisons of
+     * iterators with past-the-end or before-the-beginning states.
+     */
     cell_iterator        end () const;
 
     /**
-    * Return an iterator which is
-    * the first iterator not on
-    * level. If @p level is the
-    * last level, then this returns
-    * <tt>end()</tt>.
-    */
+     * Return an iterator which is the first iterator not on level. If @p
+     * level is the last level, then this returns <tt>end()</tt>.
+     */
     cell_iterator        end (const unsigned int level) const;
 
     /**
-     * Return an active iterator which is the first active iterator not
-     * on the given level. If @p level is the last level, then this
-     * returns <tt>end()</tt>.
+     * Return an active iterator which is the first active iterator not on the
+     * given level. If @p level is the last level, then this returns
+     * <tt>end()</tt>.
      */
     active_cell_iterator end_active (const unsigned int level) const;
 
     /**
-     *  @name Cell iterator functions returning ranges of iterators
+     * @name Cell iterator functions returning ranges of iterators
      */
 
     /**
-     * Return an iterator range that contains all cells (active or not)
-     * that make up this DoFHandler. Such a range is useful to
-     * initialize range-based for loops as supported by C++11. See the
-     * example in the documentation of active_cell_iterators().
+     * Return an iterator range that contains all cells (active or not) that
+     * make up this DoFHandler. Such a range is useful to initialize range-
+     * based for loops as supported by C++11. See the example in the
+     * documentation of active_cell_iterators().
      *
      * @return The half open range <code>[this->begin(), this->end())</code>
      *
@@ -457,16 +390,16 @@ namespace hp
     IteratorRange<cell_iterator>        cell_iterators () const;
 
     /**
-     * Return an iterator range that contains all active cells
-     * that make up this DoFHandler. Such a range is useful to
-     * initialize range-based for loops as supported by C++11,
-     * see also @ref CPP11 "C++11 standard".
+     * Return an iterator range that contains all active cells that make up
+     * this DoFHandler. Such a range is useful to initialize range-based for
+     * loops as supported by C++11, see also @ref CPP11 "C++11 standard".
      *
-     * Range-based for loops are useful in that they require much less
-     * code than traditional loops (see
-     * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
-     * for a discussion of how they work). An example is that without
-     * range-based for loops, one often writes code such as the following:
+     * Range-based for loops are useful in that they require much less code
+     * than traditional loops (see <a
+     * href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-
+     * based_for_loop">here</a> for a discussion of how they work). An example
+     * is that without range-based for loops, one often writes code such as
+     * the following:
      * @code
      *   DoFHandler<dim> dof_handler;
      *   ...
@@ -479,8 +412,8 @@ namespace hp
      *       ...do the local integration on 'cell'...;
      *     }
      * @endcode
-     * Using C++11's range-based for loops, this is now entirely
-     * equivalent to the following:
+     * Using C++11's range-based for loops, this is now entirely equivalent to
+     * the following:
      * @code
      *   DoFHandler<dim> dof_handler;
      *   ...
@@ -492,21 +425,22 @@ namespace hp
      * @endcode
      * To use this feature, you need a compiler that supports C++11.
      *
-     * @return The half open range <code>[this->begin_active(), this->end())</code>
+     * @return The half open range <code>[this->begin_active(),
+     * this->end())</code>
      *
      * @ingroup CPP11
      */
     IteratorRange<active_cell_iterator> active_cell_iterators () const;
 
     /**
-     * Return an iterator range that contains all cells (active or not)
-     * that make up the given level of this DoFHandler. Such a range is useful to
-     * initialize range-based for loops as supported by C++11. See the
-     * example in the documentation of active_cell_iterators().
+     * Return an iterator range that contains all cells (active or not) that
+     * make up the given level of this DoFHandler. Such a range is useful to
+     * initialize range-based for loops as supported by C++11. See the example
+     * in the documentation of active_cell_iterators().
      *
      * @param[in] level A given level in the refinement hierarchy of this
-     *   triangulation.
-     * @return The half open range <code>[this->begin(level), this->end(level))</code>
+     * triangulation. @return The half open range <code>[this->begin(level),
+     * this->end(level))</code>
      *
      * @pre level must be less than this->n_levels().
      *
@@ -515,14 +449,14 @@ namespace hp
     IteratorRange<cell_iterator>        cell_iterators_on_level (const unsigned int level) const;
 
     /**
-     * Return an iterator range that contains all active cells
-     * that make up the given level of this DoFHandler. Such a range is useful to
-     * initialize range-based for loops as supported by C++11. See the
-     * example in the documentation of active_cell_iterators().
+     * Return an iterator range that contains all active cells that make up
+     * the given level of this DoFHandler. Such a range is useful to
+     * initialize range-based for loops as supported by C++11. See the example
+     * in the documentation of active_cell_iterators().
      *
      * @param[in] level A given level in the refinement hierarchy of this
-     *   triangulation.
-     * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+     * triangulation. @return The half open range
+     * <code>[this->begin_active(level), this->end(level))</code>
      *
      * @pre level must be less than this->n_levels().
      *
@@ -538,198 +472,120 @@ namespace hp
 
 
     /**
-     * Return the global number of
-     * degrees of freedom. If the
-     * current object handles all
-     * degrees of freedom itself
-     * (even if you may intend to
-     * solve your linear system in
-     * parallel, such as in step-17
-     * or step-18), then this number
-     * equals the number of locally
-     * owned degrees of freedom since
-     * this object doesn't know
-     * anything about what you want
-     * to do with it and believes
-     * that it owns every degree of
-     * freedom it knows about.
+     * Return the global number of degrees of freedom. If the current object
+     * handles all degrees of freedom itself (even if you may intend to solve
+     * your linear system in parallel, such as in step-17 or step-18), then
+     * this number equals the number of locally owned degrees of freedom since
+     * this object doesn't know anything about what you want to do with it and
+     * believes that it owns every degree of freedom it knows about.
      *
-     * On the other hand, if this
-     * object operates on a
-     * parallel::distributed::Triangulation
-     * object, then this function
-     * returns the global number of
-     * degrees of freedom,
-     * accumulated over all
+     * On the other hand, if this object operates on a
+     * parallel::distributed::Triangulation object, then this function returns
+     * the global number of degrees of freedom, accumulated over all
      * processors.
      *
-     * In either case, included in
-     * the returned number are those
-     * DoFs which are constrained by
-     * hanging nodes, see @ref constraints.
+     * In either case, included in the returned number are those DoFs which
+     * are constrained by hanging nodes, see @ref constraints.
      */
     types::global_dof_index n_dofs () const;
 
     /**
-    * The number of multilevel
-    * dofs on given level. Since
-    * hp::DoFHandler does not
-    * support multilevel methods
-    * yet, this function returns
-    * numbers::invalid_unsigned
-    * int independent of its argument.
-    */
+     * The number of multilevel dofs on given level. Since hp::DoFHandler does
+     * not support multilevel methods yet, this function returns
+     * numbers::invalid_unsigned int independent of its argument.
+     */
     types::global_dof_index n_dofs(const unsigned int level) const;
 
     /**
-     * Return the number of degrees of freedom
-     * located on the boundary.
+     * Return the number of degrees of freedom located on the boundary.
      */
     types::global_dof_index n_boundary_dofs () const;
 
     /**
-     * Return the number of degrees
-     * of freedom located on those
-     * parts of the boundary which
-     * have a boundary indicator
-     * listed in the given set. The
-     * reason that a @p map rather
-     * than a @p set is used is the
-     * same as described in the
-     * section on the
-     * @p make_boundary_sparsity_pattern
+     * Return the number of degrees of freedom located on those parts of the
+     * boundary which have a boundary indicator listed in the given set. The
+     * reason that a @p map rather than a @p set is used is the same as
+     * described in the section on the @p make_boundary_sparsity_pattern
      * function.
      */
     types::global_dof_index
     n_boundary_dofs (const FunctionMap &boundary_indicators) const;
 
     /**
-     * Same function, but with
-     * different data type of the
-     * argument, which is here simply
-     * a list of the boundary
-     * indicators under
-     * consideration.
+     * Same function, but with different data type of the argument, which is
+     * here simply a list of the boundary indicators under consideration.
      */
     types::global_dof_index
     n_boundary_dofs (const std::set<types::boundary_id> &boundary_indicators) const;
 
     /**
-     * Return the number of
-     * degrees of freedom that
-     * belong to this
-     * process.
+     * Return the number of degrees of freedom that belong to this process.
      *
-     * If this is a sequential job,
-     * then the result equals that
-     * produced by n_dofs(). On the
-     * other hand, if we are
-     * operating on a
-     * parallel::distributed::Triangulation,
-     * then it includes only the
-     * degrees of freedom that the
-     * current processor owns. Note
-     * that in this case this does
-     * not include all degrees of
-     * freedom that have been
-     * distributed on the current
-     * processor's image of the mesh:
-     * in particular, some of the
-     * degrees of freedom on the
-     * interface between the cells
-     * owned by this processor and
-     * cells owned by other
-     * processors may be theirs, and
-     * degrees of freedom on ghost
-     * cells are also not necessarily
-     * included.
+     * If this is a sequential job, then the result equals that produced by
+     * n_dofs(). On the other hand, if we are operating on a
+     * parallel::distributed::Triangulation, then it includes only the degrees
+     * of freedom that the current processor owns. Note that in this case this
+     * does not include all degrees of freedom that have been distributed on
+     * the current processor's image of the mesh: in particular, some of the
+     * degrees of freedom on the interface between the cells owned by this
+     * processor and cells owned by other processors may be theirs, and
+     * degrees of freedom on ghost cells are also not necessarily included.
      */
     types::global_dof_index n_locally_owned_dofs() const;
 
     /**
-     * Return an IndexSet describing
-     * the set of locally owned DoFs
-     * as a subset of
-     * 0..n_dofs(). The number of
-     * elements of this set equals
+     * Return an IndexSet describing the set of locally owned DoFs as a subset
+     * of 0..n_dofs(). The number of elements of this set equals
      * n_locally_owned_dofs().
      */
     const IndexSet &locally_owned_dofs() const;
 
 
     /**
-     * Returns a vector that
-     * stores the locally owned
-     * DoFs of each processor. If
-     * you are only interested in
-     * the number of elements
-     * each processor owns then
-     * n_dofs_per_processor() is
-     * a better choice.
+     * Returns a vector that stores the locally owned DoFs of each processor.
+     * If you are only interested in the number of elements each processor
+     * owns then n_dofs_per_processor() is a better choice.
      *
-     * If this is a sequential job,
-     * then the vector has a single
-     * element that equals the
-     * IndexSet representing the
-     * entire range [0,n_dofs()].
+     * If this is a sequential job, then the vector has a single element that
+     * equals the IndexSet representing the entire range [0,n_dofs()].
      */
     const std::vector<IndexSet> &
     locally_owned_dofs_per_processor () const;
 
     /**
-     * Return a vector that
-     * stores the number of
-     * degrees of freedom each
-     * processor that
-     * participates in this
-     * triangulation owns
-     * locally. The sum of all
-     * these numbers equals the
-     * number of degrees of
-     * freedom that exist
-     * globally, i.e. what
-     * n_dofs() returns.
+     * Return a vector that stores the number of degrees of freedom each
+     * processor that participates in this triangulation owns locally. The sum
+     * of all these numbers equals the number of degrees of freedom that exist
+     * globally, i.e. what n_dofs() returns.
      *
-     * Each element of the vector
-     * returned by this function
-     * equals the number of
-     * elements of the
-     * corresponding sets
-     * returned by
-     * global_dof_indices().
+     * Each element of the vector returned by this function equals the number
+     * of elements of the corresponding sets returned by global_dof_indices().
      *
-     * If this is a sequential job,
-     * then the vector has a single
-     * element equal to n_dofs().
+     * If this is a sequential job, then the vector has a single element equal
+     * to n_dofs().
      */
     const std::vector<types::global_dof_index> &
     n_locally_owned_dofs_per_processor () const;
 
     /**
-     * Return a constant reference to
-     * the set of finite element
-     * objects that are used by this
-     * @p DoFHandler.
+     * Return a constant reference to the set of finite element objects that
+     * are used by this @p DoFHandler.
      */
     const hp::FECollection<dim,spacedim> &get_fe () const;
 
     /**
-     * Return a constant reference to the
-     * triangulation underlying this object.
+     * Return a constant reference to the triangulation underlying this
+     * object.
      */
     const Triangulation<dim,spacedim> &get_tria () const;
 
     /**
-     * Determine an estimate for the
-     * memory consumption (in bytes)
-     * of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      *
-     * This function is made virtual,
-     * since a dof handler object
-     * might be accessed through a
-     * pointers to thisr base class,
-     * although the actual object
-     * might be a derived class.
+     * This function is made virtual, since a dof handler object might be
+     * accessed through a pointers to thisr base class, although the actual
+     * object might be a derived class.
      */
     virtual std::size_t memory_consumption () const;
 
@@ -760,7 +616,7 @@ namespace hp
                     int,
                     << "The matrix has the wrong dimension " << arg1);
     /**
-     *  Exception
+     * Exception
      */
     DeclException0 (ExcFunctionNotUseful);
     /**
@@ -779,7 +635,7 @@ namespace hp
                     << arg1 << ", but the finite element collection only has "
                     << arg2 << " elements");
     /**
-     *  Exception
+     * Exception
      */
     DeclException1 (ExcInvalidLevel,
                     int,
@@ -790,8 +646,7 @@ namespace hp
      */
     DeclException0 (ExcFacesHaveNoLevel);
     /**
-     * The triangulation level you
-     * accessed is empty.
+     * The triangulation level you accessed is empty.
      */
     DeclException1 (ExcEmptyLevel,
                     int,
@@ -801,49 +656,35 @@ namespace hp
   protected:
 
     /**
-     * Address of the triangulation to
-     * work on.
+     * Address of the triangulation to work on.
      */
     SmartPointer<const Triangulation<dim,spacedim>,DoFHandler<dim,spacedim> > tria;
 
     /**
-     * Store a pointer to the finite
-     * element set given latest for
-     * the distribution of dofs. In
-     * order to avoid destruction of
-     * the object before the lifetime
-     * of the DoF handler, we
-     * subscribe to the finite
-     * element object. To unlock the
-     * FE before the end of the
-     * lifetime of this DoF handler,
-     * use the <tt>clear()</tt> function
-     * (this clears all data of this
-     * object as well, though).
+     * Store a pointer to the finite element set given latest for the
+     * distribution of dofs. In order to avoid destruction of the object
+     * before the lifetime of the DoF handler, we subscribe to the finite
+     * element object. To unlock the FE before the end of the lifetime of this
+     * DoF handler, use the <tt>clear()</tt> function (this clears all data of
+     * this object as well, though).
      */
     SmartPointer<const hp::FECollection<dim,spacedim>,hp::DoFHandler<dim,spacedim> > finite_elements;
 
   private:
 
     /**
-     * Copy constructor. I can see no reason
-     * why someone might want to use it, so
-     * I don't provide it. Since this class
-     * has pointer members, making it private
-     * prevents the compiler to provide it's
-     * own, incorrect one if anyone chose to
-     * copy such an object.
+     * Copy constructor. I can see no reason why someone might want to use it,
+     * so I don't provide it. Since this class has pointer members, making it
+     * private prevents the compiler to provide it's own, incorrect one if
+     * anyone chose to copy such an object.
      */
     DoFHandler (const DoFHandler &);
 
     /**
-     * Copy operator. I can see no reason
-     * why someone might want to use it, so
-     * I don't provide it. Since this class
-     * has pointer members, making it private
-     * prevents the compiler to provide it's
-     * own, incorrect one if anyone chose to
-     * copy such an object.
+     * Copy operator. I can see no reason why someone might want to use it, so
+     * I don't provide it. Since this class has pointer members, making it
+     * private prevents the compiler to provide it's own, incorrect one if
+     * anyone chose to copy such an object.
      */
     DoFHandler &operator = (const DoFHandler &);
 
@@ -868,87 +709,55 @@ namespace hp
     void set_dof_index (const unsigned int obj_level, const unsigned int obj_index, const unsigned int fe_index, const unsigned int local_index, const types::global_dof_index global_index) const;
 
     /**
-     *  Create default tables for
-     *  the active_fe_indices in
-     *  the
-     *  dealii::internal::hp::DoFLevel. They
-     *  are initialized with a
-     *  zero indicator, meaning
-     *  that fe[0] is going to be
-     *  used by default.  This
-     *  method is called before
-     *  refinement and before
-     *  distribute_dofs is
-     *  called. It ensures each
-     *  cell has a valid
-     *  active_fe_index.
+     * Create default tables for the active_fe_indices in the
+     * dealii::internal::hp::DoFLevel. They are initialized with a zero
+     * indicator, meaning that fe[0] is going to be used by default.  This
+     * method is called before refinement and before distribute_dofs is
+     * called. It ensures each cell has a valid active_fe_index.
      */
     void create_active_fe_table ();
 
     /**
-     *  Functions that will be triggered
-     *  through signals whenever the
-     *  triangulation is modified.
+     * Functions that will be triggered through signals whenever the
+     * triangulation is modified.
      *
-     *  Here they are used to
-     *  administrate the the
-     *  active_fe_fields during the
-     *  spatial refinement.
+     * Here they are used to administrate the the active_fe_fields during the
+     * spatial refinement.
      */
     void pre_refinement_action ();
     void post_refinement_action ();
 
     /**
-     * Compute identities between
-     * DoFs located on
-     * vertices. Called from
+     * Compute identities between DoFs located on vertices. Called from
      * distribute_dofs().
      */
     void
     compute_vertex_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
 
     /**
-     * Compute identities between
-     * DoFs located on
-     * lines. Called from
+     * Compute identities between DoFs located on lines. Called from
      * distribute_dofs().
      */
     void
     compute_line_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
 
     /**
-     * Compute identities between
-     * DoFs located on
-     * quads. Called from
+     * Compute identities between DoFs located on quads. Called from
      * distribute_dofs().
      */
     void
     compute_quad_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
 
     /**
-     * Renumber the objects with
-     * the given and all lower
-     * structural dimensions,
-     * i.e. renumber vertices by
-     * giving a template argument
-     * of zero to the int2type
-     * argument, lines and vertices
-     * with one, etc.
+     * Renumber the objects with the given and all lower structural
+     * dimensions, i.e. renumber vertices by giving a template argument of
+     * zero to the int2type argument, lines and vertices with one, etc.
      *
-     * Note that in contrast to the
-     * public renumber_dofs()
-     * function, these internal
-     * functions do not ensure that
-     * the new DoFs are
-     * contiguously numbered. The
-     * function may therefore also
-     * be used to assign different
-     * DoFs the same number, for
-     * example to unify hp DoFs
-     * corresponding to different
-     * finite elements but
-     * co-located on the same
-     * entity.
+     * Note that in contrast to the public renumber_dofs() function, these
+     * internal functions do not ensure that the new DoFs are contiguously
+     * numbered. The function may therefore also be used to assign different
+     * DoFs the same number, for example to unify hp DoFs corresponding to
+     * different finite elements but co-located on the same entity.
      */
     void renumber_dofs_internal (const std::vector<types::global_dof_index> &new_numbers,
                                  dealii::internal::int2type<0>);
@@ -963,104 +772,67 @@ namespace hp
                                  dealii::internal::int2type<3>);
 
     /**
-     * Space to store the DoF
-     * numbers for the different
-     * levels. Analogous to the
-     * <tt>levels[]</tt> tree of
-     * the Triangulation objects.
+     * Space to store the DoF numbers for the different levels. Analogous to
+     * the <tt>levels[]</tt> tree of the Triangulation objects.
      */
     std::vector<dealii::internal::hp::DoFLevel *> levels;
 
     /**
-     * Space to store the DoF
-     * numbers for the faces.
-     * Analogous to the
-     * <tt>faces</tt> pointer of
-     * the Triangulation objects.
+     * Space to store the DoF numbers for the faces. Analogous to the
+     * <tt>faces</tt> pointer of the Triangulation objects.
      */
     dealii::internal::hp::DoFIndicesOnFaces<dim> *faces;
 
     /**
-     * A structure that contains all
-     * sorts of numbers that
-     * characterize the degrees of
-     * freedom this object works on.
+     * A structure that contains all sorts of numbers that characterize the
+     * degrees of freedom this object works on.
      *
-     * For most members of this
-     * structure, there is an
-     * accessor function in this
-     * class that returns its value.
+     * For most members of this structure, there is an accessor function in
+     * this class that returns its value.
      */
     dealii::internal::DoFHandler::NumberCache number_cache;
 
     /**
-     * Array to store the indices
-     * for degrees of freedom
-     * located at vertices.
+     * Array to store the indices for degrees of freedom located at vertices.
      *
-     * The format used here, in the
-     * form of a linked list, is
-     * the same as used for the
-     * arrays used in the
-     * internal::hp::DoFLevel
-     * hierarchy. Starting indices
-     * into this array are provided
-     * by the vertex_dofs_offsets
-     * field.
+     * The format used here, in the form of a linked list, is the same as used
+     * for the arrays used in the internal::hp::DoFLevel hierarchy. Starting
+     * indices into this array are provided by the vertex_dofs_offsets field.
      *
-     * Access to this field is
-     * generally through the
+     * Access to this field is generally through the
      * DoFAccessor::get_vertex_dof_index() and
-     * DoFAccessor::set_vertex_dof_index()
-     * functions, encapsulating the
-     * actual data format used to
-     * the present class.
+     * DoFAccessor::set_vertex_dof_index() functions, encapsulating the actual
+     * data format used to the present class.
      */
     std::vector<types::global_dof_index> vertex_dofs;
 
     /**
-     * For each vertex in the
-     * triangulation, store the
-     * offset within the
-     * vertex_dofs array where the
-     * dofs for this vertex start.
+     * For each vertex in the triangulation, store the offset within the
+     * vertex_dofs array where the dofs for this vertex start.
      *
-     * As for that array, the
-     * format is the same as
-     * described in the
-     * documentation of
-     * hp::DoFLevel.
+     * As for that array, the format is the same as described in the
+     * documentation of hp::DoFLevel.
      *
-     * Access to this field is
-     * generally through the
-     * Accessor::get_vertex_dof_index() and
-     * Accessor::set_vertex_dof_index()
-     * functions, encapsulating the
-     * actual data format used to
-     * the present class.
+     * Access to this field is generally through the
+     * Accessor::get_vertex_dof_index() and Accessor::set_vertex_dof_index()
+     * functions, encapsulating the actual data format used to the present
+     * class.
      */
     std::vector<types::global_dof_index>      vertex_dofs_offsets;
 
     std::vector<MGVertexDoFs> mg_vertex_dofs;  // we should really remove this field!
 
     /**
-     * Array to store the
-     * information if a cell on
-     * some level has children or
-     * not. It is used by the
-     * signal slots as a
-     * persistent buffer during the
-     * refinement, i.e. from between
-     * when pre_refinement_action is
-     * called and when post_refinement_action
-     * runs.
+     * Array to store the information if a cell on some level has children or
+     * not. It is used by the signal slots as a persistent buffer during the
+     * refinement, i.e. from between when pre_refinement_action is called and
+     * when post_refinement_action runs.
      */
     std::vector<std::vector<bool> *> has_children;
 
     /**
-     * A list of connections with which this object connects
-     * to the triangulation to get information about when the
-     * triangulation changes.
+     * A list of connections with which this object connects to the
+     * triangulation to get information about when the triangulation changes.
      */
     std::vector<boost::signals2::connection> tria_listeners;
 
@@ -1073,11 +845,8 @@ namespace hp
     friend struct dealii::internal::DoFCellAccessor::Implementation;
 
     /**
-     * Likewise for DoFLevel
-     * objects since they need to
-     * access the vertex dofs in
-     * the functions that set and
-     * retrieve vertex dof indices.
+     * Likewise for DoFLevel objects since they need to access the vertex dofs
+     * in the functions that set and retrieve vertex dof indices.
      */
     template <int> friend class dealii::internal::hp::DoFIndicesOnFacesOrEdges;
     friend struct dealii::internal::hp::DoFHandler::Implementation;
index c99f945ccca7de103c2f5009ae2ba3adc7d67589..26165828b43ba9ffffbe21cfba3cbc38af961da5 100644 (file)
@@ -55,49 +55,50 @@ namespace internal
     /**
      * This is the class that stores the degrees of freedom on cells in a hp
      * hierarchy. Compared to faces and edges, the task here is simple since
-     * each cell can only have a single active finite element index. Consequently,
-     * all we need is one long array with DoF indices and one array of offsets
-     * where each cell's indices start within the array of indices. This is in
-     * contrast to the DoFObjects class where each face or edge may have more than
-     * one associated finite element with corresponding degrees of freedom.
+     * each cell can only have a single active finite element index.
+     * Consequently, all we need is one long array with DoF indices and one
+     * array of offsets where each cell's indices start within the array of
+     * indices. This is in contrast to the DoFObjects class where each face or
+     * edge may have more than one associated finite element with
+     * corresponding degrees of freedom.
      *
-     * The data stored here is represented by three arrays
-     * - The @p active_fe_indices array stores for each cell which
-     *   finite element is used on this cell. Since some cells are not active
-     *   on the current level, some entries in this array may represent an
-     *   invalid value.
-     * - The @p dof_indices array stores for each active cell on the current
-     *   level the dofs that associated with the <i>interior</i> of the cell,
-     *   i.e., the @p dofs_per_line dofs associated with the line in 1d, and
-     *   @p dofs_per_quad and @p dofs_per_hex in 2d and 3d. These numbers are
-     *   in general smaller than @p dofs_per_cell.
-     * - The @p dof_offsets array stores, for each cell, the starting point
-     *   of the dof indices corresponding to this cell in the @p dof_indices
-     *   array. This is analogous to how we store data in compressed row storage
-     *   for sparse matrices. For cells that are not active on the current level,
-     *   we store an invalid value for the starting index.
+     * The data stored here is represented by three arrays - The @p
+     * active_fe_indices array stores for each cell which finite element is
+     * used on this cell. Since some cells are not active on the current
+     * level, some entries in this array may represent an invalid value. - The
+     * @p dof_indices array stores for each active cell on the current level
+     * the dofs that associated with the <i>interior</i> of the cell, i.e.,
+     * the @p dofs_per_line dofs associated with the line in 1d, and @p
+     * dofs_per_quad and @p dofs_per_hex in 2d and 3d. These numbers are in
+     * general smaller than @p dofs_per_cell. - The @p dof_offsets array
+     * stores, for each cell, the starting point of the dof indices
+     * corresponding to this cell in the @p dof_indices array. This is
+     * analogous to how we store data in compressed row storage for sparse
+     * matrices. For cells that are not active on the current level, we store
+     * an invalid value for the starting index.
      *
      * <h3>Compression</h3>
      *
-     * It is common for the indices stored in @p dof_indices for one cell to be
-     * numbered consecutively. For example, using the standard numbering (without
-     * renumbering DoFs), the quad dofs on the first cell of a mesh when using a
-     * $Q_3$ element will be numbered <tt>12, 13, 14, 15</tt>. This allows for
-     * compression if we only store the first entry and have some way to mark
-     * the DoFs on this object as compressed. Here, compression means that we
-     * know that subsequent DoF indices can be obtained from the previous ones
-     * by just incrementing them by one -- in other words, we use a variant of doing
-     * run-length encoding. The way to do this is that we
-     * use positive FE indices for uncompressed sets of DoFs and if a set of indices
-     * is compressed, then we instead store the FE index in binary complement (which
-     * we can identify by looking at the sign bit when interpreting the number as a
-     * signed one). There are two functions, compress_data() and uncompress_data()
-     * that convert between the two possible representations.
+     * It is common for the indices stored in @p dof_indices for one cell to
+     * be numbered consecutively. For example, using the standard numbering
+     * (without renumbering DoFs), the quad dofs on the first cell of a mesh
+     * when using a $Q_3$ element will be numbered <tt>12, 13, 14, 15</tt>.
+     * This allows for compression if we only store the first entry and have
+     * some way to mark the DoFs on this object as compressed. Here,
+     * compression means that we know that subsequent DoF indices can be
+     * obtained from the previous ones by just incrementing them by one -- in
+     * other words, we use a variant of doing run-length encoding. The way to
+     * do this is that we use positive FE indices for uncompressed sets of
+     * DoFs and if a set of indices is compressed, then we instead store the
+     * FE index in binary complement (which we can identify by looking at the
+     * sign bit when interpreting the number as a signed one). There are two
+     * functions, compress_data() and uncompress_data() that convert between
+     * the two possible representations.
      *
-     * Note that compression is not always possible. For example, if one renumbered
-     * the example above using DoFRenumbering::downstream with $(1,0)^T$ as
-     * direction, then they would likely be numbered <tt>12, 14, 13, 15</tt>, which
-     * can not be compressed using run-length encoding.
+     * Note that compression is not always possible. For example, if one
+     * renumbered the example above using DoFRenumbering::downstream with
+     * $(1,0)^T$ as direction, then they would likely be numbered <tt>12, 14,
+     * 13, 15</tt>, which can not be compressed using run-length encoding.
      */
     class DoFLevel
     {
@@ -119,24 +120,23 @@ namespace internal
       typedef signed short int signed_active_fe_index_type;
 
       /**
-       * Indices specifying the finite element of hp::FECollection to
-       * use for the different cells on the current level. The vector
-       * stores one element per cell since the active_fe_index is
-       * unique for cells.
+       * Indices specifying the finite element of hp::FECollection to use for
+       * the different cells on the current level. The vector stores one
+       * element per cell since the active_fe_index is unique for cells.
        *
-       * If a cell is not active on the level corresponding to the
-       * current object (i.e., it has children on higher levels) then
-       * it does not have an associated fe index and we store
-       * an invalid fe index marker instead.
+       * If a cell is not active on the level corresponding to the current
+       * object (i.e., it has children on higher levels) then it does not have
+       * an associated fe index and we store an invalid fe index marker
+       * instead.
        */
       std::vector<active_fe_index_type> active_fe_indices;
 
       /**
-       * Store the start index for the degrees of freedom of each
-       * object in the @p dof_indices array. If the cell corresponding to
-       * a particular index in this array is not active on this level,
-       * then we do not store any DoFs for it. In that case, the offset
-       * we store here must be an invalid number and indeed we store
+       * Store the start index for the degrees of freedom of each object in
+       * the @p dof_indices array. If the cell corresponding to a particular
+       * index in this array is not active on this level, then we do not store
+       * any DoFs for it. In that case, the offset we store here must be an
+       * invalid number and indeed we store
        * <code>(std::vector<types::global_dof_index>::size_type)(-1)</code>
        * for it.
        *
@@ -146,9 +146,9 @@ namespace internal
       std::vector<offset_type> dof_offsets;
 
       /**
-       * Store the global indices of the degrees of freedom.
-       * information. The dof_offsets field determines where each
-       * (active) cell's data is stored.
+       * Store the global indices of the degrees of freedom. information. The
+       * dof_offsets field determines where each (active) cell's data is
+       * stored.
        */
       std::vector<types::global_dof_index> dof_indices;
 
@@ -158,36 +158,24 @@ namespace internal
       std::vector<offset_type> cell_cache_offsets;
 
       /**
-       * Cache for the DoF indices
-       * on cells. The size of this
-       * array equals the sum over all cells of selected_fe[active_fe_index[cell]].dofs_per_cell.
+       * Cache for the DoF indices on cells. The size of this array equals the
+       * sum over all cells of
+       * selected_fe[active_fe_index[cell]].dofs_per_cell.
        */
       std::vector<types::global_dof_index> cell_dof_indices_cache;
 
     public:
 
       /**
-       * Set the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index to the value
-       * given by @p global_index. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Set the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index to the value given by
+       * @p global_index. The @p dof_handler argument is used to access the
+       * finite element that is to be used to compute the location where this
+       * data is stored.
        *
-       * The third argument, @p
-       * fe_index, denotes which of
-       * the finite elements
-       * associated with this
-       * object we shall
-       * access. Refer to the
-       * general documentation of
-       * the internal::hp::DoFLevel
-       * class template for more
+       * The third argument, @p fe_index, denotes which of the finite elements
+       * associated with this object we shall access. Refer to the general
+       * documentation of the internal::hp::DoFLevel class template for more
        * information.
        */
       void
@@ -197,26 +185,14 @@ namespace internal
                      const types::global_dof_index    global_index);
 
       /**
-       * Return the global index of
-       * the @p local_index-th
-       * degree of freedom located
-       * on the object with number @p
-       * obj_index. The @p
-       * dof_handler argument is
-       * used to access the finite
-       * element that is to be used
-       * to compute the location
-       * where this data is stored.
+       * Return the global index of the @p local_index-th degree of freedom
+       * located on the object with number @p obj_index. The @p dof_handler
+       * argument is used to access the finite element that is to be used to
+       * compute the location where this data is stored.
        *
-       * The third argument, @p
-       * fe_index, denotes which of
-       * the finite elements
-       * associated with this
-       * object we shall
-       * access. Refer to the
-       * general documentation of
-       * the internal::hp::DoFLevel
-       * class template for more
+       * The third argument, @p fe_index, denotes which of the finite elements
+       * associated with this object we shall access. Refer to the general
+       * documentation of the internal::hp::DoFLevel class template for more
        * information.
        */
       types::global_dof_index
@@ -225,17 +201,13 @@ namespace internal
                      const unsigned int               local_index) const;
 
       /**
-       * Return the fe_index of the
-       * active finite element
-       * on this object.
+       * Return the fe_index of the active finite element on this object.
        */
       unsigned int
       active_fe_index (const unsigned int obj_index) const;
 
       /**
-       * Check whether a given
-       * finite element index is
-       * used on the present
+       * Check whether a given finite element index is used on the present
        * object or not.
        */
       bool
@@ -243,64 +215,59 @@ namespace internal
                           const unsigned int               fe_index) const;
 
       /**
-       * Set the fe_index of the
-       * active finite element
-       * on this object.
+       * Set the fe_index of the active finite element on this object.
        */
       void
       set_active_fe_index (const unsigned int obj_index,
                            const unsigned int fe_index);
 
       /**
-       * Return a pointer to the beginning of the DoF indices cache
-       * for a given cell.
+       * Return a pointer to the beginning of the DoF indices cache for a
+       * given cell.
        *
        * @param obj_index The number of the cell we are looking at.
        * @param dofs_per_cell The number of DoFs per cell for this cell. This
-       *   is not used for the hp case but necessary to keep the interface
-       *   the same as for the non-hp case.
-       * @return A pointer to the first DoF index for the current cell. The
-       *   next dofs_per_cell indices are for the current cell.
+       * is not used for the hp case but necessary to keep the interface the
+       * same as for the non-hp case. @return A pointer to the first DoF index
+       * for the current cell. The next dofs_per_cell indices are for the
+       * current cell.
        */
       const types::global_dof_index *
       get_cell_cache_start (const unsigned int obj_index,
                             const unsigned int dofs_per_cell) const;
 
       /**
-       * Determine an estimate for the
-       * memory consumption (in bytes)
-       * of this object.
+       * Determine an estimate for the memory consumption (in bytes) of this
+       * object.
        */
       std::size_t memory_consumption () const;
 
     private:
       /**
-       * Compress the arrays that store dof indices by using a variant
-       * of run-length encoding. See the general documentation of this
-       * class for more information.
+       * Compress the arrays that store dof indices by using a variant of run-
+       * length encoding. See the general documentation of this class for more
+       * information.
        *
-       * @param fe_collection The object that can tell us how many
-       * degrees of freedom each of the finite elements has that we
-       * store in this object.
+       * @param fe_collection The object that can tell us how many degrees of
+       * freedom each of the finite elements has that we store in this object.
        */
       template <int dim, int spacedim>
       void compress_data (const dealii::hp::FECollection<dim,spacedim> &fe_collection);
 
       /**
-       * Uncompress the arrays that store dof indices by using a variant
-       * of run-length encoding. See the general documentation of this
-       * class for more information.
+       * Uncompress the arrays that store dof indices by using a variant of
+       * run-length encoding. See the general documentation of this class for
+       * more information.
        *
-       * @param fe_collection The object that can tell us how many
-       * degrees of freedom each of the finite elements has that we
-       * store in this object.
+       * @param fe_collection The object that can tell us how many degrees of
+       * freedom each of the finite elements has that we store in this object.
        */
       template <int dim, int spacedim>
       void uncompress_data (const dealii::hp::FECollection<dim,spacedim> &fe_collection);
 
       /**
-       * Make hp::DoFHandler and its auxiliary class a friend since it
-       * is the class that needs to create these data structures.
+       * Make hp::DoFHandler and its auxiliary class a friend since it is the
+       * class that needs to create these data structures.
        */
       template <int, int> friend class dealii::hp::DoFHandler;
       friend struct dealii::internal::hp::DoFHandler::Implementation;
index 3e8307fcb488f00107c05d425ae443f9df4db14a..8fcc900e6259f6f18a05689ad0ed74343a4758a3 100644 (file)
@@ -29,17 +29,17 @@ namespace hp
 
   /**
    * This class acts as a collection of finite element objects used in the
-   * hp::DoFHandler. It is thus to a hp::DoFHandler what a
-   * FiniteElement is to a ::DoFHandler.
+   * hp::DoFHandler. It is thus to a hp::DoFHandler what a FiniteElement is to
+   * a ::DoFHandler.
    *
-   * It implements the concepts stated in the @ref hpcollection module described
-   * in the doxygen documentation.
+   * It implements the concepts stated in the @ref hpcollection module
+   * described in the doxygen documentation.
    *
    * In addition to offering access to the elements of the collection, this
    * class provides access to the maximal number of degrees of freedom per
-   * vertex, line, etc, to allow allocation of as much memory as is necessary in
-   * the worst case when using the finite elements associated with the cells of
-   * a triangulation.
+   * vertex, line, etc, to allow allocation of as much memory as is necessary
+   * in the worst case when using the finite elements associated with the
+   * cells of a triangulation.
    *
    * This class has not yet been implemented for the use in the codimension
    * one case (<tt>spacedim != dim </tt>).
@@ -53,23 +53,16 @@ namespace hp
   {
   public:
     /**
-     * Default constructor. Leads
-     * to an empty collection that
-     * can later be filled using
-     * push_back().
+     * Default constructor. Leads to an empty collection that can later be
+     * filled using push_back().
      */
     FECollection ();
 
     /**
-     * Conversion constructor. This
-     * constructor creates a
-     * FECollection from a single
-     * finite element. More finite
-     * element objects can be added
-     * with push_back(), if
-     * desired, though it would
-     * probably be clearer to add
-     * all mappings the same way.
+     * Conversion constructor. This constructor creates a FECollection from a
+     * single finite element. More finite element objects can be added with
+     * push_back(), if desired, though it would probably be clearer to add all
+     * mappings the same way.
      */
     explicit FECollection (const FiniteElement<dim,spacedim> &fe);
 
@@ -79,350 +72,294 @@ namespace hp
     FECollection (const FECollection<dim,spacedim> &fe_collection);
 
     /**
-     * Add a finite element. This
-     * function generates a copy of
-     * the given element, i.e. you
-     * can do things like
-     * <tt>push_back(FE_Q<dim>(1));</tt>. The
-     * internal copy is later
-     * destroyed by this object
-     * upon destruction of the
-     * entire collection.
+     * Add a finite element. This function generates a copy of the given
+     * element, i.e. you can do things like <tt>push_back(FE_Q<dim>(1));</tt>.
+     * The internal copy is later destroyed by this object upon destruction of
+     * the entire collection.
      *
-     * When a new element is added,
-     * it needs to have the same
-     * number of vector components
-     * as all other elements
-     * already in the collection.
+     * When a new element is added, it needs to have the same number of vector
+     * components as all other elements already in the collection.
      */
     void push_back (const FiniteElement<dim,spacedim> &new_fe);
 
     /**
-     * Get a reference to the given
-     * element in this collection.
+     * Get a reference to the given element in this collection.
      *
-     * @pre @p index must be
-     * between zero and the number
-     * of elements of the
+     * @pre @p index must be between zero and the number of elements of the
      * collection.
      */
     const FiniteElement<dim,spacedim> &
     operator[] (const unsigned int index) const;
 
     /**
-     * Return the number of finite
-     * element objects stored in
-     * this collection.
+     * Return the number of finite element objects stored in this collection.
      */
     unsigned int size () const;
 
     /**
-     * Return the number of vector
-     * components of the finite elements in
-     * this collection.  This number must
-     * be the same for all elements in the
+     * Return the number of vector components of the finite elements in this
+     * collection.  This number must be the same for all elements in the
      * collection.
-    *
-    * This function calls
-    * FiniteElement::n_components.  See
-    * @ref GlossComponent "the glossary"
-    * for more information.
+     *
+     * This function calls FiniteElement::n_components.  See @ref
+     * GlossComponent "the glossary" for more information.
      */
     unsigned int n_components () const;
 
     /**
-     * Return the number of vector
-     * blocks of the finite elements in
-     * this collection. While this class ensures that all
-     * elements stored in it have the same number of vector
-     * components, there is no such guarantees for the number
-     * of blocks each element is made up of (an element may
-     * have fewer blocks than vector components; see
-     * @ref GlossBlock "the glossary" for more information).
-     * For example, you may have an FECollection object that stores
-     * one copy of an FESystem with <code>dim</code> FE_Q objects
-     * and one copy of an FE_RaviartThomas element. Both have
-     * <code>dim</code> vector components but while the former has
-     * <code>dim</code> blocks the latter has only one.
-     * Consequently, this function will throw an assertion
-     * if the number of blocks is not the same for all elements.
-     * If they are the same, this function returns the result
-     * of FiniteElement::n_blocks().
+     * Return the number of vector blocks of the finite elements in this
+     * collection. While this class ensures that all elements stored in it
+     * have the same number of vector components, there is no such guarantees
+     * for the number of blocks each element is made up of (an element may
+     * have fewer blocks than vector components; see @ref GlossBlock "the
+     * glossary" for more information). For example, you may have an
+     * FECollection object that stores one copy of an FESystem with
+     * <code>dim</code> FE_Q objects and one copy of an FE_RaviartThomas
+     * element. Both have <code>dim</code> vector components but while the
+     * former has <code>dim</code> blocks the latter has only one.
+     * Consequently, this function will throw an assertion if the number of
+     * blocks is not the same for all elements. If they are the same, this
+     * function returns the result of FiniteElement::n_blocks().
      */
     unsigned int n_blocks () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per vertex over all
+     * Return the maximal number of degrees of freedom per vertex over all
      * elements of this collection.
      */
     unsigned int max_dofs_per_vertex () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per line over all elements
-     * of this collection.
+     * Return the maximal number of degrees of freedom per line over all
+     * elements of this collection.
      */
     unsigned int max_dofs_per_line () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per quad over all elements
-     * of this collection.
+     * Return the maximal number of degrees of freedom per quad over all
+     * elements of this collection.
      */
     unsigned int max_dofs_per_quad () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per hex over all elements
-     * of this collection.
+     * Return the maximal number of degrees of freedom per hex over all
+     * elements of this collection.
      */
     unsigned int max_dofs_per_hex () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per face over all elements
-     * of this collection.
+     * Return the maximal number of degrees of freedom per face over all
+     * elements of this collection.
      */
     unsigned int max_dofs_per_face () const;
 
     /**
-     * Return the maximal number of degrees
-     * of freedom per cell over all elements
-     * of this collection.
+     * Return the maximal number of degrees of freedom per cell over all
+     * elements of this collection.
      */
     unsigned int max_dofs_per_cell () const;
 
     /**
-     * Return an estimate for the memory
-     * allocated for this object.
+     * Return an estimate for the memory allocated for this object.
      */
     std::size_t memory_consumption () const;
 
 
     /**
-     * Return whether all elements
-     * in this collection
-     * implement the hanging node
-     * constraints in the new way,
-     * which has to be used to make
-     * elements "hp compatible".
-     * If this is not the case,
-     * the function returns false,
-     * which implies, that at least
-     * one element in the FECollection
-     * does not support the new face
-     * interface constraints.
-     * On the other hand, if this
-     * method does return
-     * true, this does not imply
-     * that the hp method will work!
+     * Return whether all elements in this collection implement the hanging
+     * node constraints in the new way, which has to be used to make elements
+     * "hp compatible". If this is not the case, the function returns false,
+     * which implies, that at least one element in the FECollection does not
+     * support the new face interface constraints. On the other hand, if this
+     * method does return true, this does not imply that the hp method will
+     * work!
      *
-     * This behaviour is related to
-     * the fact, that FiniteElement
-     * classes, which provide the
-     * new style hanging node constraints
-     * might still not provide
-     * them for all possible cases.
-     * If FE_Q and FE_RaviartThomas
-     * elements are included in the
-     * FECollection and both properly implement
-     * the get_face_interpolation_matrix
-     * method, this method will return
-     * true. But the get_face_interpolation_matrix
-     * might still fail to find an interpolation
-     * matrix between these two elements.
+     * This behaviour is related to the fact, that FiniteElement classes,
+     * which provide the new style hanging node constraints might still not
+     * provide them for all possible cases. If FE_Q and FE_RaviartThomas
+     * elements are included in the FECollection and both properly implement
+     * the get_face_interpolation_matrix method, this method will return true.
+     * But the get_face_interpolation_matrix might still fail to find an
+     * interpolation matrix between these two elements.
      */
     bool hp_constraints_are_implemented () const;
 
     /**
-     * Return a component mask with as many elements as this
-     * object has vector components and of which exactly the
-     * one component is true that corresponds to the given
-     * argument.
+     * Return a component mask with as many elements as this object has vector
+     * components and of which exactly the one component is true that
+     * corresponds to the given argument.
      *
      * @note This function is the equivalent of
-     * FiniteElement::component_mask() with the same arguments.
-     * It verifies that it gets the same result from every one
-     * of the elements that are stored in this FECollection. If
-     * this is not the case, it throws an exception.
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
      *
-     * @param scalar An object that represents a single scalar
-     * vector component of this finite element.
-     * @return A component mask that is false in all components
-     * except for the one that corresponds to the argument.
+     * @param scalar An object that represents a single scalar vector
+     * component of this finite element. @return A component mask that is
+     * false in all components except for the one that corresponds to the
+     * argument.
      */
     ComponentMask
     component_mask (const FEValuesExtractors::Scalar &scalar) const;
 
     /**
-     * Return a component mask with as many elements as this
-     * object has vector components and of which exactly the
-     * <code>dim</code> components are true that correspond to the given
-     * argument.
+     * Return a component mask with as many elements as this object has vector
+     * components and of which exactly the <code>dim</code> components are
+     * true that correspond to the given argument.
      *
      * @note This function is the equivalent of
-     * FiniteElement::component_mask() with the same arguments.
-     * It verifies that it gets the same result from every one
-     * of the elements that are stored in this FECollection. If
-     * this is not the case, it throws an exception.
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
      *
-     * @param vector An object that represents dim
-     * vector components of this finite element.
-     * @return A component mask that is false in all components
-     * except for the ones that corresponds to the argument.
+     * @param vector An object that represents dim vector components of this
+     * finite element. @return A component mask that is false in all
+     * components except for the ones that corresponds to the argument.
      */
     ComponentMask
     component_mask (const FEValuesExtractors::Vector &vector) const;
 
     /**
-     * Return a component mask with as many elements as this
-     * object has vector components and of which exactly the
-     * <code>dim*(dim+1)/2</code> components are true that
-     * correspond to the given argument.
+     * Return a component mask with as many elements as this object has vector
+     * components and of which exactly the <code>dim*(dim+1)/2</code>
+     * components are true that correspond to the given argument.
      *
      * @note This function is the equivalent of
-     * FiniteElement::component_mask() with the same arguments.
-     * It verifies that it gets the same result from every one
-     * of the elements that are stored in this FECollection. If
-     * this is not the case, it throws an exception.
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
      *
-     * @param sym_tensor An object that represents dim*(dim+1)/2
-     * components of this finite element that are jointly to be
-     * interpreted as forming a symmetric tensor.
-     * @return A component mask that is false in all components
-     * except for the ones that corresponds to the argument.
+     * @param sym_tensor An object that represents dim*(dim+1)/2 components of
+     * this finite element that are jointly to be interpreted as forming a
+     * symmetric tensor. @return A component mask that is false in all
+     * components except for the ones that corresponds to the argument.
      */
     ComponentMask
     component_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
 
     /**
-    * Given a block mask (see @ref GlossBlockMask "this glossary entry"),
-    * produce a component mask (see @ref GlossComponentMask "this glossary entry")
-    * that represents the components that correspond to the blocks selected in
-    * the input argument. This is essentially a conversion operator from
-    * BlockMask to ComponentMask.
-    *
-    * @note This function is the equivalent of
-    * FiniteElement::component_mask() with the same arguments.
-    * It verifies that it gets the same result from every one
-    * of the elements that are stored in this FECollection. If
-    * this is not the case, it throws an exception.
-    *
-    * @param block_mask The mask that selects individual blocks of the finite
-    * element
-    * @return A mask that selects those components corresponding to the selected
-    * blocks of the input argument.
-    */
+     * Given a block mask (see @ref GlossBlockMask "this glossary entry"),
+     * produce a component mask (see @ref GlossComponentMask "this glossary
+     * entry") that represents the components that correspond to the blocks
+     * selected in the input argument. This is essentially a conversion
+     * operator from BlockMask to ComponentMask.
+     *
+     * @note This function is the equivalent of
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
+     *
+     * @param block_mask The mask that selects individual blocks of the finite
+     * element @return A mask that selects those components corresponding to
+     * the selected blocks of the input argument.
+     */
     ComponentMask
     component_mask (const BlockMask &block_mask) const;
 
     /**
-    * Return a block mask with as many elements as this
-    * object has blocks and of which exactly the
-    * one component is true that corresponds to the given
-    * argument. See @ref GlossBlockMask "the glossary"
-    * for more information.
-    *
-    * @note This function will only succeed if the scalar referenced
-    * by the argument encompasses a complete block. In other words,
-    * if, for example, you pass an extractor for the single
-    * $x$ velocity and this object represents an FE_RaviartThomas
-    * object, then the single scalar object you selected is part
-    * of a larger block and consequently there is no block mask that
-    * would represent it. The function will then produce an exception.
-    *
-    * @note This function is the equivalent of
-    * FiniteElement::component_mask() with the same arguments.
-    * It verifies that it gets the same result from every one
-    * of the elements that are stored in this FECollection. If
-    * this is not the case, it throws an exception.
-    *
-    * @param scalar An object that represents a single scalar
-    * vector component of this finite element.
-    * @return A component mask that is false in all components
-    * except for the one that corresponds to the argument.
-    */
+     * Return a block mask with as many elements as this object has blocks and
+     * of which exactly the one component is true that corresponds to the
+     * given argument. See @ref GlossBlockMask "the glossary" for more
+     * information.
+     *
+     * @note This function will only succeed if the scalar referenced by the
+     * argument encompasses a complete block. In other words, if, for example,
+     * you pass an extractor for the single $x$ velocity and this object
+     * represents an FE_RaviartThomas object, then the single scalar object
+     * you selected is part of a larger block and consequently there is no
+     * block mask that would represent it. The function will then produce an
+     * exception.
+     *
+     * @note This function is the equivalent of
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
+     *
+     * @param scalar An object that represents a single scalar vector
+     * component of this finite element. @return A component mask that is
+     * false in all components except for the one that corresponds to the
+     * argument.
+     */
     BlockMask
     block_mask (const FEValuesExtractors::Scalar &scalar) const;
 
     /**
-    * Return a component mask with as many elements as this
-    * object has vector components and of which exactly the
-    * <code>dim</code> components are true that correspond to the given
-    * argument. See @ref GlossBlockMask "the glossary"
-    * for more information.
-    *
-    * @note This function is the equivalent of
-    * FiniteElement::component_mask() with the same arguments.
-    * It verifies that it gets the same result from every one
-    * of the elements that are stored in this FECollection. If
-    * this is not the case, it throws an exception.
-    *
-    * @note The same caveat applies as to the version of the function above:
-    * The extractor object passed as argument must be so that it corresponds
-    * to full blocks and does not split blocks of this element.
-    *
-    * @param vector An object that represents dim
-    * vector components of this finite element.
-    * @return A component mask that is false in all components
-    * except for the ones that corresponds to the argument.
-    */
+     * Return a component mask with as many elements as this object has vector
+     * components and of which exactly the <code>dim</code> components are
+     * true that correspond to the given argument. See @ref GlossBlockMask
+     * "the glossary" for more information.
+     *
+     * @note This function is the equivalent of
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
+     *
+     * @note The same caveat applies as to the version of the function above:
+     * The extractor object passed as argument must be so that it corresponds
+     * to full blocks and does not split blocks of this element.
+     *
+     * @param vector An object that represents dim vector components of this
+     * finite element. @return A component mask that is false in all
+     * components except for the ones that corresponds to the argument.
+     */
     BlockMask
     block_mask (const FEValuesExtractors::Vector &vector) const;
 
     /**
-    * Return a component mask with as many elements as this
-    * object has vector components and of which exactly the
-    * <code>dim*(dim+1)/2</code> components are true that
-    * correspond to the given argument. See @ref GlossBlockMask "the glossary"
-    * for more information.
-    *
-    * @note The same caveat applies as to the version of the function above:
-    * The extractor object passed as argument must be so that it corresponds
-    * to full blocks and does not split blocks of this element.
-    *
-    * @note This function is the equivalent of
-    * FiniteElement::component_mask() with the same arguments.
-    * It verifies that it gets the same result from every one
-    * of the elements that are stored in this FECollection. If
-    * this is not the case, it throws an exception.
-    *
-    * @param sym_tensor An object that represents dim*(dim+1)/2
-    * components of this finite element that are jointly to be
-    * interpreted as forming a symmetric tensor.
-    * @return A component mask that is false in all components
-    * except for the ones that corresponds to the argument.
-    */
+     * Return a component mask with as many elements as this object has vector
+     * components and of which exactly the <code>dim*(dim+1)/2</code>
+     * components are true that correspond to the given argument. See @ref
+     * GlossBlockMask "the glossary" for more information.
+     *
+     * @note The same caveat applies as to the version of the function above:
+     * The extractor object passed as argument must be so that it corresponds
+     * to full blocks and does not split blocks of this element.
+     *
+     * @note This function is the equivalent of
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
+     *
+     * @param sym_tensor An object that represents dim*(dim+1)/2 components of
+     * this finite element that are jointly to be interpreted as forming a
+     * symmetric tensor. @return A component mask that is false in all
+     * components except for the ones that corresponds to the argument.
+     */
     BlockMask
     block_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
 
     /**
-    * Given a component mask (see @ref GlossComponentMask "this glossary entry"),
-    * produce a block mask (see @ref GlossBlockMask "this glossary entry")
-    * that represents the blocks that correspond to the components selected in
-    * the input argument. This is essentially a conversion operator from
-    * ComponentMask to BlockMask.
-    *
-    * @note This function will only succeed if the components referenced
-    * by the argument encompasses complete blocks. In other words,
-    * if, for example, you pass an component mask for the single
-    * $x$ velocity and this object represents an FE_RaviartThomas
-    * object, then the single component you selected is part
-    * of a larger block and consequently there is no block mask that
-    * would represent it. The function will then produce an exception.
-    *
-    * @note This function is the equivalent of
-    * FiniteElement::component_mask() with the same arguments.
-    * It verifies that it gets the same result from every one
-    * of the elements that are stored in this FECollection. If
-    * this is not the case, it throws an exception.
-    *
-    * @param component_mask The mask that selects individual components of the finite
-    * element
-    * @return A mask that selects those blocks corresponding to the selected
-    * blocks of the input argument.
-    */
+     * Given a component mask (see @ref GlossComponentMask "this glossary
+     * entry"), produce a block mask (see @ref GlossBlockMask "this glossary
+     * entry") that represents the blocks that correspond to the components
+     * selected in the input argument. This is essentially a conversion
+     * operator from ComponentMask to BlockMask.
+     *
+     * @note This function will only succeed if the components referenced by
+     * the argument encompasses complete blocks. In other words, if, for
+     * example, you pass an component mask for the single $x$ velocity and
+     * this object represents an FE_RaviartThomas object, then the single
+     * component you selected is part of a larger block and consequently there
+     * is no block mask that would represent it. The function will then
+     * produce an exception.
+     *
+     * @note This function is the equivalent of
+     * FiniteElement::component_mask() with the same arguments. It verifies
+     * that it gets the same result from every one of the elements that are
+     * stored in this FECollection. If this is not the case, it throws an
+     * exception.
+     *
+     * @param component_mask The mask that selects individual components of
+     * the finite element @return A mask that selects those blocks
+     * corresponding to the selected blocks of the input argument.
+     */
     BlockMask
     block_mask (const ComponentMask &component_mask) const;
 
@@ -434,8 +371,7 @@ namespace hp
 
   private:
     /**
-     * Array of pointers to the finite
-     * elements stored by this collection.
+     * Array of pointers to the finite elements stored by this collection.
      */
     std::vector<std_cxx11::shared_ptr<const FiniteElement<dim,spacedim> > > finite_elements;
   };
index 6ea336c675f226d5d2d0d978a580498273d01c5f..f0d8f8280f8632f81d22dbb17a84f17ccf0c11f5 100644 (file)
@@ -41,18 +41,17 @@ namespace internal
      * Base class for the <tt>hp::FE*Values</tt> classes, storing the data
      * that is common to them. The main task of this class is to provide a
      * table where for every combination of finite element, mapping, and
-     * quadrature object from their corresponding collection objects there
-     * is a matching ::FEValues, ::FEFaceValues, or ::FESubfaceValues
-     * object. To make things more efficient, however, these FE*Values
-     * objects are only created once requested (lazy allocation).
+     * quadrature object from their corresponding collection objects there is
+     * a matching ::FEValues, ::FEFaceValues, or ::FESubfaceValues object. To
+     * make things more efficient, however, these FE*Values objects are only
+     * created once requested (lazy allocation).
      *
-     * The first template parameter denotes the space dimension we are in,
-     * the second the dimensionality of the object that we integrate on,
-     * i.e. for usual @p hp::FEValues it is equal to the first one, while
-     * for face integration it is one less. The third template parameter
-     * indicates the type of underlying non-hp FE*Values base type,
-     * i.e. it could either be dealii::FEValues, dealii::FEFaceValues, or
-     * dealii::FESubfaceValues.
+     * The first template parameter denotes the space dimension we are in, the
+     * second the dimensionality of the object that we integrate on, i.e. for
+     * usual @p hp::FEValues it is equal to the first one, while for face
+     * integration it is one less. The third template parameter indicates the
+     * type of underlying non-hp FE*Values base type, i.e. it could either be
+     * dealii::FEValues, dealii::FEFaceValues, or dealii::FESubfaceValues.
      *
      * @ingroup hp
      *
@@ -87,15 +86,13 @@ namespace internal
       get_fe_collection () const;
 
       /**
-       * Get a reference to the collection of mapping objects used
-       * here.
+       * Get a reference to the collection of mapping objects used here.
        */
       const dealii::hp::MappingCollection<dim,FEValues::space_dimension> &
       get_mapping_collection () const;
 
       /**
-       * Get a reference to the collection of quadrature objects used
-       * here.
+       * Get a reference to the collection of quadrature objects used here.
        */
       const dealii::hp::QCollection<q_dim> &
       get_quadrature_collection () const;
@@ -148,11 +145,11 @@ namespace internal
     private:
       /**
        * A table in which we store pointers to fe_values objects for different
-       * finite element, mapping, and quadrature objects from our
-       * collection. The first index indicates the index of the finite element
-       * within the fe_collection, the second the index of the mapping within
-       * the mapping collection, and the last one the index of the quadrature
-       * formula within the q_collection.
+       * finite element, mapping, and quadrature objects from our collection.
+       * The first index indicates the index of the finite element within the
+       * fe_collection, the second the index of the mapping within the mapping
+       * collection, and the last one the index of the quadrature formula
+       * within the q_collection.
        *
        * Initially, all entries have zero pointers, and we will allocate them
        * lazily as needed in select_fe_values().
@@ -180,44 +177,46 @@ namespace hp
 {
 
   /**
-   * An hp equivalent of the ::FEValues class. See the step-27
-   * tutorial program for examples of use.
+   * An hp equivalent of the ::FEValues class. See the step-27 tutorial
+   * program for examples of use.
    *
-   * The idea of this class is as follows: when one assembled matrices in the hp
-   * finite element method, there may be different finite elements on different
-   * cells, and consequently one may also want to use different quadrature
-   * formulas for different cells. On the other hand, the ::FEValues efficiently
-   * handles pre-evaluating whatever information is necessary for a single
-   * finite element and quadrature object. This class brings these concepts
-   * together: it provides a "collection" of ::FEValues objects.
+   * The idea of this class is as follows: when one assembled matrices in the
+   * hp finite element method, there may be different finite elements on
+   * different cells, and consequently one may also want to use different
+   * quadrature formulas for different cells. On the other hand, the
+   * ::FEValues efficiently handles pre-evaluating whatever information is
+   * necessary for a single finite element and quadrature object. This class
+   * brings these concepts together: it provides a "collection" of ::FEValues
+   * objects.
    *
-   * Upon construction, one passes not one finite element and quadrature object
-   * (and possible a mapping), but a whole collection of type hp::FECollection
-   * and hp::QCollection. Later on, when one sits on a concrete cell, one would
-   * call the reinit() function for this particular cell, just as one does for a
-   * regular ::FEValues object. The difference is that this time, the reinit()
-   * function looks up the active_fe_index of that cell, if necessary creates a
-   * ::FEValues object that matches the finite element and quadrature formulas
-   * with that particular index in their collections, and then re-initializes it
-   * for the current cell. The ::FEValues object that then fits the finite
-   * element and quadrature formula for the current cell can then be accessed
-   * using the get_present_fe_values() function, and one would work with it just
-   * like with any ::FEValues object for non-hp DoF handler objects.
+   * Upon construction, one passes not one finite element and quadrature
+   * object (and possible a mapping), but a whole collection of type
+   * hp::FECollection and hp::QCollection. Later on, when one sits on a
+   * concrete cell, one would call the reinit() function for this particular
+   * cell, just as one does for a regular ::FEValues object. The difference is
+   * that this time, the reinit() function looks up the active_fe_index of
+   * that cell, if necessary creates a ::FEValues object that matches the
+   * finite element and quadrature formulas with that particular index in
+   * their collections, and then re-initializes it for the current cell. The
+   * ::FEValues object that then fits the finite element and quadrature
+   * formula for the current cell can then be accessed using the
+   * get_present_fe_values() function, and one would work with it just like
+   * with any ::FEValues object for non-hp DoF handler objects.
    *
    * The reinit() functions have additional arguments with default values. If
    * not specified, the function takes the index into the hp::FECollection,
-   * hp::QCollection, and hp::MappingCollection objects from the active_fe_index
-   * of the cell, as explained above. However, one can also select different
-   * indices for a current cell. For example, by specifying a different index
-   * into the hp::QCollection class, one does not need to sort the quadrature
-   * objects in the quadrature collection so that they match one-to-one the
-   * order of finite element objects in the FE collection (even though choosing
-   * such an order is certainly convenient).
+   * hp::QCollection, and hp::MappingCollection objects from the
+   * active_fe_index of the cell, as explained above. However, one can also
+   * select different indices for a current cell. For example, by specifying a
+   * different index into the hp::QCollection class, one does not need to sort
+   * the quadrature objects in the quadrature collection so that they match
+   * one-to-one the order of finite element objects in the FE collection (even
+   * though choosing such an order is certainly convenient).
    *
-   * Note that ::FEValues objects are created on the fly, i.e. only as they are
-   * needed. This ensures that we do not create objects for every combination of
-   * finite element, quadrature formula and mapping, but only those that will
-   * actually be needed.
+   * Note that ::FEValues objects are created on the fly, i.e. only as they
+   * are needed. This ensures that we do not create objects for every
+   * combination of finite element, quadrature formula and mapping, but only
+   * those that will actually be needed.
    *
    * This class has not yet been implemented for the use in the codimension
    * one case (<tt>spacedim != dim </tt>).
@@ -268,12 +267,12 @@ namespace hp
      * Reinitialize the object for the given cell.
      *
      * After the call, you can get an FEValues object using the
-     * get_present_fe_values() function that corresponds to the present
-     * cell. For this FEValues object, we use the additional arguments
-     * described below to determine which finite element, mapping, and
-     * quadrature formula to use. They are order in such a way that the
-     * arguments one may want to change most frequently come first. The rules
-     * for these arguments are as follows:
+     * get_present_fe_values() function that corresponds to the present cell.
+     * For this FEValues object, we use the additional arguments described
+     * below to determine which finite element, mapping, and quadrature
+     * formula to use. They are order in such a way that the arguments one may
+     * want to change most frequently come first. The rules for these
+     * arguments are as follows:
      *
      * If the @p fe_index argument to this function is left at its default
      * value, then we use that finite element within the hp::FECollection
@@ -343,8 +342,9 @@ namespace hp
 
 
   /**
-   * This is the equivalent of the hp::FEValues class but for face integrations,
-   * i.e. it is to hp::FEValues what ::FEFaceValues is to ::FEValues.
+   * This is the equivalent of the hp::FEValues class but for face
+   * integrations, i.e. it is to hp::FEValues what ::FEFaceValues is to
+   * ::FEValues.
    *
    * The same comments apply as in the documentation of the hp::FEValues
    * class. However, it is important to note that it is here more common that
@@ -402,12 +402,12 @@ namespace hp
      * Reinitialize the object for the given cell and face.
      *
      * After the call, you can get an FEFaceValues object using the
-     * get_present_fe_values() function that corresponds to the present
-     * cell. For this FEFaceValues object, we use the additional arguments
-     * described below to determine which finite element, mapping, and
-     * quadrature formula to use. They are order in such a way that the
-     * arguments one may want to change most frequently come first. The rules
-     * for these arguments are as follows:
+     * get_present_fe_values() function that corresponds to the present cell.
+     * For this FEFaceValues object, we use the additional arguments described
+     * below to determine which finite element, mapping, and quadrature
+     * formula to use. They are order in such a way that the arguments one may
+     * want to change most frequently come first. The rules for these
+     * arguments are as follows:
      *
      * If the @p fe_index argument to this function is left at its default
      * value, then we use that finite element within the hp::FECollection
@@ -477,8 +477,8 @@ namespace hp
 
 
   /**
-   * This class implements for subfaces what hp::FEFaceValues does for
-   * faces. See there for further documentation.
+   * This class implements for subfaces what hp::FEFaceValues does for faces.
+   * See there for further documentation.
    *
    * @ingroup hp hpcollection
    * @author Wolfgang Bangerth, 2003
@@ -520,8 +520,8 @@ namespace hp
      * Reinitialize the object for the given cell, face, and subface.
      *
      * After the call, you can get an FESubfaceValues object using the
-     * get_present_fe_values() function that corresponds to the present
-     * cell. For this FESubfaceValues object, we use the additional arguments
+     * get_present_fe_values() function that corresponds to the present cell.
+     * For this FESubfaceValues object, we use the additional arguments
      * described below to determine which finite element, mapping, and
      * quadrature formula to use. They are order in such a way that the
      * arguments one may want to change most frequently come first. The rules
index 22699e75c2b2a473e0d832ec34b53599a3cf3574..f81dcd2a25f186c2b2797dd728717840f86cdcd7 100644 (file)
@@ -32,20 +32,18 @@ namespace hp
    * This class implements a collection of mapping objects in the same way as
    * the hp::FECollection implements a collection of finite element classes.
    *
-   * It implements the concepts stated in the @ref hpcollection module described
-   * in the doxygen documentation.
+   * It implements the concepts stated in the @ref hpcollection module
+   * described in the doxygen documentation.
    *
-   * Although it is recommended to supply an appropriate mapping for
-   * each finite element kind used in a hp-computation, the
-   * MappingCollection class implements a conversion constructor from a
-   * single mapping.  Therefore it is possible to offer only a single
-   * mapping to the hp::FEValues class instead of a
-   * hp::MappingCollection. This is for the convenience of the user, as
-   * many simple geometries do not require different mappings along the
-   * boundary to achieve optimal convergence rates.  Hence providing a
-   * single mapping object will usually suffice. See the hp::FEValues
-   * class for the rules which mapping will be selected for a given
-   * cell.
+   * Although it is recommended to supply an appropriate mapping for each
+   * finite element kind used in a hp-computation, the MappingCollection class
+   * implements a conversion constructor from a single mapping.  Therefore it
+   * is possible to offer only a single mapping to the hp::FEValues class
+   * instead of a hp::MappingCollection. This is for the convenience of the
+   * user, as many simple geometries do not require different mappings along
+   * the boundary to achieve optimal convergence rates.  Hence providing a
+   * single mapping object will usually suffice. See the hp::FEValues class
+   * for the rules which mapping will be selected for a given cell.
    *
    * @ingroup hp hpcollection
    *
@@ -56,23 +54,16 @@ namespace hp
   {
   public:
     /**
-     * Default constructor. Leads
-     * to an empty collection that
-     * can later be filled using
-     * push_back().
+     * Default constructor. Leads to an empty collection that can later be
+     * filled using push_back().
      */
     MappingCollection ();
 
     /**
-     * Conversion constructor. This
-     * constructor creates a
-     * MappingCollection from a
-     * single mapping. More
-     * mappings can be added with
-     * push_back(), if desired,
-     * though it would probably be
-     * clearer to add all mappings
-     * the same way.
+     * Conversion constructor. This constructor creates a MappingCollection
+     * from a single mapping. More mappings can be added with push_back(), if
+     * desired, though it would probably be clearer to add all mappings the
+     * same way.
      */
     explicit MappingCollection (const Mapping<dim,spacedim> &mapping);
 
@@ -82,53 +73,37 @@ namespace hp
     MappingCollection (const MappingCollection<dim,spacedim> &mapping_collection);
 
     /**
-     * Adds a new mapping to the
-     * MappingCollection.  The
-     * mappings have to be added in
-     * the order of the
-     * active_fe_indices. Thus the
-     * reference to the mapping
-     * object for active_fe_index 0
-     * has to be added first,
-     * followed by the mapping
-     * object for active_fe_index
-     * 1.
+     * Adds a new mapping to the MappingCollection.  The mappings have to be
+     * added in the order of the active_fe_indices. Thus the reference to the
+     * mapping object for active_fe_index 0 has to be added first, followed by
+     * the mapping object for active_fe_index 1.
      */
     void push_back (const Mapping<dim,spacedim> &new_mapping);
 
     /**
-     * Returns the mapping object
-     * which was specified by the
-     * user for the active_fe_index
-     * which is provided as a
-     * parameter to this method.
+     * Returns the mapping object which was specified by the user for the
+     * active_fe_index which is provided as a parameter to this method.
      *
-     * @pre @p index must be
-     * between zero and the number
-     * of elements of the
+     * @pre @p index must be between zero and the number of elements of the
      * collection.
      */
     const Mapping<dim,spacedim> &
     operator[] (const unsigned int index) const;
 
     /**
-     * Returns the number of
-     * mapping objects stored in
-     * this container.
+     * Returns the number of mapping objects stored in this container.
      */
     unsigned int size () const;
 
     /**
-     * Determine an estimate for the
-     * memory consumption (in bytes)
-     * of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
   private:
     /**
-     * The real container, which stores
-     * pointers to the different Mapping
+     * The real container, which stores pointers to the different Mapping
      * objects.
      */
     std::vector<std_cxx11::shared_ptr<const Mapping<dim,spacedim> > > mappings;
@@ -136,10 +111,9 @@ namespace hp
 
 
   /**
-   * In order to avoid creation of static MappingQ1 objects at several
-   * places in the library, this class
-   * defines a static collection of mappings with a single
-   * MappingQ1 mapping object once and for all places where it is
+   * In order to avoid creation of static MappingQ1 objects at several places
+   * in the library, this class defines a static collection of mappings with a
+   * single MappingQ1 mapping object once and for all places where it is
    * needed.
    */
   template<int dim, int spacedim=dim>
@@ -147,9 +121,7 @@ namespace hp
   {
   public:
     /**
-     * The publicly available
-     * static Q1 mapping collection
-     * object.
+     * The publicly available static Q1 mapping collection object.
      */
     static MappingCollection<dim,spacedim> mapping_collection;
   };
index bed5ae27cd6108c21d84f18931678bbe93a87437..270060b9b8e06153ce4266adf8664b64387159dd 100644 (file)
@@ -30,11 +30,12 @@ DEAL_II_NAMESPACE_OPEN
 namespace hp
 {
   /**
-   * This class implements a collection of quadrature objects in the same way as
-   * the hp::FECollection implements a collection of finite element classes.
+   * This class implements a collection of quadrature objects in the same way
+   * as the hp::FECollection implements a collection of finite element
+   * classes.
    *
-   * It implements the concepts stated in the @ref hpcollection module described
-   * in the doxygen documentation.
+   * It implements the concepts stated in the @ref hpcollection module
+   * described in the doxygen documentation.
    *
    * @ingroup hp hpcollection
    *
@@ -45,23 +46,16 @@ namespace hp
   {
   public:
     /**
-     * Default constructor. Leads
-     * to an empty collection that
-     * can later be filled using
-     * push_back().
+     * Default constructor. Leads to an empty collection that can later be
+     * filled using push_back().
      */
     QCollection ();
 
     /**
-     * Conversion constructor. This
-     * constructor creates a
-     * QCollection from a single
-     * quadrature rule. More
-     * quadrature formulas can be
-     * added with push_back(), if
-     * desired, though it would
-     * probably be clearer to add
-     * all mappings the same way.
+     * Conversion constructor. This constructor creates a QCollection from a
+     * single quadrature rule. More quadrature formulas can be added with
+     * push_back(), if desired, though it would probably be clearer to add all
+     * mappings the same way.
      */
     explicit QCollection (const Quadrature<dim> &quadrature);
 
@@ -71,69 +65,44 @@ namespace hp
     QCollection (const QCollection<dim> &q_collection);
 
     /**
-     * Adds a new quadrature rule
-     * to the QCollection.  The
-     * quadrature rules have to be
-     * added in the same order as
-     * for the FECollection for
-     * which this quadrature rule
-     * collection is meant. Thus
-     * the reference to the
-     * quadrature rule for
-     * active_fe_index 0 has to be
-     * added first, followed by the
-     * quadrature rule for
-     * active_fe_index 1.
+     * Adds a new quadrature rule to the QCollection.  The quadrature rules
+     * have to be added in the same order as for the FECollection for which
+     * this quadrature rule collection is meant. Thus the reference to the
+     * quadrature rule for active_fe_index 0 has to be added first, followed
+     * by the quadrature rule for active_fe_index 1.
      *
-     * This class creates a copy of
-     * the given quadrature object,
-     * i.e. you can do things like
-     * <tt>push_back(QGauss<dim>(3));</tt>. The
-     * internal copy is later
-     * destroyed by this object
-     * upon destruction of the
-     * entire collection.
+     * This class creates a copy of the given quadrature object, i.e. you can
+     * do things like <tt>push_back(QGauss<dim>(3));</tt>. The internal copy
+     * is later destroyed by this object upon destruction of the entire
+     * collection.
      */
     void push_back (const Quadrature<dim> &new_quadrature);
 
     /**
-     * Returns a reference to the
-     * quadrature rule specified by the
-     * argument.
+     * Returns a reference to the quadrature rule specified by the argument.
      *
-     * @pre @p index must be between zero
-     * and the number of elements of the
+     * @pre @p index must be between zero and the number of elements of the
      * collection.
      */
     const Quadrature<dim> &
     operator[] (const unsigned int index) const;
 
     /**
-     * Returns the number of
-     * quadrature pointers stored
-     * in this object.
+     * Returns the number of quadrature pointers stored in this object.
      */
     unsigned int size () const;
 
     /**
-     * Return the maximum number of
-     * quadrature points over all
-     * the elements of the
-     * collection. This is mostly
-     * useful to initialize arrays
-     * to allocate the maxmimum
-     * amount of memory that may be
-     * used when re-sizing later on
-     * to a articular quadrature
-     * formula from within this
-     * collection.
+     * Return the maximum number of quadrature points over all the elements of
+     * the collection. This is mostly useful to initialize arrays to allocate
+     * the maxmimum amount of memory that may be used when re-sizing later on
+     * to a articular quadrature formula from within this collection.
      */
     unsigned int max_n_quadrature_points () const;
 
     /**
-     * Determine an estimate for the
-     * memory consumption (in bytes)
-     * of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
@@ -144,8 +113,7 @@ namespace hp
 
   private:
     /**
-     * The real container, which stores
-     * pointers to the different quadrature
+     * The real container, which stores pointers to the different quadrature
      * objects.
      */
     std::vector<std_cxx11::shared_ptr<const Quadrature<dim> > > quadratures;
index dab64e21e9a7603078d174a2b5cde2c690d9bc3e..d0eddd3c64745065d2fdffc16046e390096afbf0 100644 (file)
@@ -30,15 +30,16 @@ DEAL_II_NAMESPACE_OPEN
 namespace LocalIntegrators
 {
   /**
-   * @brief Local integrators related to advection along a vector field and its DG formulations
+   * @brief Local integrators related to advection along a vector field and
+   * its DG formulations
    *
    * All advection operators depend on an advection velocity denoted by
-   * <b>w</b> in the formulas below. It is denoted as <tt>velocity</tt>
-   * in the parameter lists.
+   * <b>w</b> in the formulas below. It is denoted as <tt>velocity</tt> in the
+   * parameter lists.
    *
-   * The functions cell_matrix() and both upwind_value_matrix() are
-   * taking the equation in weak form, that is, the directional
-   * derivative is on the test function.
+   * The functions cell_matrix() and both upwind_value_matrix() are taking the
+   * equation in weak form, that is, the directional derivative is on the test
+   * function.
    *
    * @ingroup Integrators
    * @author Guido Kanschat
@@ -47,26 +48,24 @@ namespace LocalIntegrators
   namespace Advection
   {
     /**
-     * Advection along the direction <b>w</b> in weak form
-     * with derivative on the test function
-     * \f[
-     * m_{ij} = \int_Z u_j\,(\mathbf w \cdot \nabla) v_i \, dx.
-     * \f]
+     * Advection along the direction <b>w</b> in weak form with derivative on
+     * the test function \f[ m_{ij} = \int_Z u_j\,(\mathbf w \cdot \nabla) v_i
+     * \, dx. \f]
      *
-     * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In
-     * the latter case, the advection operator is applied to each component
+     * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In the
+     * latter case, the advection operator is applied to each component
      * separately.
      *
      * @param M: The advection matrix obtained as result
      * @param fe: The FEValues object describing the local trial function
      * space. #update_values and #update_gradients, and #update_JxW_values
      * must be set.
-     * @param fetest: The FEValues object describing the local test
-     * function space. #update_values and #update_gradients must be set.
+     * @param fetest: The FEValues object describing the local test function
+     * space. #update_values and #update_gradients must be set.
      * @param velocity: The advection velocity, a vector of dimension
-     * <tt>dim</tt>. Each component may either contain a vector of length
-     * one, in which case a constant velocity is assumed, or a vector with
-     * as many entries as quadrature points if the velocity is not constant.
+     * <tt>dim</tt>. Each component may either contain a vector of length one,
+     * in which case a constant velocity is assumed, or a vector with as many
+     * entries as quadrature points if the velocity is not constant.
      * @param factor is an optional multiplication factor for the result.
      *
      * @author Guido Kanschat
@@ -121,9 +120,7 @@ namespace LocalIntegrators
     /**
      * Advection residual operator in strong form
      *
-     * \f[
-     * r_i = \int_Z  (\mathbf w \cdot \nabla)u\, v_i \, dx.
-     * \f]
+     * \f[ r_i = \int_Z  (\mathbf w \cdot \nabla)u\, v_i \, dx. \f]
      */
     template <int dim>
     inline void
@@ -161,9 +158,8 @@ namespace LocalIntegrators
      * Vector-valued advection residual operator in strong form
      *
      *
-     * \f[
-     * r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr) \cdot\mathbf v_i \, dx.
-     * \f]
+     * \f[ r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr)
+     * \cdot\mathbf v_i \, dx. \f]
      */
     template <int dim>
     inline void
@@ -200,33 +196,21 @@ namespace LocalIntegrators
     }
 
     /**
-     * Upwind flux at the boundary
-     * for weak advection
-     * operator. This is the value of
-     * the trial function at the
-     * outflow boundary and zero
-     * else:
+     * Upwind flux at the boundary for weak advection operator. This is the
+     * value of the trial function at the outflow boundary and zero else:
      * @f[
      * a_{ij} = \int_{\partial\Omega}
      * [\mathbf w\cdot\mathbf n]_+
      * u_i v_j \, ds
      * @f]
      *
-     * The <tt>velocity</tt> is
-     * provided as a VectorSlice,
-     * having <tt>dim</tt> vectors,
-     * one for each velocity
-     * component. Each of the
-     * vectors must either have only
-     * a single entry, if t he
-     * advection velocity is
-     * constant, or have an entry
-     * for each quadrature point.
+     * The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
+     * vectors, one for each velocity component. Each of the vectors must
+     * either have only a single entry, if t he advection velocity is
+     * constant, or have an entry for each quadrature point.
      *
-     * The finite element can have
-     * several components, in which
-     * case each component is
-     * advected by the same velocity.
+     * The finite element can have several components, in which case each
+     * component is advected by the same velocity.
      */
     template <int dim>
     void upwind_value_matrix(
@@ -274,37 +258,25 @@ namespace LocalIntegrators
     }
 
     /**
-    * Upwind flux in the interior
-    * for weak advection
-    * operator. Matrix entries
-    * correspond to the upwind value
-    * of the trial function, multiplied
-    * by the jump of the test
-    * functions
-    * @f[
-    * a_{ij} = \int_F \left|\mathbf w
-    * \cdot \mathbf n\right|
-    * u^\uparrow
-    * (v^\uparrow-v^\downarrow)
-    * \,ds
-    * @f]
-    *
-    * The <tt>velocity</tt> is
-    * provided as a VectorSlice,
-    * having <tt>dim</tt> vectors,
-    * one for each velocity
-    * component. Each of the
-    * vectors must either have only
-    * a single entry, if t he
-    * advection velocity is
-    * constant, or have an entry
-    * for each quadrature point.
-    *
-    * The finite element can have
-    * several components, in which
-    * case each component is
-    * advected the same way.
-    */
+     * Upwind flux in the interior for weak advection operator. Matrix entries
+     * correspond to the upwind value of the trial function, multiplied by the
+     * jump of the test functions
+     * @f[
+     * a_{ij} = \int_F \left|\mathbf w
+     * \cdot \mathbf n\right|
+     * u^\uparrow
+     * (v^\uparrow-v^\downarrow)
+     * \,ds
+     * @f]
+     *
+     * The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
+     * vectors, one for each velocity component. Each of the vectors must
+     * either have only a single entry, if t he advection velocity is
+     * constant, or have an entry for each quadrature point.
+     *
+     * The finite element can have several components, in which case each
+     * component is advected the same way.
+     */
     template <int dim>
     void upwind_value_matrix (
       FullMatrix<double> &M11,
index b18999688f132791ef718904ccff8f19dfe7169c..1bd83ff06ee94e6c0e6d327b63329d65047d218a 100644 (file)
@@ -30,7 +30,8 @@ DEAL_II_NAMESPACE_OPEN
 namespace LocalIntegrators
 {
   /**
-   * @brief Local integrators related to the divergence operator and its trace.
+   * @brief Local integrators related to the divergence operator and its
+   * trace.
    *
    * @ingroup Integrators
    * @author Guido Kanschat
@@ -42,8 +43,8 @@ namespace LocalIntegrators
      * Auxiliary function. Computes the grad-div-operator from a set of
      * Hessians.
      *
-     * @note The third tensor argument is not used in two dimensions and
-     * can for instance duplicate one of the previous.
+     * @note The third tensor argument is not used in two dimensions and can
+     * for instance duplicate one of the previous.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -67,14 +68,10 @@ namespace LocalIntegrators
 
 
     /**
-     * Cell matrix for divergence. The derivative is on the trial
-     * function.
-     * \f[
-     * \int_Z v\nabla \cdot \mathbf u \,dx
-     * \f]
-     * This is the strong divergence operator and the trial
-     * space should be at least <b>H</b><sup>div</sup>. The test functions
-     * may be discontinuous.
+     * Cell matrix for divergence. The derivative is on the trial function.
+     * \f[ \int_Z v\nabla \cdot \mathbf u \,dx \f] This is the strong
+     * divergence operator and the trial space should be at least
+     * <b>H</b><sup>div</sup>. The test functions may be discontinuous.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -111,16 +108,13 @@ namespace LocalIntegrators
     }
 
     /**
-     * The residual of the divergence operator in strong form.
-     * \f[
-     * \int_Z v\nabla \cdot \mathbf u \,dx
-     * \f]
-     * This is the strong divergence operator and the trial
-     * space should be at least <b>H</b><sup>div</sup>. The test functions
-     * may be discontinuous.
+     * The residual of the divergence operator in strong form. \f[ \int_Z
+     * v\nabla \cdot \mathbf u \,dx \f] This is the strong divergence operator
+     * and the trial space should be at least <b>H</b><sup>div</sup>. The test
+     * functions may be discontinuous.
      *
-     * The function cell_matrix() is the Frechet derivative of this function with respect
-     * to the test functions.
+     * The function cell_matrix() is the Frechet derivative of this function
+     * with respect to the test functions.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -149,16 +143,13 @@ namespace LocalIntegrators
 
 
     /**
-     * The residual of the divergence operator in weak form.
-     * \f[
-     * - \int_Z \nabla v \cdot \mathbf u \,dx
-     * \f]
-     * This is the weak divergence operator and the test
-     * space should be at least <b>H</b><sup>1</sup>. The trial functions
-     * may be discontinuous.
+     * The residual of the divergence operator in weak form. \f[ - \int_Z
+     * \nabla v \cdot \mathbf u \,dx \f] This is the weak divergence operator
+     * and the test space should be at least <b>H</b><sup>1</sup>. The trial
+     * functions may be discontinuous.
      *
-     * @todo Verify: The function cell_matrix() is the Frechet derivative of this function with respect
-     * to the test functions.
+     * @todo Verify: The function cell_matrix() is the Frechet derivative of
+     * this function with respect to the test functions.
      *
      * @author Guido Kanschat
      * @date 2013
@@ -187,13 +178,11 @@ namespace LocalIntegrators
 
 
     /**
-     * Cell matrix for gradient. The derivative is on the trial function.
-     * \f[
-     * \int_Z \nabla u \cdot \mathbf v\,dx
-     * \f]
+     * Cell matrix for gradient. The derivative is on the trial function. \f[
+     * \int_Z \nabla u \cdot \mathbf v\,dx \f]
      *
-     * This is the strong gradient and the trial space should be at least
-     * in <i>H</i><sup>1</sup>. The test functions can be discontinuous.
+     * This is the strong gradient and the trial space should be at least in
+     * <i>H</i><sup>1</sup>. The test functions can be discontinuous.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -231,15 +220,13 @@ namespace LocalIntegrators
     }
 
     /**
-     * The residual of the gradient operator in strong form.
-     * \f[
-     * \int_Z \mathbf v\cdot\nabla u \,dx
-     * \f]
-     * This is the strong gradient operator and the trial
-     * space should be at least <b>H</b><sup>1</sup>. The test functions
-     * may be discontinuous.
+     * The residual of the gradient operator in strong form. \f[ \int_Z
+     * \mathbf v\cdot\nabla u \,dx \f] This is the strong gradient operator
+     * and the trial space should be at least <b>H</b><sup>1</sup>. The test
+     * functions may be discontinuous.
      *
-     * The function gradient_matrix() is the Frechet derivative of this function with respect to the test functions.
+     * The function gradient_matrix() is the Frechet derivative of this
+     * function with respect to the test functions.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -267,15 +254,13 @@ namespace LocalIntegrators
     }
 
     /**
-     * The residual of the gradient operator in weak form.
-     * \f[
-     * -\int_Z \nabla\cdot \mathbf v u \,dx
-     * \f]
-     * This is the weak gradient operator and the test
-     * space should be at least <b>H</b><sup>div</sup>. The trial functions
-     * may be discontinuous.
+     * The residual of the gradient operator in weak form. \f[ -\int_Z
+     * \nabla\cdot \mathbf v u \,dx \f] This is the weak gradient operator and
+     * the test space should be at least <b>H</b><sup>div</sup>. The trial
+     * functions may be discontinuous.
      *
-     * @todo Verify: The function gradient_matrix() is the Frechet derivative of this function with respect to the test functions.
+     * @todo Verify: The function gradient_matrix() is the Frechet derivative
+     * of this function with respect to the test functions.
      *
      * @author Guido Kanschat
      * @date 2013
@@ -303,9 +288,8 @@ namespace LocalIntegrators
     }
 
     /**
-     * The trace of the divergence operator, namely the product of the
-     * normal component of the vector valued trial space and the test
-     * space.
+     * The trace of the divergence operator, namely the product of the normal
+     * component of the vector valued trial space and the test space.
      * @f[ \int_F (\mathbf u\cdot \mathbf n) v \,ds @f]
      *
      * @author Guido Kanschat
@@ -340,11 +324,8 @@ namespace LocalIntegrators
     }
 
     /**
-     * The trace of the divergence
-     * operator, namely the product
-     * of the normal component of the
-     * vector valued trial space and
-     * the test space.
+     * The trace of the divergence operator, namely the product of the normal
+     * component of the vector valued trial space and the test space.
      * @f[
      * \int_F (\mathbf u\cdot \mathbf n) v \,ds
      * @f]
@@ -380,11 +361,8 @@ namespace LocalIntegrators
     }
 
     /**
-     * The trace of the gradient
-     * operator, namely the product
-     * of the normal component of the
-     * vector valued test space and
-     * the trial space.
+     * The trace of the gradient operator, namely the product of the normal
+     * component of the vector valued test space and the trial space.
      * @f[
      * \int_F u (\mathbf v\cdot \mathbf n) \,ds
      * @f]
@@ -417,11 +395,9 @@ namespace LocalIntegrators
     }
 
     /**
-     * The trace of the divergence
-     * operator, namely the product
-     * of the jump of the normal component of the
-     * vector valued trial function and
-     * the mean value of the test function.
+     * The trace of the divergence operator, namely the product of the jump of
+     * the normal component of the vector valued trial function and the mean
+     * value of the test function.
      * @f[
      * \int_F (\mathbf u_1\cdot \mathbf n_1 + \mathbf u_2 \cdot \mathbf n_2) \frac{v_1+v_2}{2} \,ds
      * @f]
@@ -614,13 +590,12 @@ namespace LocalIntegrators
     }
 
     /**
-     * The <i>L</i><sup>2</sup>-norm of the divergence over the
-     * quadrature set determined by the FEValuesBase object.
+     * The <i>L</i><sup>2</sup>-norm of the divergence over the quadrature set
+     * determined by the FEValuesBase object.
      *
-     * The vector is expected to consist of dim vectors of length
-     * equal to the number of quadrature points. The number of
-     * components of the finite element has to be equal to the space
-     * dimension.
+     * The vector is expected to consist of dim vectors of length equal to the
+     * number of quadrature points. The number of components of the finite
+     * element has to be equal to the space dimension.
      *
      * @author Guido Kanschat
      * @date 2013
index be364b371a362da48c882d319f620beb3eab1d32..427fbb497fd89b1db741a67cabf719428f2533da 100644 (file)
@@ -39,12 +39,10 @@ namespace LocalIntegrators
   namespace Elasticity
   {
     /**
-     * The linear elasticity operator in weak form, namely double
-     * contraction of symmetric gradients.
+     * The linear elasticity operator in weak form, namely double contraction
+     * of symmetric gradients.
      *
-     * \f[
-     * \int_Z \varepsilon(u): \varepsilon(v)\,dx
-     * \f]
+     * \f[ \int_Z \varepsilon(u): \varepsilon(v)\,dx \f]
      */
     template <int dim>
     inline void cell_matrix (
@@ -75,9 +73,7 @@ namespace LocalIntegrators
     /**
      * Vector-valued residual operator for linear elasticity in weak form
      *
-     * \f[
-     * - \int_Z \varepsilon(u): \varepsilon(v) \,dx
-     * \f]
+     * \f[ - \int_Z \varepsilon(u): \varepsilon(v) \,dx \f]
      */
     template <int dim, typename number>
     inline void
@@ -110,8 +106,7 @@ namespace LocalIntegrators
 
 
     /**
-     * The weak boundary condition of Nitsche type for linear
-     * elasticity:
+     * The weak boundary condition of Nitsche type for linear elasticity:
      * @f[
      * \int_F \Bigl(\gamma (u-g) \cdot v - n^T \epsilon(u) v - (u-g) \epsilon(v) n^T\Bigr)\;ds.
      * @f]
@@ -156,17 +151,17 @@ namespace LocalIntegrators
     }
 
     /**
-     * Weak boundary condition for the elasticity operator by Nitsche,
-     * namely on the face <i>F</i> the vector
+     * Weak boundary condition for the elasticity operator by Nitsche, namely
+     * on the face <i>F</i> the vector
      * @f[
      * \int_F \Bigl(\gamma (u-g) \cdot v - n^T \epsilon(u) v - (u-g) \epsilon(v) n^T\Bigr)\;ds.
      * @f]
      *
-     * Here, <i>u</i> is the finite element function whose values and
-     * gradient are given in the arguments <tt>input</tt> and
-     * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
-     * boundary value in the argument <tt>data</tt>. $n$ is the outer
-     * normal vector and $\gamma$ is the usual penalty parameter.
+     * Here, <i>u</i> is the finite element function whose values and gradient
+     * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+     * respectively. <i>g</i> is the inhomogeneous boundary value in the
+     * argument <tt>data</tt>. $n$ is the outer normal vector and $\gamma$ is
+     * the usual penalty parameter.
      *
      * @author Guido Kanschat
      * @date 2013
@@ -214,16 +209,16 @@ namespace LocalIntegrators
     }
 
     /**
-     * Homogeneous weak boundary condition for the elasticity operator by Nitsche,
-     * namely on the face <i>F</i> the vector
+     * Homogeneous weak boundary condition for the elasticity operator by
+     * Nitsche, namely on the face <i>F</i> the vector
      * @f[
      * \int_F \Bigl(\gamma u \cdot v - n^T \epsilon(u) v - u \epsilon(v) n^T\Bigr)\;ds.
      * @f]
      *
-     * Here, <i>u</i> is the finite element function whose values and
-     * gradient are given in the arguments <tt>input</tt> and
-     * <tt>Dinput</tt>, respectively. $n$ is the outer
-     * normal vector and $\gamma$ is the usual penalty parameter.
+     * Here, <i>u</i> is the finite element function whose values and gradient
+     * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+     * respectively. $n$ is the outer normal vector and $\gamma$ is the usual
+     * penalty parameter.
      *
      * @author Guido Kanschat
      * @date 2013
@@ -268,8 +263,7 @@ namespace LocalIntegrators
     }
 
     /**
-     * The interior penalty flux
-     * for symmetric gradients.
+     * The interior penalty flux for symmetric gradients.
      */
     template <int dim>
     inline void ip_matrix (
index d6db3d06ba9caa73e2ec104d23c1bc8938f13b49..48b42c1f59442bc25d5f69f5235a2ccaf1fa9a52 100644 (file)
@@ -39,15 +39,12 @@ namespace LocalIntegrators
   namespace L2
   {
     /**
-     * The mass matrix for scalar or vector values finite elements.
-     * \f[
-     * \int_Z uv\,dx \quad \text{or} \quad \int_Z \mathbf u\cdot \mathbf v\,dx
-     * \f]
+     * The mass matrix for scalar or vector values finite elements. \f[ \int_Z
+     * uv\,dx \quad \text{or} \quad \int_Z \mathbf u\cdot \mathbf v\,dx \f]
      *
-     * Likewise, this term can be used on faces, where it computes  the integrals
-     * \f[
-     * \int_F uv\,ds \quad \text{or} \quad \int_F \mathbf u\cdot \mathbf v\,ds
-     * \f]
+     * Likewise, this term can be used on faces, where it computes  the
+     * integrals \f[ \int_F uv\,ds \quad \text{or} \quad \int_F \mathbf u\cdot
+     * \mathbf v\,ds \f]
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -76,17 +73,15 @@ namespace LocalIntegrators
 
     /**
      * The weighted mass matrix for scalar or vector values finite elements.
-     * \f[
-     * \int_Z \omega(x) uv\,dx \quad \text{or} \quad \int_Z \omega(x) \mathbf u\cdot \mathbf v\,dx
-     * \f]
+     * \f[ \int_Z \omega(x) uv\,dx \quad \text{or} \quad \int_Z \omega(x)
+     * \mathbf u\cdot \mathbf v\,dx \f]
      *
-     * Likewise, this term can be used on faces, where it computes  the integrals
-     * \f[
-     * \int_F \omega(x) uv\,ds \quad \text{or} \quad \int_F \omega(x) \mathbf u\cdot \mathbf v\,ds
-     * \f]
+     * Likewise, this term can be used on faces, where it computes  the
+     * integrals \f[ \int_F \omega(x) uv\,ds \quad \text{or} \quad \int_F
+     * \omega(x) \mathbf u\cdot \mathbf v\,ds \f]
      *
-     * The size of the vector <tt>weights</tt> must be equal to the
-     * number of quadrature points in the finite element.
+     * The size of the vector <tt>weights</tt> must be equal to the number of
+     * quadrature points in the finite element.
      *
      * @author Guido Kanschat
      * @date 2014
@@ -119,9 +114,7 @@ namespace LocalIntegrators
     /**
      * <i>L<sup>2</sup></i>-inner product for scalar functions.
      *
-     * \f[
-     * \int_Z fv\,dx \quad \text{or} \quad \int_F fv\,ds
-     * \f]
+     * \f[ \int_Z fv\,dx \quad \text{or} \quad \int_F fv\,ds \f]
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -144,13 +137,9 @@ namespace LocalIntegrators
     }
 
     /**
-     * <i>L<sup>2</sup></i>-inner product for a slice of a vector valued
-     * right hand side.
-     * \f[
-     * \int_Z \mathbf f\cdot \mathbf v\,dx
-     * \quad \text{or} \quad
-     * \int_F \mathbf f\cdot \mathbf v\,ds
-     * \f]
+     * <i>L<sup>2</sup></i>-inner product for a slice of a vector valued right
+     * hand side. \f[ \int_Z \mathbf f\cdot \mathbf v\,dx \quad \text{or}
+     * \quad \int_F \mathbf f\cdot \mathbf v\,ds \f]
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -176,17 +165,13 @@ namespace LocalIntegrators
     }
 
     /**
-     * The jump matrix between two cells for scalar or vector values
-     * finite elements. Note that the factor $\gamma$ can be used to
-     * implement weighted jumps.
-     * \f[
-     * \int_F [\gamma u][\gamma v]\,ds
-     * \quad \text{or}
-     * \int_F [\gamma \mathbf u]\cdot [\gamma \mathbf v]\,ds
-     * \f]
+     * The jump matrix between two cells for scalar or vector values finite
+     * elements. Note that the factor $\gamma$ can be used to implement
+     * weighted jumps. \f[ \int_F [\gamma u][\gamma v]\,ds \quad \text{or}
+     * \int_F [\gamma \mathbf u]\cdot [\gamma \mathbf v]\,ds \f]
      *
-     * Using appropriate weights, this term can be used to penalize
-     * violation of conformity in <i>H<sup>1</sup></i>.
+     * Using appropriate weights, this term can be used to penalize violation
+     * of conformity in <i>H<sup>1</sup></i>.
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
index b563cbc76d28052ab5922023882810ab5a8de441..ac1b77d03b3bdf1e905979e709d041159ea35611 100644 (file)
@@ -39,14 +39,11 @@ namespace LocalIntegrators
   namespace Laplace
   {
     /**
-     * Laplacian in weak form, namely on the cell <i>Z</i> the matrix
-     * \f[
-     * \int_Z \nu \nabla u \cdot \nabla v \, dx.
-     * \f]
+     * Laplacian in weak form, namely on the cell <i>Z</i> the matrix \f[
+     * \int_Z \nu \nabla u \cdot \nabla v \, dx. \f]
      *
-     * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In
-     * the latter case, the Laplacian is applied to each component
-     * separately.
+     * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In the
+     * latter case, the Laplacian is applied to each component separately.
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -76,9 +73,7 @@ namespace LocalIntegrators
     /**
      * Laplacian residual operator in weak form
      *
-     * \f[
-     * \int_Z \nu \nabla u \cdot \nabla v \, dx.
-     * \f]
+     * \f[ \int_Z \nu \nabla u \cdot \nabla v \, dx. \f]
      */
     template <int dim>
     inline void
@@ -105,9 +100,7 @@ namespace LocalIntegrators
     /**
      * Vector-valued Laplacian residual operator in weak form
      *
-     * \f[
-     * \int_Z \nu \nabla u : \nabla v \, dx.
-     * \f]
+     * \f[ \int_Z \nu \nabla u : \nabla v \, dx. \f]
      */
     template <int dim>
     inline void
@@ -138,13 +131,14 @@ namespace LocalIntegrators
 
 
     /**
-     * Weak boundary condition of Nitsche type for the Laplacian, namely on the face <i>F</i> the matrix
+     * Weak boundary condition of Nitsche type for the Laplacian, namely on
+     * the face <i>F</i> the matrix
      * @f[
      * \int_F \Bigl(\gamma u v - \partial_n u v - u \partial_n v\Bigr)\;ds.
      * @f]
      *
-     * Here, $\gamma$ is the <tt>penalty</tt> parameter suitably computed
-     * with compute_penalty().
+     * Here, $\gamma$ is the <tt>penalty</tt> parameter suitably computed with
+     * compute_penalty().
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -183,11 +177,10 @@ namespace LocalIntegrators
      * \int_F \Bigl(\gamma (u-g) v - \partial_n u v - (u-g) \partial_n v\Bigr)\;ds.
      * @f]
      *
-     * Here, <i>u</i> is the finite element function whose values and
-     * gradient are given in the arguments <tt>input</tt> and
-     * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
-     * boundary value in the argument <tt>data</tt>. $\gamma$ is the usual
-     * penalty parameter.
+     * Here, <i>u</i> is the finite element function whose values and gradient
+     * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+     * respectively. <i>g</i> is the inhomogeneous boundary value in the
+     * argument <tt>data</tt>. $\gamma$ is the usual penalty parameter.
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -226,19 +219,17 @@ namespace LocalIntegrators
 
     /**
      * Weak boundary condition for the Laplace operator by Nitsche, vector
-     * valued version, namely on the face <i>F</i>
-     * the vector
+     * valued version, namely on the face <i>F</i> the vector
      * @f[
      * \int_F \Bigl(\gamma (\mathbf u- \mathbf g) \cdot \mathbf v
-     - \partial_n \mathbf u \cdot \mathbf v
-     - (\mathbf u-\mathbf g) \cdot \partial_n \mathbf v\Bigr)\;ds.
+     - \partial_n \mathbf u \cdot \mathbf v
+     - (\mathbf u-\mathbf g) \cdot \partial_n \mathbf v\Bigr)\;ds.
      * @f]
      *
-     * Here, <i>u</i> is the finite element function whose values and
-     * gradient are given in the arguments <tt>input</tt> and
-     * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
-     * boundary value in the argument <tt>data</tt>. $\gamma$ is the usual
-     * penalty parameter.
+     * Here, <i>u</i> is the finite element function whose values and gradient
+     * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+     * respectively. <i>g</i> is the inhomogeneous boundary value in the
+     * argument <tt>data</tt>. $\gamma$ is the usual penalty parameter.
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -278,20 +269,20 @@ namespace LocalIntegrators
     }
 
     /**
-     * Flux for the interior penalty method for the Laplacian, namely on
-     * the face <i>F</i> the matrices associated with the bilinear form
+     * Flux for the interior penalty method for the Laplacian, namely on the
+     * face <i>F</i> the matrices associated with the bilinear form
      * @f[
      * \int_F \Bigl( \gamma [u][v] - \{\nabla u\}[v\mathbf n] - [u\mathbf
      * n]\{\nabla v\} \Bigr) \; ds.
      * @f]
      *
-     * The penalty parameter should always be the mean value of the
-     * penalties needed for stability on each side. In the case of
-     * constant coefficients, it can be computed using compute_penalty().
+     * The penalty parameter should always be the mean value of the penalties
+     * needed for stability on each side. In the case of constant
+     * coefficients, it can be computed using compute_penalty().
      *
-     * If <tt>factor2</tt> is missing or negative, the factor is assumed
-     * the same on both sides. If factors differ, note that the penalty
-     * parameter has to be computed accordingly.
+     * If <tt>factor2</tt> is missing or negative, the factor is assumed the
+     * same on both sides. If factors differ, note that the penalty parameter
+     * has to be computed accordingly.
      *
      * @author Guido Kanschat
      * @date 2008, 2009, 2010
@@ -351,9 +342,9 @@ namespace LocalIntegrators
     }
 
     /**
-     * Flux for the interior penalty method for the Laplacian applied
-     * to the tangential components of a vector field, namely on
-     * the face <i>F</i> the matrices associated with the bilinear form
+     * Flux for the interior penalty method for the Laplacian applied to the
+     * tangential components of a vector field, namely on the face <i>F</i>
+     * the matrices associated with the bilinear form
      * @f[
      * \int_F \Bigl( \gamma [u_\tau][v_\tau] - \{\nabla u_\tau\}[v_\tau\mathbf n] - [u_\tau\mathbf
      * n]\{\nabla v_\tau\} \Bigr) \; ds.
@@ -517,8 +508,8 @@ namespace LocalIntegrators
      * Vector-valued residual term for the symmetric interior penalty method:
      * @f[
      * \int_F \Bigl( \gamma [\mathbf u]\cdot[\mathbf v]
-     - \{\nabla \mathbf u\}[\mathbf v\otimes \mathbf n]
-     - [\mathbf u\otimes \mathbf n]\{\nabla \mathbf v\} \Bigr) \; ds.
+     - \{\nabla \mathbf u\}[\mathbf v\otimes \mathbf n]
+     - [\mathbf u\otimes \mathbf n]\{\nabla \mathbf v\} \Bigr) \; ds.
      * @f]
      *
      * @author Guido Kanschat
@@ -585,15 +576,15 @@ namespace LocalIntegrators
 
 
     /**
-     * Auxiliary function computing the penalty parameter for interior
-     * penalty methods on rectangles.
+     * Auxiliary function computing the penalty parameter for interior penalty
+     * methods on rectangles.
      *
      * Computation is done in two steps: first, we compute on each cell
      * <i>Z<sub>i</sub></i> the value <i>P<sub>i</sub> =
-     * p<sub>i</sub>(p<sub>i</sub>+1)/h<sub>i</sub></i>, where <i>p<sub>i</sub></i> is
-     * the polynomial degree on cell <i>Z<sub>i</sub></i> and
-     * <i>h<sub>i</sub></i> is the length of <i>Z<sub>i</sub></i>
-     * orthogonal to the current face.
+     * p<sub>i</sub>(p<sub>i</sub>+1)/h<sub>i</sub></i>, where
+     * <i>p<sub>i</sub></i> is the polynomial degree on cell
+     * <i>Z<sub>i</sub></i> and <i>h<sub>i</sub></i> is the length of
+     * <i>Z<sub>i</sub></i> orthogonal to the current face.
      *
      * @author Guido Kanschat
      * @date 2010
index 81ac420ca1274929c93c3adf9c8bec9cdc157a4e..63816f7c439ec1b7c29d9af947c97883c412659c 100644 (file)
@@ -28,52 +28,47 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * @brief Library of integrals over cells and faces
  *
- * This namespace contains application specific local integrals for
- * bilinear forms, forms and error estimates. It is a collection of
- * functions organized into namespaces devoted to certain
- * applications. For instance, the namespace Laplace contains
- * functions for computing cell matrices and cell residuals for the
- * Laplacian operator, as well as functions for the weak boundary
- * conditions by Nitsche or the interior penalty discontinuous
- * Galerkin method. The namespace Maxwell does the same for
- * curl-curl type problems.
+ * This namespace contains application specific local integrals for bilinear
+ * forms, forms and error estimates. It is a collection of functions organized
+ * into namespaces devoted to certain applications. For instance, the
+ * namespace Laplace contains functions for computing cell matrices and cell
+ * residuals for the Laplacian operator, as well as functions for the weak
+ * boundary conditions by Nitsche or the interior penalty discontinuous
+ * Galerkin method. The namespace Maxwell does the same for curl-curl type
+ * problems.
  *
  * The namespace L2 contains functions for mass matrices and
  * <i>L<sup>2</sup></i>-inner products.
  *
  * <h3>Notational conventions</h3>
  *
- * In most cases, the action of a function in this namespace can be
- * described by a single integral. We distinguish between integrals
- * over cells <i>Z</i> and over faces <i>F</i>. If an integral is
- * denoted as
+ * In most cases, the action of a function in this namespace can be described
+ * by a single integral. We distinguish between integrals over cells <i>Z</i>
+ * and over faces <i>F</i>. If an integral is denoted as
  * @f[
  *   \int_Z u \otimes v \,dx,
  * @f]
- * it will yield the following results, depending on the type of
- * operation
+ * it will yield the following results, depending on the type of operation
  * <ul>
- * <li> If the function returns a matrix, the entry at
- * position <i>(i,j)</i> will be the integrated product of test function
- * <i>v<sub>i</sub></i> and trial function <i>u<sub>j</sub></i> (note
- * the reversion of indices)</li>
- * <li> If the function returns a vector, then the vector
- * entry at position <i>i</i> will be the integrated product of the
- * given function <i>u</i> with the test function <i>v<sub>i</sub></i>.</li>
- * <li> If the function returns a number, then this number is the
- * integral of the two given functions <i>u</i> and <i>v</i>.
+ * <li> If the function returns a matrix, the entry at position <i>(i,j)</i>
+ * will be the integrated product of test function <i>v<sub>i</sub></i> and
+ * trial function <i>u<sub>j</sub></i> (note the reversion of indices)</li>
+ * <li> If the function returns a vector, then the vector entry at position
+ * <i>i</i> will be the integrated product of the given function <i>u</i> with
+ * the test function <i>v<sub>i</sub></i>.</li>
+ * <li> If the function returns a number, then this number is the integral of
+ * the two given functions <i>u</i> and <i>v</i>.
  * </ul>
  *
- * We will use regular cursive symbols $u$ for scalars and bold
- * symbols $\mathbf u$ for vectors. Test functions are always <i>v</i>
- * and trial functions are always <i>u</i>. Parameters are Greek and
- * the face normal vectors are $\mathbf n = \mathbf n_1 = -\mathbf
- * n_2$.
+ * We will use regular cursive symbols $u$ for scalars and bold symbols
+ * $\mathbf u$ for vectors. Test functions are always <i>v</i> and trial
+ * functions are always <i>u</i>. Parameters are Greek and the face normal
+ * vectors are $\mathbf n = \mathbf n_1 = -\mathbf n_2$.
  *
  * <h3>Signature of functions</h3>
  *
- * Functions in this namespace follow a generic signature. In the
- * simplest case, you have two related functions
+ * Functions in this namespace follow a generic signature. In the simplest
+ * case, you have two related functions
  * @code
  *   template <int dim>
  *   void
@@ -91,11 +86,11 @@ DEAL_II_NAMESPACE_OPEN
  *     const double factor = 1.);
  * @endcode
  *
- * There is typically a pair of functions for the same operator, the
- * function <tt>cell_residual</tt> implementing the mapping of the
- * operator from the finite element space into its dual, and the
- * function <tt>cell_matrix</tt> generating the bilinear form
- * corresponding to the Frechet derivative of <tt>cell_residual</tt>.
+ * There is typically a pair of functions for the same operator, the function
+ * <tt>cell_residual</tt> implementing the mapping of the operator from the
+ * finite element space into its dual, and the function <tt>cell_matrix</tt>
+ * generating the bilinear form corresponding to the Frechet derivative of
+ * <tt>cell_residual</tt>.
  *
  * The first argument of these functions is the return type, which is
  * <ul>
@@ -103,12 +98,11 @@ DEAL_II_NAMESPACE_OPEN
  * <li> BlockVector&ltdouble&gt; for vectors
  * </ul>
  *
- * The next argument is the FEValuesBase object representing the
- * finite element for integration. If the integrated operator maps
- * from one finite element space into the dual of another (for
- * instance an off-diagonal matrix in a block system), then first the
- * FEValuesBase for the trial space and after this the one for the
- * test space are specified.
+ * The next argument is the FEValuesBase object representing the finite
+ * element for integration. If the integrated operator maps from one finite
+ * element space into the dual of another (for instance an off-diagonal matrix
+ * in a block system), then first the FEValuesBase for the trial space and
+ * after this the one for the test space are specified.
  *
  * This list is followed by the set of required data in the order
  * <ol>
@@ -120,30 +114,31 @@ DEAL_II_NAMESPACE_OPEN
  *
  * <h3>Usage</h3>
  *
- * The local integrators can be used wherever a local integration loop
- * would have been implemented instead. The following example is from
- * the implementation of a Stokes solver, using
+ * The local integrators can be used wherever a local integration loop would
+ * have been implemented instead. The following example is from the
+ * implementation of a Stokes solver, using
  * MeshWorker::Assembler::LocalBlocksToGlobalBlocks. The matrices are
  * <ul>
- * <li> 0: The vector Laplacian for the velocity (here with a vector valued element)
+ * <li> 0: The vector Laplacian for the velocity (here with a vector valued
+ * element)
  * <li> 1: The divergence matrix
  * <li> 2: The pressure mass matrix used in the preconditioner
  * </ul>
  *
- * With these matrices, the function called by MeshWorker::loop()
- * could be written like
+ * With these matrices, the function called by MeshWorker::loop() could be
+ * written like
  * @code
-using namespace ::dealii:: LocalIntegrators;
-
-template <int dim>
-void MatrixIntegrator<dim>::cell(
-  MeshWorker::DoFInfo<dim>& dinfo,
-  typename MeshWorker::IntegrationInfo<dim>& info)
-{
-  Laplace::cell_matrix(dinfo.matrix(0,false).matrix, info.fe_values(0));
-  Divergence::cell_matrix(dinfo.matrix(1,false).matrix, info.fe_values(0), info.fe_values(1));
-  L2::cell_matrix(dinfo.matrix(2,false).matrix, info.fe_values(1));
-}
+ * using namespace ::dealii:: LocalIntegrators;
+ *
+ * template <int dim>
+ * void MatrixIntegrator<dim>::cell(
* MeshWorker::DoFInfo<dim>& dinfo,
* typename MeshWorker::IntegrationInfo<dim>& info)
+ * {
* Laplace::cell_matrix(dinfo.matrix(0,false).matrix, info.fe_values(0));
* Divergence::cell_matrix(dinfo.matrix(1,false).matrix, info.fe_values(0), info.fe_values(1));
* L2::cell_matrix(dinfo.matrix(2,false).matrix, info.fe_values(1));
+ * }
  * @endcode
  * See step-39 for a worked out example of this code.
  *
index 236d2a5cb3badcb75a4fbf0987f3b774a6af8270..6cbd02b30cda6b32ac0d31ff8bf22728d0b7bf47 100644 (file)
@@ -30,11 +30,10 @@ DEAL_II_NAMESPACE_OPEN
 namespace LocalIntegrators
 {
   /**
-   * @brief Local integrators related to curl operators and their
-   * traces.
+   * @brief Local integrators related to curl operators and their traces.
    *
-   * We use the following conventions for curl
-   * operators. First, in three space dimensions
+   * We use the following conventions for curl operators. First, in three
+   * space dimensions
    *
    * @f[
    * \nabla\times \mathbf u = \begin{pmatrix}
@@ -46,9 +45,9 @@ namespace LocalIntegrators
    *
    * In two space dimensions, the curl is obtained by extending a vector
    * <b>u</b> to $(u_1, u_2, 0)^T$ and a scalar <i>p</i> to $(0,0,p)^T$.
-   * Computing the nonzero components, we obtain the scalar
-   * curl of a vector function and the vector curl of a scalar
-   * function. The current implementation exchanges the sign and we have:
+   * Computing the nonzero components, we obtain the scalar curl of a vector
+   * function and the vector curl of a scalar function. The current
+   * implementation exchanges the sign and we have:
    * @f[
    *  \nabla \times \mathbf u = \partial_1 u_2 - \partial 2 u_1,
    *  \qquad
@@ -64,9 +63,9 @@ namespace LocalIntegrators
   namespace Maxwell
   {
     /**
-     * Auxiliary function. Given the tensors of <tt>dim</tt> second derivatives,
-     * compute the curl of the curl of a vector function. The result in
-     * two and three dimensions is:
+     * Auxiliary function. Given the tensors of <tt>dim</tt> second
+     * derivatives, compute the curl of the curl of a vector function. The
+     * result in two and three dimensions is:
      * @f[
      * \nabla\times\nabla\times \mathbf u = \begin{pmatrix}
      * \partial_1\partial_2 u_2 - \partial_2^2 u_1 \\
@@ -83,8 +82,8 @@ namespace LocalIntegrators
      * \end{pmatrix}
      * @f]
      *
-     * @note The third tensor argument is not used in two dimensions and
-     * can for instance duplicate one of the previous.
+     * @note The third tensor argument is not used in two dimensions and can
+     * for instance duplicate one of the previous.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -115,14 +114,14 @@ namespace LocalIntegrators
     }
 
     /**
-     * Auxiliary function. Given <tt>dim</tt> tensors of first
-     * derivatives and a normal vector, compute the tangential curl
+     * Auxiliary function. Given <tt>dim</tt> tensors of first derivatives and
+     * a normal vector, compute the tangential curl
      * @f[
      * \mathbf n \times \nabla \times u.
      * @f]
      *
-     * @note The third tensor argument is not used in two dimensions and
-     * can for instance duplicate one of the previous.
+     * @note The third tensor argument is not used in two dimensions and can
+     * for instance duplicate one of the previous.
      *
      * @author Guido Kanschat
      * @date 2011
@@ -212,13 +211,13 @@ namespace LocalIntegrators
      * \int_Z \nabla\!\times\! u \cdot v \,dx.
      * @f]
      *
-     * This is the standard curl operator in 3D and the scalar curl in
-     * 2D. The vector curl operator can be obtained by exchanging test and
-     * trial functions.
+     * This is the standard curl operator in 3D and the scalar curl in 2D. The
+     * vector curl operator can be obtained by exchanging test and trial
+     * functions.
      *
      * @author Guido Kanschat
      * @date 2011
-    */
+     */
     template <int dim>
     void curl_matrix (
       FullMatrix<double> &M,
@@ -254,10 +253,8 @@ namespace LocalIntegrators
     }
 
     /**
-     * The matrix for weak boundary
-     * condition of Nitsche type for
-     * the tangential component in
-     * Maxwell systems.
+     * The matrix for weak boundary condition of Nitsche type for the
+     * tangential component in Maxwell systems.
      *
      * @f[
      * \int_F \biggl( 2\gamma
@@ -317,8 +314,7 @@ namespace LocalIntegrators
         }
     }
     /**
-     * The product of two tangential
-     * traces,
+     * The product of two tangential traces,
      * @f[
      * \int_F (u\times n)(v\times n)
      * \, ds.
@@ -371,8 +367,7 @@ namespace LocalIntegrators
     }
 
     /**
-     * The interior penalty fluxes
-     * for Maxwell systems.
+     * The interior penalty fluxes for Maxwell systems.
      *
      * @f[
      * \int_F \biggl( \gamma
@@ -382,9 +377,9 @@ namespace LocalIntegrators
      * n\}\{\nu \nabla\times u\}
      * \biggr)\;dx
      * @f]
-    *
-    * @author Guido Kanschat
-    * @date 2011
+     *
+     * @author Guido Kanschat
+     * @date 2011
      */
     template <int dim>
     inline void ip_curl_matrix (
index 21983c028313f6c508184356e6ea20b4e7ae1ed1..185efe61c0421461a6611b92fa4c5b0f08b481e9 100644 (file)
@@ -49,30 +49,28 @@ extern "C" void dneupd_(int *rvec, char *howmany, int *select, double *d,
  * eigenvectors of a general n by n matrix A. It is most appropriate for large
  * sparse matrices A.
  *
- * In this class we make use of the method applied to the
- * generalized eigenspectrum problem $(A-\lambda B)x=0$, for
- * $x\neq0$; where $A$ is a system matrix, $B$ is a mass matrix,
- * and $\lambda, x$ are a set of eigenvalues and eigenvectors
- * respectively.
+ * In this class we make use of the method applied to the generalized
+ * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
+ * system matrix, $B$ is a mass matrix, and $\lambda, x$ are a set of
+ * eigenvalues and eigenvectors respectively.
  *
- * The ArpackSolver can be used in application codes
- * with serial objects in the following way:
- @code
-  SolverControl solver_control (1000, 1e-9);
-  ArpackSolver (solver_control);
-  system.solve (A, B, OP, lambda, x, size_of_spectrum);
- @endcode
- * for the generalized eigenvalue problem $Ax=B\lambda x$, where
- * the variable <code>size_of_spectrum</code>
- * tells ARPACK the number of eigenvector/eigenvalue pairs to
- * solve for. Here, <code>lambda</code> is a vector that will contain
- * the eigenvalues computed, <code>x</code> a vector that will
- * contain the eigenvectors computed, and <code>OP</code> is
- * an inverse operation for the matrix <code>A</code>.
- * Shift and invert transformation around zero is applied.
+ * The ArpackSolver can be used in application codes with serial objects in
+ * the following way:
+ * @code
+ * SolverControl solver_control (1000, 1e-9);
+ * ArpackSolver (solver_control);
+ * system.solve (A, B, OP, lambda, x, size_of_spectrum);
+ * @endcode
+ * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
+ * <code>size_of_spectrum</code> tells ARPACK the number of
+ * eigenvector/eigenvalue pairs to solve for. Here, <code>lambda</code> is a
+ * vector that will contain the eigenvalues computed, <code>x</code> a vector
+ * that will contain the eigenvectors computed, and <code>OP</code> is an
+ * inverse operation for the matrix <code>A</code>. Shift and invert
+ * transformation around zero is applied.
  *
- * Through the AdditionalData the user can specify some of the
- * parameters to be set.
+ * Through the AdditionalData the user can specify some of the parameters to
+ * be set.
  *
  * For further information on how the ARPACK routines <code>dneupd</code> and
  * <code>dnaupd</code> work and also how to set the parameters appropriately
@@ -90,9 +88,8 @@ public:
 
 
   /**
-   * An enum that lists the possible
-   * choices for which eigenvalues to
-   * compute in the solve() function.
+   * An enum that lists the possible choices for which eigenvalues to compute
+   * in the solve() function.
    */
   enum WhichEigenvalues
   {
@@ -108,9 +105,8 @@ public:
   };
 
   /**
-   * Standardized data struct to pipe
-   * additional data to the solver,
-   * should it be needed.
+   * Standardized data struct to pipe additional data to the solver, should it
+   * be needed.
    */
   struct AdditionalData
   {
@@ -122,8 +118,7 @@ public:
   };
 
   /**
-   * Access to the object that
-   * controls convergence.
+   * Access to the object that controls convergence.
    */
   SolverControl &control () const;
 
@@ -134,10 +129,8 @@ public:
                const AdditionalData &data = AdditionalData());
 
   /**
-   * Solve the generalized eigensprectrum
-   * problem $A x=\lambda B x$ by calling
-   * the <code>dneupd</code> and <code>dnaupd</code>
-   * functions of ARPACK.
+   * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by calling
+   * the <code>dneupd</code> and <code>dnaupd</code> functions of ARPACK.
    */
   template <typename VECTOR, typename MATRIX1,
             typename MATRIX2, typename INVERSE>
@@ -152,15 +145,13 @@ public:
 protected:
 
   /**
-   * Reference to the object that
-   * controls convergence of the
-   * iterative solver.
+   * Reference to the object that controls convergence of the iterative
+   * solver.
    */
   SolverControl &solver_control;
 
   /**
-   * Store a copy of the flags for
-   * this particular solver.
+   * Store a copy of the flags for this particular solver.
    */
   const AdditionalData additional_data;
 
@@ -266,22 +257,16 @@ void ArpackSolver::solve (
   int ido = 0;
 
   /**
-   * 'G' generalized eigenvalue problem
-   * 'I' standard eigenvalue problem
+   * 'G' generalized eigenvalue problem 'I' standard eigenvalue problem
    */
   char bmat[2] = "G";
 
-  /** Specify the eigenvalues of interest,
-   *  possible parameters
-   *  "LA" algebraically largest
-   *  "SA" algebraically smallest
-   *  "LM" largest magnitude
-   *  "SM" smallest magnitude
-   *  "LR" largest real part
-   *  "SR" smallest real part
-   *  "LI" largest imaginary part
-   *  "SI" smallest imaginary part
-   *  "BE" both ends of spectrum simultaneous
+  /**
+   * Specify the eigenvalues of interest, possible parameters "LA"
+   * algebraically largest "SA" algebraically smallest "LM" largest magnitude
+   * "SM" smallest magnitude "LR" largest real part "SR" smallest real part
+   * "LI" largest imaginary part "SI" smallest imaginary part "BE" both ends
+   * of spectrum simultaneous
    */
   char which[3];
   switch (additional_data.eigenvalue_of_interest)
@@ -336,12 +321,9 @@ void ArpackSolver::solve (
   // maximum number of iterations
   iparam[2] = control().max_steps();
 
-  /** Sets the mode of dsaupd.
-   *  1 is exact shifting,
-   *  2 is user-supplied shifts,
-   *  3 is shift-invert mode,
-   *  4 is buckling mode,
-   *  5 is Cayley mode.
+  /**
+   * Sets the mode of dsaupd. 1 is exact shifting, 2 is user-supplied shifts,
+   * 3 is shift-invert mode, 4 is buckling mode, 5 is Cayley mode.
    */
 
   iparam[6] = mode;
@@ -457,8 +439,8 @@ void ArpackSolver::solve (
     }
   else
     {
-      /** 1 - compute eigenvectors,
-       *  0 - only eigenvalues
+      /**
+       * 1 - compute eigenvectors, 0 - only eigenvalues
        */
       int rvec = 1;
 
index e8124b5571adb6db7d196c915c735f0cad9d0b0b..890d723935d6ec80f018d9264a4fb98c6f116030 100644 (file)
@@ -31,24 +31,22 @@ DEAL_II_NAMESPACE_OPEN
  * @brief Auxiliary class aiding in the handling of block structures like in
  * BlockVector or FESystem.
  *
- * The information obtained from this class falls into two
- * groups. First, it is possible to obtain the number of blocks,
- * namely size(), the block_size() for each block and the total_size()
- * of the object described by the block indices, namely the length of
- * the whole index set. These functions do not make any assumption on
- * the ordering of the index set.
+ * The information obtained from this class falls into two groups. First, it
+ * is possible to obtain the number of blocks, namely size(), the block_size()
+ * for each block and the total_size() of the object described by the block
+ * indices, namely the length of the whole index set. These functions do not
+ * make any assumption on the ordering of the index set.
  *
- * If on the other hand the index set is ordered "by blocks", such
- * that each block forms a consecutive set of indices, this
- * class that manages the conversion of global indices into a block vector or
- * matrix to the local indices within this block. This is required, for
- * example, when you address a global element in a block vector and want to
- * know which element within which block this is. It is also useful if a
- * matrix is composed of several blocks, where you have to translate global
- * row and column indices to local ones.
+ * If on the other hand the index set is ordered "by blocks", such that each
+ * block forms a consecutive set of indices, this class that manages the
+ * conversion of global indices into a block vector or matrix to the local
+ * indices within this block. This is required, for example, when you address
+ * a global element in a block vector and want to know which element within
+ * which block this is. It is also useful if a matrix is composed of several
+ * blocks, where you have to translate global row and column indices to local
+ * ones.
  *
- * @ingroup data
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup data @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Wolfgang Bangerth, Guido Kanschat, 2000, 2007, 2011
  */
 class BlockIndices : public Subscriptor
@@ -60,50 +58,37 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Default
-   * constructor. Initialize for
-   * zero blocks.
+   * Default constructor. Initialize for zero blocks.
    */
   BlockIndices ();
 
   /**
-   * Constructor. Initialize the
-   * number of entries in each
-   * block @p i as <tt>n[i]</tt>. The
-   * number of blocks will be the
-   * size of the vector
+   * Constructor. Initialize the number of entries in each block @p i as
+   * <tt>n[i]</tt>. The number of blocks will be the size of the vector
    */
   BlockIndices (const std::vector<size_type> &n);
 
   /**
-   * Specialized constructor for a
-   * structure with blocks of equal size.
+   * Specialized constructor for a structure with blocks of equal size.
    */
   explicit BlockIndices(const unsigned int n_blocks, const size_type block_size = 0);
 
   /**
-   * Reinitialize the number of
-   * blocks and assign each block
-   * the same number of elements.
+   * Reinitialize the number of blocks and assign each block the same number
+   * of elements.
    */
   void reinit (const unsigned int n_blocks,
                const size_type n_elements_per_block);
 
   /**
-   * Reinitialize the number of
-   * indices within each block from
-   * the given argument. The number
-   * of blocks will be adjusted to
-   * the size of @p n and the size
-   * of block @p i is set to
-   * <tt>n[i]</tt>.
+   * Reinitialize the number of indices within each block from the given
+   * argument. The number of blocks will be adjusted to the size of @p n and
+   * the size of block @p i is set to <tt>n[i]</tt>.
    */
   void reinit (const std::vector<size_type> &n);
 
   /**
-   * Add another block of given
-   * size to the end of the block
-   * structure.
+   * Add another block of given size to the end of the block structure.
    */
   void push_back(const size_type size);
 
@@ -118,11 +103,8 @@ public:
   unsigned int size () const;
 
   /**
-   * Return the total number of
-   * indices accumulated over all
-   * blocks, that is, the dimension
-   * of the vector space of the
-   * block vector.
+   * Return the total number of indices accumulated over all blocks, that is,
+   * the dimension of the vector space of the block vector.
    */
   size_type total_size () const;
 
@@ -136,32 +118,23 @@ public:
   /**
    * @name Index conversion
    *
-   * Functions in this group
-   * assume an object, which
-   * was created after sorting by
-   * block, such that each block
-   * forms a set of consecutive
-   * indices in the object.
-   * If applied to other objects,
-   * the numbers obtained from
-   * these functions are meaningless.
+   * Functions in this group assume an object, which was created after sorting
+   * by block, such that each block forms a set of consecutive indices in the
+   * object. If applied to other objects, the numbers obtained from these
+   * functions are meaningless.
    */
   //@{
 
   /**
-   * Return the block and the
-   * index within that block
-   * for the global index @p i. The
-   * first element of the pair is
-   * the block, the second the
-   * index within it.
+   * Return the block and the index within that block for the global index @p
+   * i. The first element of the pair is the block, the second the index
+   * within it.
    */
   std::pair<unsigned int,size_type>
   global_to_local (const size_type i) const;
 
   /**
-   * Return the global index of
-   * @p index in block @p block.
+   * Return the global index of @p index in block @p block.
    */
   size_type local_to_global (const unsigned int block,
                              const size_type index) const;
@@ -178,50 +151,40 @@ public:
   BlockIndices &operator = (const BlockIndices &b);
 
   /**
-   * Compare whether two objects
-   * are the same, i.e. whether the
-   * number of blocks and the sizes
-   * of all blocks are equal.
+   * Compare whether two objects are the same, i.e. whether the number of
+   * blocks and the sizes of all blocks are equal.
    */
   bool operator == (const BlockIndices &b) const;
 
   /**
-   * Swap the contents of these two
-   * objects.
+   * Swap the contents of these two objects.
    */
   void swap (BlockIndices &b);
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
 private:
   /**
-   * Number of blocks. While this
-   * value could be obtained
-   * through
-   * <tt>start_indices.size()-1</tt>,
-   * we cache this value for faster
-   * access.
+   * Number of blocks. While this value could be obtained through
+   * <tt>start_indices.size()-1</tt>, we cache this value for faster access.
    */
   unsigned int n_blocks;
 
   /**
-   * Global starting index of each
-   * vector. The last and redundant
-   * value is the total number of
-   * entries.
+   * Global starting index of each vector. The last and redundant value is the
+   * total number of entries.
    */
   std::vector<size_type> start_indices;
 };
 
 
 /**
- * Operator for logging BlockIndices. Writes the number of blocks, the
- * size of each block and the total size of the index field.
+ * Operator for logging BlockIndices. Writes the number of blocks, the size of
+ * each block and the total size of the index field.
  *
  * @ref BlockIndices
  * @author Guido Kanschat
@@ -258,9 +221,9 @@ template <typename number>     class BlockSparseMatrixEZ;
  * @code
  *   IsBlockMatrix<BlockSparseMatrix<double> >::value
  * @endcode
- * is true. This is sometimes useful in template contexts where we may
- * want to do things differently depending on whether a template type
- * denotes a regular or a block matrix type.
+ * is true. This is sometimes useful in template contexts where we may want to
+ * do things differently depending on whether a template type denotes a
+ * regular or a block matrix type.
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Wolfgang Bangerth, 2009
@@ -279,46 +242,37 @@ private:
   };
 
   /**
-   * Overload returning true if the class
-   * is derived from BlockMatrixBase,
-   * which is what block matrices do
-   * (with the exception of
+   * Overload returning true if the class is derived from BlockMatrixBase,
+   * which is what block matrices do (with the exception of
    * BlockSparseMatrixEZ).
    */
   template <typename T>
   static yes_type check_for_block_matrix (const BlockMatrixBase<T> *);
 
   /**
-   * Overload returning true if the class
-   * is derived from
-   * BlockSparsityPatternBase, which is
-   * what block sparsity patterns do.
+   * Overload returning true if the class is derived from
+   * BlockSparsityPatternBase, which is what block sparsity patterns do.
    */
   template <typename T>
   static yes_type check_for_block_matrix (const BlockSparsityPatternBase<T> *);
 
   /**
-   * Overload for BlockSparseMatrixEZ,
-   * which is the only block matrix not
-   * derived from BlockMatrixBase at the
-   * time of writing this class.
+   * Overload for BlockSparseMatrixEZ, which is the only block matrix not
+   * derived from BlockMatrixBase at the time of writing this class.
    */
   template <typename T>
   static yes_type check_for_block_matrix (const BlockSparseMatrixEZ<T> *);
 
   /**
-   * Catch all for all other potential
-   * matrix types that are not block
+   * Catch all for all other potential matrix types that are not block
    * matrices.
    */
   static no_type check_for_block_matrix (...);
 
 public:
   /**
-   * A statically computable value that
-   * indicates whether the template
-   * argument to this class is a block
-   * matrix (in fact whether the type is
+   * A statically computable value that indicates whether the template
+   * argument to this class is a block matrix (in fact whether the type is
    * derived from BlockMatrixBase<T>).
    */
   static const bool value = (sizeof(check_for_block_matrix
@@ -528,9 +482,9 @@ BlockIndices::memory_consumption () const
 
 
 /**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two objects.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two objects.
  *
  * @relates BlockIndices
  * @author Wolfgang Bangerth, 2000
index 3366348d75215101edfccb0aa4c36a7c2b46d862..62c9676f01a5f205e5ceeef5d50c55e293738bf9 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * @deprecated This class is experimental and will be
- * removed in a future release.
+ * @deprecated This class is experimental and will be removed in a future
+ * release.
  *
- * A vector of index sets listing the indices of small blocks of a
- * linear system. For each block, the indices in that block are
- * listed.
+ * A vector of index sets listing the indices of small blocks of a linear
+ * system. For each block, the indices in that block are listed.
  *
- * The focus of this class is on small blocks of degrees of freedom
- * associated with a single mesh cell or a small patch. These indices
- * may be contiguous or not and we do not optimize for the case they
- * are. For larger sets, the use of a vector of IndexSet objects might
- * be advisable.
+ * The focus of this class is on small blocks of degrees of freedom associated
+ * with a single mesh cell or a small patch. These indices may be contiguous
+ * or not and we do not optimize for the case they are. For larger sets, the
+ * use of a vector of IndexSet objects might be advisable.
  *
- * BlockList objects can conveniently be initialized with iterator
- * ranges from DoFHandler or MGDoFHandler, using either their cell or
- * multigrid indices. Other initializations are possible to be
- * implemented.
+ * BlockList objects can conveniently be initialized with iterator ranges from
+ * DoFHandler or MGDoFHandler, using either their cell or multigrid indices.
+ * Other initializations are possible to be implemented.
  *
  * @author Guido Kanschat
  * @date 2010
@@ -63,33 +60,23 @@ public:
   typedef block_container::const_iterator const_iterator;
 
   /**
-   * Since SparsityPattern can
-   * handle the tasks of BlockList,
-   * this function allows us to
-   * create one from an already
-   * filled BlockList. A first step
-   * to make BlockList obsolete.
+   * Since SparsityPattern can handle the tasks of BlockList, this function
+   * allows us to create one from an already filled BlockList. A first step to
+   * make BlockList obsolete.
    *
-   * The additional integer
-   * argument is the dimension of
-   * the vector space.
+   * The additional integer argument is the dimension of the vector space.
    */
   void create_sparsity_pattern(SparsityPattern &sparsity, size_type n) const;
 
   /**
-   * Add the indices in
-   * <tt>indices</tt> to block
-   * <tt>block</tt>, eliminating
+   * Add the indices in <tt>indices</tt> to block <tt>block</tt>, eliminating
    * repeated indices.
    */
   void add(size_type block, const std::vector<size_type> &indices);
 
   /**
-   * Add the indices in
-   * <tt>indices</tt> to block
-   * <tt>block</tt>, eliminating
-   * repeated indices. Only add
-   * those indices for which
+   * Add the indices in <tt>indices</tt> to block <tt>block</tt>, eliminating
+   * repeated indices. Only add those indices for which
    * <tt>selected_indices</tt> is true.
    */
   void add(size_type block,
@@ -98,25 +85,18 @@ public:
            size_type offset = 0);
 
   /**
-   * Just set up the correct size
-   * and assign indices to blocks later.
+   * Just set up the correct size and assign indices to blocks later.
    */
   void initialize(size_type n_blocks);
 
   /**
-   * Set up all index sets using an
-   * DoF iterator range. This
-   * function will call
-   * <tt>begin->get_dof_indices()</tt>
-   * with a signature like
-   * DoFCellAccessor::get_dof_indices().
-   * Typically, the iterators will
-   * loop over active cells of a
-   * triangulation.
+   * Set up all index sets using an DoF iterator range. This function will
+   * call <tt>begin->get_dof_indices()</tt> with a signature like
+   * DoFCellAccessor::get_dof_indices(). Typically, the iterators will loop
+   * over active cells of a triangulation.
    *
-   * In addition, the function
-   * needs the total number of
-   * blocks as its first argument.
+   * In addition, the function needs the total number of blocks as its first
+   * argument.
    */
   template <typename ITERATOR>
   void initialize(size_type n_blocks,
@@ -124,22 +104,15 @@ public:
                   const typename identity<ITERATOR>::type end);
 
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
-   * Set up all index sets using an
-   * DoF iterator range. This
-   * function will call
-   * <tt>begin->get_mg_dof_indices()</tt>
-   * with a signature like
-   * MGDoFCellAccessor::get_mg_dof_indices().
-   * Typically, the iterators loop
-   * over the cells of a single
-   * level or a Triangulation.
+   * Set up all index sets using an DoF iterator range. This function will
+   * call <tt>begin->get_mg_dof_indices()</tt> with a signature like
+   * MGDoFCellAccessor::get_mg_dof_indices(). Typically, the iterators loop
+   * over the cells of a single level or a Triangulation.
    *
-   * In addition, the function
-   * needs the total number of
-   * blocks as its first argument.
+   * In addition, the function needs the total number of blocks as its first
+   * argument.
    */
   template <typename ITERATOR>
   void initialize_mg(size_type n_blocks,
@@ -147,35 +120,21 @@ public:
                      const typename identity<ITERATOR>::type end) DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
-   * Set up all index sets using an
-   * DoF iterator range. This
-   * function will call
-   * <tt>begin->get_dof_indices()</tt>
-   * with a signature like
-   * DoFCellAccessor::get_dof_indices().
-   * Typically, the iterators will
-   * loop over active cells of a
-   * triangulation.
+   * Set up all index sets using an DoF iterator range. This function will
+   * call <tt>begin->get_dof_indices()</tt> with a signature like
+   * DoFCellAccessor::get_dof_indices(). Typically, the iterators will loop
+   * over active cells of a triangulation.
    *
-   * The argument vector
-   * <tt>selected_dofs</tt> should
-   * have the length  of dofs per
-   * cell (thus, this function is
-   * not suitable for hp), and a
-   * true value for each degree of
-   * freedom which should be added
-   * to the index set of this
-   * cell. If you are working on a
-   * single block of a block
-   * system, the <tt>offset</tt> is
-   * the start index of this block.
+   * The argument vector <tt>selected_dofs</tt> should have the length  of
+   * dofs per cell (thus, this function is not suitable for hp), and a true
+   * value for each degree of freedom which should be added to the index set
+   * of this cell. If you are working on a single block of a block system, the
+   * <tt>offset</tt> is the start index of this block.
    *
-   * In addition, the function
-   * needs the total number of
-   * blocks as its first argument.
+   * In addition, the function needs the total number of blocks as its first
+   * argument.
    */
   template <typename ITERATOR>
   void initialize(size_type n_blocks,
@@ -184,35 +143,21 @@ public:
                   const std::vector<bool> &selected_dofs,
                   size_type offset = 0) DEAL_II_DEPRECATED;
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
-   * Set up all index sets using an
-   * DoF iterator range. This
-   * function will call
-   * <tt>begin->get_mg_dof_indices()</tt>
-   * with a signature like
-   * MGDoFCellAccessor::get_mg_dof_indices().
-   * Typically, the iterators will
-   * loop over cells on a single
-   * level of a triangulation.
+   * Set up all index sets using an DoF iterator range. This function will
+   * call <tt>begin->get_mg_dof_indices()</tt> with a signature like
+   * MGDoFCellAccessor::get_mg_dof_indices(). Typically, the iterators will
+   * loop over cells on a single level of a triangulation.
    *
-   * The argument vector
-   * <tt>selected_dofs</tt> should
-   * have the length  of dofs per
-   * cell (thus, this function is
-   * not suitable for hp), and a
-   * true value for each degree of
-   * freedom which should be added
-   * to the index set of this
-   * cell. If you are working on a
-   * single block of a block
-   * system, the <tt>offset</tt> is
-   * the start index of this block.
+   * The argument vector <tt>selected_dofs</tt> should have the length  of
+   * dofs per cell (thus, this function is not suitable for hp), and a true
+   * value for each degree of freedom which should be added to the index set
+   * of this cell. If you are working on a single block of a block system, the
+   * <tt>offset</tt> is the start index of this block.
    *
-   * In addition, the function
-   * needs the total number of
-   * blocks as its first argument.
+   * In addition, the function needs the total number of blocks as its first
+   * argument.
    */
   template <typename ITERATOR>
   void initialize_mg(size_type n_blocks,
@@ -222,14 +167,10 @@ public:
                      size_type offset = 0) DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
-   * Same as initialize_mg(), but
-   * instead of gathering the
-   * degrees of freedom of a single
-   * cell into a block, gather all
-   * degrees of freedom of a patch
+   * Same as initialize_mg(), but instead of gathering the degrees of freedom
+   * of a single cell into a block, gather all degrees of freedom of a patch
    * around a vertex.
    */
   template <int dim, typename ITERATOR>
@@ -240,11 +181,9 @@ public:
                                     size_type offset = 0) DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
-   * Auxiliary function, counting
-   * the patches around vertices.
+   * Auxiliary function, counting the patches around vertices.
    */
   template <int dim, typename ITERATOR>
   unsigned int count_vertex_patches(
@@ -253,8 +192,7 @@ public:
     bool same_level_only) const DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This function will
-   * move to DoFTools.
+   * @deprecated This function will move to DoFTools.
    *
    */
   template <int dim, typename ITERATOR>
@@ -280,11 +218,8 @@ public:
    */
   const_iterator end(size_type block) const;
   /**
-   * Return the position of
-   * <tt>index</tt> in
-   * <tt>block</tt>, or
-   * numbers::invalid_size_type,
-   * if the index is not in the block.
+   * Return the position of <tt>index</tt> in <tt>block</tt>, or
+   * numbers::invalid_size_type, if the index is not in the block.
    */
   size_type local_index(size_type block, size_type index) const;
 
index 74021d0b60850b40b5a3854f53bb122974bd9116..18491b8c29a23cbff29dc6ef1537951441760787 100644 (file)
@@ -31,13 +31,12 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * A matrix with several copies of the same block on the diagonal.
  *
- * This matrix implements an @p m by @p m block matrix. Each
- * diagonal block consists of the same (non-block) matrix, while
- * off-diagonal blocks are void.
+ * This matrix implements an @p m by @p m block matrix. Each diagonal block
+ * consists of the same (non-block) matrix, while off-diagonal blocks are
+ * void.
  *
- * One special application is a one by one block matrix, allowing to
- * apply the @p vmult of the original matrix (or preconditioner) to a
- * block vector.
+ * One special application is a one by one block matrix, allowing to apply the
+ * @p vmult of the original matrix (or preconditioner) to a block vector.
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Guido Kanschat, 2000
@@ -47,9 +46,8 @@ class BlockDiagonalMatrix : public Subscriptor
 {
 public:
   /**
-   * Constructor for an @p n_blocks
-   * by @p n_blocks matrix with
-   * diagonal blocks @p M.
+   * Constructor for an @p n_blocks by @p n_blocks matrix with diagonal blocks
+   * @p M.
    */
   BlockDiagonalMatrix (const MATRIX       &M,
                        const unsigned int  n_blocks);
index 278da473fa78f21a56560b9953c722be9e14d0f6..56e8f0f826a98ab88ad927ac2745fd4e01e38072 100644 (file)
@@ -40,84 +40,71 @@ template <typename> class Vector;
 
 
 /**
- * Block matrix composed of different single matrices; these matrices
- * may even be of different types.
+ * Block matrix composed of different single matrices; these matrices may even
+ * be of different types.
  *
  * Given a set of arbitrary matrices <i>A<sub>i</sub></i>, this class
- * implements a block matrix with block entries of the form
- * <i>M<sub>jk</sub> = s<sub>jk</sub>A<sub>i</sub></i>.  Each
- * <i>A<sub>i</sub></i> may be used several times with different
- * prefix. The matrices are not copied into the BlockMatrixArray
- * object, but rather a PointerMatrix referencing each of them will be
- * stored along with factors and transposition flags.
+ * implements a block matrix with block entries of the form <i>M<sub>jk</sub>
+ * = s<sub>jk</sub>A<sub>i</sub></i>.  Each <i>A<sub>i</sub></i> may be used
+ * several times with different prefix. The matrices are not copied into the
+ * BlockMatrixArray object, but rather a PointerMatrix referencing each of
+ * them will be stored along with factors and transposition flags.
  *
- * Non-zero entries are registered by the function enter(), zero
- * entries are not stored at all. Using enter() with the same location
- * <tt>(i,j)</tt> several times will add the corresponding matrices in
- * matrix-vector multiplications. These matrices will not be actually
- * added, but the multiplications with them will be summed up.
+ * Non-zero entries are registered by the function enter(), zero entries are
+ * not stored at all. Using enter() with the same location <tt>(i,j)</tt>
+ * several times will add the corresponding matrices in matrix-vector
+ * multiplications. These matrices will not be actually added, but the
+ * multiplications with them will be summed up.
  *
- * @note This mechanism makes it impossible to access single entries
- * of BlockMatrixArray. In particular, (block) relaxation
- * preconditioners based on PreconditionRelaxation or
- * PreconditionBlock <b>cannot</b> be used with this class. If you
- * need a preconditioner for a BlockMatrixArray object, use
+ * @note This mechanism makes it impossible to access single entries of
+ * BlockMatrixArray. In particular, (block) relaxation preconditioners based
+ * on PreconditionRelaxation or PreconditionBlock <b>cannot</b> be used with
+ * this class. If you need a preconditioner for a BlockMatrixArray object, use
  * BlockTrianglePrecondition.
  *
  * <h3>Requirements on MATRIX</h3>
  *
- * The template argument <tt>MATRIX</tt> is a class providing the
- * matrix-vector multiplication functions vmult(), Tvmult(),
- * vmult_add() and Tvmult_add() used in this class, but with arguments
- * of type Vector&lt;number&gt; instead of
- * BlockVector&lt;number&gt;. Every matrix which can be used by
- * PointerMatrix is allowed, in particular SparseMatrix is a possible
- * entry type.
+ * The template argument <tt>MATRIX</tt> is a class providing the matrix-
+ * vector multiplication functions vmult(), Tvmult(), vmult_add() and
+ * Tvmult_add() used in this class, but with arguments of type
+ * Vector&lt;number&gt; instead of BlockVector&lt;number&gt;. Every matrix
+ * which can be used by PointerMatrix is allowed, in particular SparseMatrix
+ * is a possible entry type.
  *
- * <h3>Example program</h3>
- * We document the relevant parts of <tt>examples/doxygen/block_matrix_array.cc</tt>.
+ * <h3>Example program</h3> We document the relevant parts of
+ * <tt>examples/doxygen/block_matrix_array.cc</tt>.
  *
  * @dontinclude block_matrix_array.cc
  *
- * Obviously, we have to include the header file containing the definition
- * of BlockMatrixArray:
- * @skipline block_matrix_array.h
+ * Obviously, we have to include the header file containing the definition of
+ * BlockMatrixArray: @skipline block_matrix_array.h
  *
- * First, we set up some matrices to be entered into the blocks.
- * @skip main
+ * First, we set up some matrices to be entered into the blocks. @skip main
  * @until C.fill
  *
- * The BlockMatrixArray needs a VectorMemory&lt;Vector&lt;number&gt;
- * &gt; object to allocate auxiliary vectors. <tt>number</tt> must
- * equal the second template argument of BlockMatrixArray and also the
- * number type of the BlockVector used later. We use the
- * GrowingVectorMemory type, since it remembers the vector and avoids
- * reallocating.
+ * The BlockMatrixArray needs a VectorMemory&lt;Vector&lt;number&gt; &gt;
+ * object to allocate auxiliary vectors. <tt>number</tt> must equal the second
+ * template argument of BlockMatrixArray and also the number type of the
+ * BlockVector used later. We use the GrowingVectorMemory type, since it
+ * remembers the vector and avoids reallocating.
  *
  * @line Growing
  *
- * Now, we are ready to build a <i>2x2</i> BlockMatrixArray.
- * @line Block
- * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left block
- * @line enter
- * Now -1 times <tt>B1</tt> in the upper right block.
- * @line enter
- * We add the transpose of <tt>B2</tt> to the upper right block and
- * continue in a similar fashion. In the end, the block matrix
- * structure is printed into an LaTeX table.
- * @until latex
+ * Now, we are ready to build a <i>2x2</i> BlockMatrixArray. @line Block
+ * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left
+ * block @line enter Now -1 times <tt>B1</tt> in the upper right block. @line
+ * enter We add the transpose of <tt>B2</tt> to the upper right block and
+ * continue in a similar fashion. In the end, the block matrix structure is
+ * printed into an LaTeX table. @until latex
  *
  * Now, we set up vectors to be multiplied with this matrix and do a
- * multiplication.
- * @until vmult
+ * multiplication. @until vmult
  *
  * Finally, we solve a linear system with BlockMatrixArray, using no
- * preconditioning and the conjugate gradient method.
- * @until Error
+ * preconditioning and the conjugate gradient method. @until Error
  *
- * The remaining code of this sample program concerns preconditioning
- * and is described in the documentation of
- * BlockTrianglePrecondition.
+ * The remaining code of this sample program concerns preconditioning and is
+ * described in the documentation of BlockTrianglePrecondition.
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Guido Kanschat
@@ -133,33 +120,26 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Default constructor creating a
-   * useless object. initialize()
-   * must be called before using
-   * it.
+   * Default constructor creating a useless object. initialize() must be
+   * called before using it.
    */
   BlockMatrixArray ();
 
   /**
-   * Constructor fixing the
-   * dimensions.
+   * Constructor fixing the dimensions.
    */
   BlockMatrixArray (const unsigned int n_block_rows,
                     const unsigned int n_block_cols);
 
   /**
-   * Initialize object
-   * completely. This is the
-   * function to call for an object
-   * created by the default
-   * constructor.
+   * Initialize object completely. This is the function to call for an object
+   * created by the default constructor.
    */
   void initialize (const unsigned int n_block_rows,
                    const unsigned int n_block_cols);
 
   /**
-   * Constructor fixing the
-   * dimensions.
+   * Constructor fixing the dimensions.
    *
    * @deprecated The last argument is ignored. Use the constructor with only
    * the first two arguments.
@@ -169,11 +149,8 @@ public:
                     VectorMemory<Vector<number> > &mem) DEAL_II_DEPRECATED;
 
   /**
-   * Initialize object
-   * completely. This is the
-   * function to call for an object
-   * created by the default
-   * constructor.
+   * Initialize object completely. This is the function to call for an object
+   * created by the default constructor.
    *
    * @deprecated The last argument is ignored. Use the function with same name
    * but only the first two arguments.
@@ -183,30 +160,20 @@ public:
                    VectorMemory<Vector<number> > &mem) DEAL_II_DEPRECATED;
 
   /**
-   * Adjust the matrix to a new
-   * size and delete all blocks.
+   * Adjust the matrix to a new size and delete all blocks.
    */
   void reinit (const unsigned int n_block_rows,
                const unsigned int n_block_cols);
 
   /**
-   * Add a block matrix entry. The
-   * <tt>matrix</tt> is entered
-   * into a list of blocks for
-   * multiplication, together with
-   * its coordinates <tt>row</tt>
-   * and <tt>col</tt> as well as
-   * optional multiplication factor
-   * <tt>prefix</tt> and transpose
-   * flag <tt>transpose</tt>.
+   * Add a block matrix entry. The <tt>matrix</tt> is entered into a list of
+   * blocks for multiplication, together with its coordinates <tt>row</tt> and
+   * <tt>col</tt> as well as optional multiplication factor <tt>prefix</tt>
+   * and transpose flag <tt>transpose</tt>.
    *
-   * @note No check for consistency
-   * of block sizes is
-   * made. Therefore, entering a
-   * block of wrong dimension here
-   * will only lead to a
-   * ExcDimensionMismatch in one of
-   * the multiplication functions.
+   * @note No check for consistency of block sizes is made. Therefore,
+   * entering a block of wrong dimension here will only lead to a
+   * ExcDimensionMismatch in one of the multiplication functions.
    */
   template <class MATRIX>
   void enter (const MATRIX       &matrix,
@@ -216,14 +183,11 @@ public:
               const bool          transpose = false);
 
   /**
-   * Add an entry like with enter,
-   * but use PointerMatrixAux for
-   * matrices not having functions
-   * vmult_add() and TVmult_add().
+   * Add an entry like with enter, but use PointerMatrixAux for matrices not
+   * having functions vmult_add() and TVmult_add().
    *
-   * @deprecated The first argument
-   * is ignored. Use the function with same name
-   * but without the first argument.
+   * @deprecated The first argument is ignored. Use the function with same
+   * name but without the first argument.
    */
   template <class MATRIX>
   void enter_aux (VectorMemory<Vector<number> > &mem,
@@ -235,20 +199,17 @@ public:
 
 
   /**
-   * Delete all entries, i.e. reset
-   * the matrix to an empty state.
+   * Delete all entries, i.e. reset the matrix to an empty state.
    */
   void clear();
 
   /**
-   * Number of block-entries per
-   * column.
+   * Number of block-entries per column.
    */
   unsigned int n_block_rows () const;
 
   /**
-   * Number of block-entries per
-   * row.
+   * Number of block-entries per row.
    */
   unsigned int n_block_cols () const;
 
@@ -259,59 +220,44 @@ public:
               const BlockVector<number> &src) const;
 
   /**
-   * Matrix-vector multiplication
-   * adding to <tt>dst</tt>.
+   * Matrix-vector multiplication adding to <tt>dst</tt>.
    */
   void vmult_add (BlockVector<number> &dst,
                   const BlockVector<number> &src) const;
 
   /**
-   * Transposed matrix-vector
-   * multiplication.
+   * Transposed matrix-vector multiplication.
    */
   void Tvmult (BlockVector<number> &dst,
                const BlockVector<number> &src) const;
 
   /**
-   * Transposed matrix-vector
-   * multiplication adding to
-   * <tt>dst</tt>.
+   * Transposed matrix-vector multiplication adding to <tt>dst</tt>.
    */
   void Tvmult_add (BlockVector<number> &dst,
                    const BlockVector<number> &src) const;
 
   /**
-   * Matrix scalar product between
-   * two vectors (at least for a
-   * symmetric matrix).
+   * Matrix scalar product between two vectors (at least for a symmetric
+   * matrix).
    */
   number matrix_scalar_product (const BlockVector<number> &u,
                                 const BlockVector<number> &v) const;
 
   /**
-   * Compute $u^T M u$. This is the square
-   * of the norm induced by the matrix
-   * assuming the matrix is symmetric
-   * positive definitive.
+   * Compute $u^T M u$. This is the square of the norm induced by the matrix
+   * assuming the matrix is symmetric positive definitive.
    */
   number matrix_norm_square (const BlockVector<number> &u) const;
 
   /**
-   * Print the block structure as a
-   * LaTeX-array. This output will
-   * not be very intuitive, since
-   * the current object lacks
-   * knowledge about what the individual blocks represent or
-   * how they should be named. Instead, what
-   * you will see is an entry for each
-   * block showing all the matrices
-   * with their multiplication
-   * factors and possibly transpose
-   * marks. The matrices itself are
-   * named successively as they are encountered. If the same
-   * matrix is entered several
-   * times, it will be listed with
-   * different names.
+   * Print the block structure as a LaTeX-array. This output will not be very
+   * intuitive, since the current object lacks knowledge about what the
+   * individual blocks represent or how they should be named. Instead, what
+   * you will see is an entry for each block showing all the matrices with
+   * their multiplication factors and possibly transpose marks. The matrices
+   * itself are named successively as they are encountered. If the same matrix
+   * is entered several times, it will be listed with different names.
    *
    * As an example, consider the following code:
    * @code
@@ -330,19 +276,18 @@ public:
    *
    *  block.print_latex(std::cout);
    * @endcode
-   * The current function will then produce output of the following
-   * kind:
+   * The current function will then produce output of the following kind:
    * @code
    * \begin{array}{cc}
    *    M0+2xM1^T &     -3xM2-3xM3^T\\
    *    &      M4^T
    * \end{array}
    * @endcode
-   * Note how the individual blocks here are just numbered successively
-   * as <code>M0</code> to <code>M4</code> and that the output misses
-   * the fact that <code>M2</code> and <code>M3</code> are, in fact,
-   * the same matrix. Nevertheless, the output at least gives some
-   * kind of idea of the block structure of this matrix.
+   * Note how the individual blocks here are just numbered successively as
+   * <code>M0</code> to <code>M4</code> and that the output misses the fact
+   * that <code>M2</code> and <code>M3</code> are, in fact, the same matrix.
+   * Nevertheless, the output at least gives some kind of idea of the block
+   * structure of this matrix.
    */
   template <class STREAM>
   void print_latex (STREAM &out) const;
@@ -351,12 +296,9 @@ protected:
   /**
    * Internal data structure.
    *
-   * For each entry of a
-   * BlockMatrixArray, its
-   * position, matrix, prefix and
-   * optional transposition must be
-   * stored. This structure
-   * encapsulates all of them.
+   * For each entry of a BlockMatrixArray, its position, matrix, prefix and
+   * optional transposition must be stored. This structure encapsulates all of
+   * them.
    *
    * @author Guido Kanschat, 2000, 2001
    */
@@ -364,11 +306,8 @@ protected:
   {
   public:
     /**
-     * Constructor initializing
-     * all data fields. A
-     * PointerMatrix object is
-     * generated for
-     * <tt>matrix</tt>.
+     * Constructor initializing all data fields. A PointerMatrix object is
+     * generated for <tt>matrix</tt>.
      */
     template<class MATRIX>
     Entry (const MATRIX &matrix,
@@ -376,50 +315,37 @@ protected:
            double prefix, bool transpose);
 
     /**
-     * Copy constructor
-     * invalidating the old
-     * object. Since it is only
-     * used for entering
-     * temporary objects into a
-     * vector, this is ok.
+     * Copy constructor invalidating the old object. Since it is only used for
+     * entering temporary objects into a vector, this is ok.
      *
-     * For a deep copy, we would
-     * need a reproduction
-     * operator in
+     * For a deep copy, we would need a reproduction operator in
      * PointerMatixBase.
      */
     Entry(const Entry &);
 
     /**
-     * Destructor, where we
-     * delete the PointerMatrix
-     * created by the
+     * Destructor, where we delete the PointerMatrix created by the
      * constructor.
      */
     ~Entry();
 
     /**
-     * Row number in the block
-     * matrix.
+     * Row number in the block matrix.
      */
     size_type row;
 
     /**
-     * Column number in the block
-     * matrix.
+     * Column number in the block matrix.
      */
     size_type col;
 
     /**
-     * Factor in front of the matrix
-     * block.
+     * Factor in front of the matrix block.
      */
     double prefix;
 
     /**
-     * Indicates that matrix block
-     * must be transposed for
-     * multiplication.
+     * Indicates that matrix block must be transposed for multiplication.
      */
     bool transpose;
 
@@ -430,8 +356,7 @@ protected:
   };
 
   /**
-   * Array of block entries in the
-   * matrix.
+   * Array of block entries in the matrix.
    */
   std::vector<Entry> entries;
 
@@ -452,55 +377,46 @@ private:
 /**
  * Inversion of a block-triangular matrix.
  *
- * In this block matrix, the inverses of the diagonal blocks are
- * stored together with the off-diagonal blocks of a block
- * matrix. Then, forward or backward insertion is performed
- * block-wise. The diagonal blocks are NOT inverted for this purpose!
+ * In this block matrix, the inverses of the diagonal blocks are stored
+ * together with the off-diagonal blocks of a block matrix. Then, forward or
+ * backward insertion is performed block-wise. The diagonal blocks are NOT
+ * inverted for this purpose!
  *
- * Like for all preconditioners, the preconditioning operation is
- * performed by the vmult() member function.
+ * Like for all preconditioners, the preconditioning operation is performed by
+ * the vmult() member function.
  *
- * @note While block indices may be duplicated (see BlockMatrixArray)
- * to add blocks, this has to be used with caution, since
- * summing up the inverse of two blocks does not yield the inverse of
- * the sum. While the latter would be desirable, we can only perform
- * the first.
+ * @note While block indices may be duplicated (see BlockMatrixArray) to add
+ * blocks, this has to be used with caution, since summing up the inverse of
+ * two blocks does not yield the inverse of the sum. While the latter would be
+ * desirable, we can only perform the first.
  *
- * The implementation may be a little clumsy, but it should be
- * sufficient as long as the block sizes are much larger than the
- * number of blocks.
+ * The implementation may be a little clumsy, but it should be sufficient as
+ * long as the block sizes are much larger than the number of blocks.
  *
- * <h3>Example</h3>
- * Here, we document the second part of
- * <tt>examples/doxygen/block_matrix_array.cc</tt>. For the beginning
- * of this file, see BlockMatrixArray.
+ * <h3>Example</h3> Here, we document the second part of
+ * <tt>examples/doxygen/block_matrix_array.cc</tt>. For the beginning of this
+ * file, see BlockMatrixArray.
  *
- * In order to set up the preconditioner, we have to compute the
- * inverses of the diagonal blocks ourselves. Since we used FullMatrix
- * objects, this is fairly easy.
- * @dontinclude block_matrix_array.cc
- * @skip Error
- * @until Cinv.invert
+ * In order to set up the preconditioner, we have to compute the inverses of
+ * the diagonal blocks ourselves. Since we used FullMatrix objects, this is
+ * fairly easy. @dontinclude block_matrix_array.cc @skip Error @until
+ * Cinv.invert
  *
- * After creating a <i>2x2</i> BlockTrianglePrecondition object, we
- * only fill its diagonals. The scaling factor <i>1/2</i> used for
- * <tt>A</tt> is the reciprocal of the scaling factor used for the
- * <tt>matrix</tt> itself. Remember, this preconditioner actually
- * <b>multiplies</b> with the diagonal blocks.
- * @until Cinv
+ * After creating a <i>2x2</i> BlockTrianglePrecondition object, we only fill
+ * its diagonals. The scaling factor <i>1/2</i> used for <tt>A</tt> is the
+ * reciprocal of the scaling factor used for the <tt>matrix</tt> itself.
+ * Remember, this preconditioner actually <b>multiplies</b> with the diagonal
+ * blocks. @until Cinv
  *
- * Now, we have a block Jacobi preconditioner, which is still
- * symmetric, since the blocks are symmetric. Therefore, we can still
- * use the preconditioned conjugate gradient method.
- * @until Error
+ * Now, we have a block Jacobi preconditioner, which is still symmetric, since
+ * the blocks are symmetric. Therefore, we can still use the preconditioned
+ * conjugate gradient method. @until Error
  *
  * Now, we enter the subdiagonal block. This is the same as in
- * <tt>matrix</tt>.
- * @until B2
+ * <tt>matrix</tt>. @until B2
  *
- * Since the preconditioner is not symmetric anymore, we use the GMRES
- * method for solving.
- * @until Error
+ * Since the preconditioner is not symmetric anymore, we use the GMRES method
+ * for solving. @until Error
  *
  *
  * @ingroup Preconditioners
@@ -517,26 +433,20 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Default constructor creating a
-   * useless object. initialize()
-   * must be called before using
-   * it.
+   * Default constructor creating a useless object. initialize() must be
+   * called before using it.
    */
   BlockTrianglePrecondition ();
 
   /**
-   * Constructor. This matrix must be
-   * block-quadratic, and
-   * <tt>n_blocks</tt> is the
-   * number of blocks in each direction.
+   * Constructor. This matrix must be block-quadratic, and <tt>n_blocks</tt>
+   * is the number of blocks in each direction.
    */
   BlockTrianglePrecondition (const unsigned int n_blocks);
 
   /**
-   * Constructor. This matrix must be
-   * block-quadratic. The additional
-   * parameter allows for backward
-   * insertion instead of forward.
+   * Constructor. This matrix must be block-quadratic. The additional
+   * parameter allows for backward insertion instead of forward.
    *
    * @deprecated The second argument is ignored. Use the constructor with only
    * the first and third argument.
@@ -546,32 +456,25 @@ public:
                              const bool backward = false) DEAL_II_DEPRECATED;
 
   /**
-   * Initialize object
-   * completely. This is the
-   * function to call for an object
-   * created by the default
-   * constructor.
+   * Initialize object completely. This is the function to call for an object
+   * created by the default constructor.
    *
-   * @deprecated The second argument
-   * is ignored. Use the function without that argument.
+   * @deprecated The second argument is ignored. Use the function without that
+   * argument.
    */
   void initialize (const unsigned int n_block_rows,
                    VectorMemory<Vector<number> > &mem,
                    const bool backward = false) DEAL_II_DEPRECATED;
 
   /**
-   * Resize preconditioner to a new
-   * size and clear all blocks.
+   * Resize preconditioner to a new size and clear all blocks.
    */
   void reinit (const unsigned int n_block_rows);
 
 
   /**
-   * Enter a block. This calls
-   * BlockMatrixArray::enter(). Remember
-   * that the diagonal blocks
-   * should actually be inverse
-   * matrices or preconditioners.
+   * Enter a block. This calls BlockMatrixArray::enter(). Remember that the
+   * diagonal blocks should actually be inverse matrices or preconditioners.
    */
   template <class MATRIX>
   void enter (const MATRIX   &matrix,
@@ -581,15 +484,11 @@ public:
               const bool      transpose = false);
 
   /**
-   * Enter a block. This calls
-   * BlockMatrixArray::enter_aux(). Remember
-   * that the diagonal blocks
-   * should actually be inverse
-   * matrices or preconditioners.
+   * Enter a block. This calls BlockMatrixArray::enter_aux(). Remember that
+   * the diagonal blocks should actually be inverse matrices or
+   * preconditioners.
    *
-   * @deprecated The first
-   * argument is ignored. Use
-   * enter() instead.
+   * @deprecated The first argument is ignored. Use enter() instead.
    */
   template <class MATRIX>
   void enter_aux (VectorMemory<Vector<double> > &mem,
@@ -606,8 +505,7 @@ public:
               const BlockVector<number> &src) const;
 
   /**
-   * Preconditioning
-   * adding to <tt>dst</tt>.
+   * Preconditioning adding to <tt>dst</tt>.
    */
   void vmult_add (BlockVector<number> &dst,
                   const BlockVector<number> &src) const;
@@ -619,8 +517,7 @@ public:
                const BlockVector<number> &src) const;
 
   /**
-   * Transposed preconditioning
-   * adding to <tt>dst</tt>.
+   * Transposed preconditioning adding to <tt>dst</tt>.
    */
   void Tvmult_add (BlockVector<number> &dst,
                    const BlockVector<number> &src) const;
@@ -643,26 +540,22 @@ public:
   using BlockMatrixArray<number>::Subscriptor::subscribe;
   using BlockMatrixArray<number>::Subscriptor::unsubscribe;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
-   * Each diagonal block must
-   * contain one and only one
-   * matrix. If this exception is
-   * thrown, you did not enter a
-   * matrix here.
+   * Each diagonal block must contain one and only one matrix. If this
+   * exception is thrown, you did not enter a matrix here.
    */
   DeclException1(ExcNoDiagonal,
                  size_type,
                  << "No diagonal entry was added for block " << arg1);
 
   /**
-   * Each diagonal block must
-   * contain one and only one
-   * matrix. If this exception is
-   * thrown, you entered a second
-   * matrix here.
+   * Each diagonal block must contain one and only one matrix. If this
+   * exception is thrown, you entered a second matrix here.
    */
   DeclException1(ExcMultipleDiagonal,
                  size_type,
@@ -671,10 +564,8 @@ public:
   //@}
 private:
   /**
-   * Add all off-diagonal
-   * contributions and return the
-   * entry of the diagonal element
-   * for one row.
+   * Add all off-diagonal contributions and return the entry of the diagonal
+   * element for one row.
    */
   void do_row (BlockVector<number> &dst,
                size_type row_num) const;
index 268feb777bbfe27f7edfb9fb450dd2d2aab2a23b..44f91961428d6063913937f3a979d9107d48eed9 100644 (file)
@@ -50,9 +50,8 @@ template <typename> class MatrixIterator;
 namespace BlockMatrixIterators
 {
   /**
-   * Base class for block matrix
-   * accessors, implementing the
-   * stepping through a matrix.
+   * Base class for block matrix accessors, implementing the stepping through
+   * a matrix.
    */
   template <class BlockMatrix>
   class AccessorBase
@@ -64,47 +63,38 @@ namespace BlockMatrixIterators
     typedef types::global_dof_index size_type;
 
     /**
-     * Typedef the value type of the
-     * matrix we point into.
+     * Typedef the value type of the matrix we point into.
      */
     typedef typename BlockMatrix::value_type value_type;
 
     /**
-     * Initialize data fields to
-     * default values.
+     * Initialize data fields to default values.
      */
     AccessorBase ();
 
     /**
-     * Block row of the
-     * element represented by
-     * this object.
+     * Block row of the element represented by this object.
      */
     unsigned int block_row() const;
 
     /**
-     * Block column of the
-     * element represented by
-     * this object.
+     * Block column of the element represented by this object.
      */
     unsigned int block_column() const;
 
   protected:
     /**
-     * Block row into which we presently
-     * point.
+     * Block row into which we presently point.
      */
     unsigned int row_block;
 
     /**
-     * Block column into which we
-     * presently point.
+     * Block column into which we presently point.
      */
     unsigned int col_block;
 
     /**
-     * Let the iterator class be a
-     * friend.
+     * Let the iterator class be a friend.
      */
     template <typename>
     friend class MatrixIterator;
@@ -113,16 +103,14 @@ namespace BlockMatrixIterators
 
 
   /**
-   * Accessor classes in
-   * block matrices.
+   * Accessor classes in block matrices.
    */
   template <class BlockMatrix, bool ConstNess>
   class Accessor;
 
 
   /**
-   * Block matrix accessor for non
-   * const matrices.
+   * Block matrix accessor for non const matrices.
    */
   template <class BlockMatrix>
   class Accessor<BlockMatrix, false>
@@ -136,50 +124,39 @@ namespace BlockMatrixIterators
     typedef types::global_dof_index size_type;
 
     /**
-     * Type of the matrix used in
-     * this accessor.
+     * Type of the matrix used in this accessor.
      */
     typedef BlockMatrix MatrixType;
 
     /**
-     * Typedef the value type of the
-     * matrix we point into.
+     * Typedef the value type of the matrix we point into.
      */
     typedef typename BlockMatrix::value_type value_type;
 
     /**
-     * Constructor. Since we use
-     * accessors only for read
-     * access, a const matrix
-     * pointer is sufficient.
+     * Constructor. Since we use accessors only for read access, a const
+     * matrix pointer is sufficient.
      *
-     * Place the iterator at the
-     * beginning of the given row of the
-     * matrix, or create the end pointer
-     * if @p row equals the total number
-     * of rows in the matrix.
+     * Place the iterator at the beginning of the given row of the matrix, or
+     * create the end pointer if @p row equals the total number of rows in the
+     * matrix.
      */
     Accessor (BlockMatrix *m,
               const size_type row,
               const size_type col);
 
     /**
-     * Row number of the element
-     * represented by this
-     * object.
+     * Row number of the element represented by this object.
      */
     size_type row() const;
 
     /**
-     * Column number of the
-     * element represented by
-     * this object.
+     * Column number of the element represented by this object.
      */
     size_type column() const;
 
     /**
-     * Value of the entry at the
-     * current position.
+     * Value of the entry at the current position.
      */
     value_type value() const;
 
@@ -195,8 +172,7 @@ namespace BlockMatrixIterators
     BlockMatrix *matrix;
 
     /**
-     * Iterator of the underlying matrix
-     * class.
+     * Iterator of the underlying matrix class.
      */
     typename BlockMatrix::BlockType::iterator base_iterator;
 
@@ -206,8 +182,7 @@ namespace BlockMatrixIterators
     void advance ();
 
     /**
-     * Compare this accessor with another
-     * one for equality.
+     * Compare this accessor with another one for equality.
      */
     bool operator == (const Accessor &a) const;
 
@@ -216,9 +191,8 @@ namespace BlockMatrixIterators
   };
 
   /**
-   * Block matrix accessor for
-   * constant matrices, implementing
-   * the stepping through a matrix.
+   * Block matrix accessor for constant matrices, implementing the stepping
+   * through a matrix.
    */
   template <class BlockMatrix>
   class Accessor<BlockMatrix, true>
@@ -232,56 +206,44 @@ namespace BlockMatrixIterators
     typedef types::global_dof_index size_type;
 
     /**
-     * Type of the matrix used in
-     * this accessor.
+     * Type of the matrix used in this accessor.
      */
     typedef const BlockMatrix MatrixType;
 
     /**
-     * Typedef the value type of the
-     * matrix we point into.
+     * Typedef the value type of the matrix we point into.
      */
     typedef typename BlockMatrix::value_type value_type;
 
     /**
-     * Constructor. Since we use
-     * accessors only for read
-     * access, a const matrix
-     * pointer is sufficient.
+     * Constructor. Since we use accessors only for read access, a const
+     * matrix pointer is sufficient.
      *
-     * Place the iterator at the
-     * beginning of the given row of the
-     * matrix, or create the end pointer
-     * if @p row equals the total number
-     * of rows in the matrix.
+     * Place the iterator at the beginning of the given row of the matrix, or
+     * create the end pointer if @p row equals the total number of rows in the
+     * matrix.
      */
     Accessor (const BlockMatrix *m,
               const size_type row,
               const size_type col);
 
     /**
-     * Initalize const accessor
-     * from non const accessor.
+     * Initalize const accessor from non const accessor.
      */
     Accessor(const Accessor<BlockMatrix, false> &);
 
     /**
-     * Row number of the element
-     * represented by this
-     * object.
+     * Row number of the element represented by this object.
      */
     size_type row() const;
 
     /**
-     * Column number of the
-     * element represented by
-     * this object.
+     * Column number of the element represented by this object.
      */
     size_type column() const;
 
     /**
-     * Value of the entry at the
-     * current position.
+     * Value of the entry at the current position.
      */
     value_type value() const;
   protected:
@@ -291,8 +253,7 @@ namespace BlockMatrixIterators
     const BlockMatrix *matrix;
 
     /**
-     * Iterator of the underlying matrix
-     * class.
+     * Iterator of the underlying matrix class.
      */
     typename BlockMatrix::BlockType::const_iterator base_iterator;
 
@@ -302,14 +263,12 @@ namespace BlockMatrixIterators
     void advance ();
 
     /**
-     * Compare this accessor with another
-     * one for equality.
+     * Compare this accessor with another one for equality.
      */
     bool operator == (const Accessor &a) const;
 
     /**
-     * Let the iterator class be a
-     * friend.
+     * Let the iterator class be a friend.
      */
     template <typename>
     friend class dealii::MatrixIterator;
@@ -328,25 +287,24 @@ namespace BlockMatrixIterators
  * blocks of this matrix is the type of the template argument, and can, for
  * example be the usual SparseMatrix or PETScWrappers::SparseMatrix.
  *
- * In addition to the usual matrix access and linear algebra
- * functions, there are functions block() which allow access to the
- * different blocks of the matrix. This may, for example, be of help
- * when you want to implement Schur complement methods, or block
- * preconditioners, where each block belongs to a specific component
- * of the equation you are presently discretizing.
+ * In addition to the usual matrix access and linear algebra functions, there
+ * are functions block() which allow access to the different blocks of the
+ * matrix. This may, for example, be of help when you want to implement Schur
+ * complement methods, or block preconditioners, where each block belongs to a
+ * specific component of the equation you are presently discretizing.
  *
- * Note that the numbers of blocks and rows are implicitly determined
- * by the sparsity pattern objects used.
+ * Note that the numbers of blocks and rows are implicitly determined by the
+ * sparsity pattern objects used.
  *
  * Objects of this type are frequently used when a system of differential
- * equations has solutions with variables that fall into different
- * classes. For example, solutions of the Stokes or Navier-Stokes equations
- * have @p dim velocity components and one pressure component. In this case,
- * it may make sense to consider the linear system of equations as a system of
- * 2x2 blocks, and one can construct preconditioners or solvers based on this
- * 2x2 block structure. This class can help you in these cases, as it allows
- * to view the matrix alternatively as one big matrix, or as a number of
- * individual blocks.
+ * equations has solutions with variables that fall into different classes.
+ * For example, solutions of the Stokes or Navier-Stokes equations have @p dim
+ * velocity components and one pressure component. In this case, it may make
+ * sense to consider the linear system of equations as a system of 2x2 blocks,
+ * and one can construct preconditioners or solvers based on this 2x2 block
+ * structure. This class can help you in these cases, as it allows to view the
+ * matrix alternatively as one big matrix, or as a number of individual
+ * blocks.
  *
  *
  * <h3>Inheriting from this class</h3>
@@ -361,14 +319,13 @@ namespace BlockMatrixIterators
  *
  *
  * Most of the functions take a vector or block vector argument. These
- * functions can, in general, only successfully be compiled if the
- * individual blocks of this matrix implement the respective functions
- * operating on the vector type in question. For example, if you have
- * a block sparse matrix over deal.II SparseMatrix objects, then you
- * will likely not be able to form the matrix-vector multiplication
- * with a block vector over PETScWrappers::SparseMatrix objects. If
- * you attempt anyway, you will likely get a number of compiler
- * errors.
+ * functions can, in general, only successfully be compiled if the individual
+ * blocks of this matrix implement the respective functions operating on the
+ * vector type in question. For example, if you have a block sparse matrix
+ * over deal.II SparseMatrix objects, then you will likely not be able to form
+ * the matrix-vector multiplication with a block vector over
+ * PETScWrappers::SparseMatrix objects. If you attempt anyway, you will likely
+ * get a number of compiler errors.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -382,14 +339,12 @@ class BlockMatrixBase : public Subscriptor
 {
 public:
   /**
-   * Typedef the type of the underlying
-   * matrix.
+   * Typedef the type of the underlying matrix.
    */
   typedef MatrixType BlockType;
 
   /**
-   * Type of matrix entries. In analogy to
-   * the STL container classes.
+   * Type of matrix entries. In analogy to the STL container classes.
    */
   typedef typename BlockType::value_type value_type;
   typedef value_type             *pointer;
@@ -418,39 +373,24 @@ public:
   ~BlockMatrixBase ();
 
   /**
-   * Copy the given matrix to this
-   * one.  The operation throws an
-   * error if the sparsity patterns
-   * of the two involved matrices
-   * do not point to the same
-   * object, since in this case the
-   * copy operation is
-   * cheaper. Since this operation
-   * is notheless not for free, we
-   * do not make it available
-   * through operator=(), since
-   * this may lead to unwanted
-   * usage, e.g. in copy arguments
-   * to functions, which should
-   * really be arguments by
-   * reference.
+   * Copy the given matrix to this one.  The operation throws an error if the
+   * sparsity patterns of the two involved matrices do not point to the same
+   * object, since in this case the copy operation is cheaper. Since this
+   * operation is notheless not for free, we do not make it available through
+   * operator=(), since this may lead to unwanted usage, e.g. in copy
+   * arguments to functions, which should really be arguments by reference.
    *
-   * The source matrix may be a
-   * matrix of arbitrary type, as
-   * long as its data type is
-   * convertible to the data type
-   * of this matrix.
+   * The source matrix may be a matrix of arbitrary type, as long as its data
+   * type is convertible to the data type of this matrix.
    *
-   * The function returns a
-   * reference to <tt>this</tt>.
+   * The function returns a reference to <tt>this</tt>.
    */
   template <class BlockMatrixType>
   BlockMatrixBase &
   copy_from (const BlockMatrixType &source);
 
   /**
-   * Access the block with the
-   * given coordinates.
+   * Access the block with the given coordinates.
    */
   BlockType &
   block (const unsigned int row,
@@ -458,86 +398,61 @@ public:
 
 
   /**
-   * Access the block with the
-   * given coordinates. Version for
-   * constant objects.
+   * Access the block with the given coordinates. Version for constant
+   * objects.
    */
   const BlockType &
   block (const unsigned int row,
          const unsigned int column) const;
 
   /**
-   * Return the dimension of the
-   * image space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the image space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type m () const;
 
   /**
-   * Return the dimension of the
-   * range space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the range space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type n () const;
 
 
   /**
-   * Return the number of blocks in
-   * a column. Returns zero if no
-   * sparsity pattern is presently
-   * associated to this matrix.
+   * Return the number of blocks in a column. Returns zero if no sparsity
+   * pattern is presently associated to this matrix.
    */
   unsigned int n_block_rows () const;
 
   /**
-   * Return the number of blocks in
-   * a row. Returns zero if no
-   * sparsity pattern is presently
-   * associated to this matrix.
+   * Return the number of blocks in a row. Returns zero if no sparsity pattern
+   * is presently associated to this matrix.
    */
   unsigned int n_block_cols () const;
 
   /**
-   * Set the element <tt>(i,j)</tt>
-   * to <tt>value</tt>. Throws an
-   * error if the entry does not
-   * exist or if <tt>value</tt> is
-   * not a finite number. Still, it
-   * is allowed to store zero
-   * values in non-existent fields.
+   * Set the element <tt>(i,j)</tt> to <tt>value</tt>. Throws an error if the
+   * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+   * it is allowed to store zero values in non-existent fields.
    */
   void set (const size_type i,
             const size_type j,
             const value_type value);
 
   /**
-   * Set all elements given in a
-   * FullMatrix into the sparse matrix
-   * locations given by
-   * <tt>indices</tt>. In other words,
-   * this function writes the elements
-   * in <tt>full_matrix</tt> into the
-   * calling matrix, using the
-   * local-to-global indexing specified
-   * by <tt>indices</tt> for both the
-   * rows and the columns of the
-   * matrix. This function assumes a
-   * quadratic sparse matrix and a
-   * quadratic full_matrix, the usual
-   * situation in FE calculations.
+   * Set all elements given in a FullMatrix into the sparse matrix locations
+   * given by <tt>indices</tt>. In other words, this function writes the
+   * elements in <tt>full_matrix</tt> into the calling matrix, using the
+   * local-to-global indexing specified by <tt>indices</tt> for both the rows
+   * and the columns of the matrix. This function assumes a quadratic sparse
+   * matrix and a quadratic full_matrix, the usual situation in FE
+   * calculations.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be set anyway or
-   * they should be filtered away (and
-   * not change the previous content in
-   * the respective element if it
-   * exists). The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are treated.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be set anyway or they should be filtered away
+   * (and not change the previous content in the respective element if it
+   * exists). The default value is <tt>false</tt>, i.e., even zero values are
+   * treated.
    */
   template <typename number>
   void set (const std::vector<size_type> &indices,
@@ -545,11 +460,9 @@ public:
             const bool                    elide_zero_values = false);
 
   /**
-   * Same function as before, but now
-   * including the possibility to use
-   * rectangular full_matrices and
-   * different local-to-global indexing
-   * on rows and columns, respectively.
+   * Same function as before, but now including the possibility to use
+   * rectangular full_matrices and different local-to-global indexing on rows
+   * and columns, respectively.
    */
   template <typename number>
   void set (const std::vector<size_type> &row_indices,
@@ -558,22 +471,14 @@ public:
             const bool                    elide_zero_values = false);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix with
-   * column indices as given by
-   * <tt>col_indices</tt> to the
-   * respective value.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be set anyway or
-   * they should be filtered away (and
-   * not change the previous content in
-   * the respective element if it
-   * exists). The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are treated.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be set anyway or they should be filtered away
+   * (and not change the previous content in the respective element if it
+   * exists). The default value is <tt>false</tt>, i.e., even zero values are
+   * treated.
    */
   template <typename number>
   void set (const size_type row,
@@ -582,20 +487,13 @@ public:
             const bool                    elide_zero_values = false);
 
   /**
-   * Set several elements to values
-   * given by <tt>values</tt> in a
-   * given row in columns given by
-   * col_indices into the sparse
-   * matrix.
+   * Set several elements to values given by <tt>values</tt> in a given row in
+   * columns given by col_indices into the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be inserted anyway
-   * or they should be filtered
-   * away. The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are inserted/replaced.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be inserted anyway or they should be filtered
+   * away. The default value is <tt>false</tt>, i.e., even zero values are
+   * inserted/replaced.
    */
   template <typename number>
   void set (const size_type  row,
@@ -605,44 +503,27 @@ public:
             const bool       elide_zero_values = false);
 
   /**
-   * Add <tt>value</tt> to the
-   * element (<i>i,j</i>).  Throws
-   * an error if the entry does not
-   * exist or if <tt>value</tt> is
-   * not a finite number. Still, it
-   * is allowed to store zero
-   * values in non-existent fields.
+   * Add <tt>value</tt> to the element (<i>i,j</i>).  Throws an error if the
+   * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+   * it is allowed to store zero values in non-existent fields.
    */
   void add (const size_type i,
             const size_type j,
             const value_type value);
 
   /**
-   * Add all elements given in a
-   * FullMatrix<double> into sparse
-   * matrix locations given by
-   * <tt>indices</tt>. In other words,
-   * this function adds the elements in
-   * <tt>full_matrix</tt> to the
-   * respective entries in calling
-   * matrix, using the local-to-global
-   * indexing specified by
-   * <tt>indices</tt> for both the rows
-   * and the columns of the
-   * matrix. This function assumes a
-   * quadratic sparse matrix and a
-   * quadratic full_matrix, the usual
-   * situation in FE calculations.
+   * Add all elements given in a FullMatrix<double> into sparse matrix
+   * locations given by <tt>indices</tt>. In other words, this function adds
+   * the elements in <tt>full_matrix</tt> to the respective entries in calling
+   * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+   * for both the rows and the columns of the matrix. This function assumes a
+   * quadratic sparse matrix and a quadratic full_matrix, the usual situation
+   * in FE calculations.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const std::vector<size_type> &indices,
@@ -650,11 +531,9 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Same function as before, but now
-   * including the possibility to use
-   * rectangular full_matrices and
-   * different local-to-global indexing
-   * on rows and columns, respectively.
+   * Same function as before, but now including the possibility to use
+   * rectangular full_matrices and different local-to-global indexing on rows
+   * and columns, respectively.
    */
   template <typename number>
   void add (const std::vector<size_type> &row_indices,
@@ -663,21 +542,13 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix with
-   * column indices as given by
-   * <tt>col_indices</tt> to the
-   * respective value.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const size_type row,
@@ -686,21 +557,13 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Add an array of values given by
-   * <tt>values</tt> in the given
-   * global matrix row at columns
-   * specified by col_indices in the
-   * sparse matrix.
+   * Add an array of values given by <tt>values</tt> in the given global
+   * matrix row at columns specified by col_indices in the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const size_type  row,
@@ -711,81 +574,53 @@ public:
             const bool       col_indices_are_sorted = false);
 
   /**
-   * Add <tt>matrix</tt> scaled by
-   * <tt>factor</tt> to this matrix,
-   * i.e. the matrix
-   * <tt>factor*matrix</tt> is added to
-   * <tt>this</tt>. If the sparsity
-   * pattern of the calling matrix does
-   * not contain all the elements in
-   * the sparsity pattern of the input
-   * matrix, this function will throw
-   * an exception.
+   * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
+   * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. If the sparsity
+   * pattern of the calling matrix does not contain all the elements in the
+   * sparsity pattern of the input matrix, this function will throw an
+   * exception.
    */
   void add (const value_type                   factor,
             const BlockMatrixBase<MatrixType> &matrix);
 
   /**
-   * Return the value of the entry
-   * (i,j).  This may be an
-   * expensive operation and you
-   * should always take care where
-   * to call this function.  In
-   * order to avoid abuse, this
-   * function throws an exception
-   * if the wanted element does not
-   * exist in the matrix.
+   * Return the value of the entry (i,j).  This may be an expensive operation
+   * and you should always take care where to call this function.  In order to
+   * avoid abuse, this function throws an exception if the wanted element does
+   * not exist in the matrix.
    */
   value_type operator () (const size_type i,
                           const size_type j) const;
 
   /**
-   * This function is mostly like
-   * operator()() in that it
-   * returns the value of the
-   * matrix entry <tt>(i,j)</tt>. The only
-   * difference is that if this
-   * entry does not exist in the
-   * sparsity pattern, then instead
-   * of raising an exception, zero
-   * is returned. While this may be
-   * convenient in some cases, note
-   * that it is simple to write
-   * algorithms that are slow
-   * compared to an optimal
-   * solution, since the sparsity
-   * of the matrix is not used.
+   * This function is mostly like operator()() in that it returns the value of
+   * the matrix entry <tt>(i,j)</tt>. The only difference is that if this
+   * entry does not exist in the sparsity pattern, then instead of raising an
+   * exception, zero is returned. While this may be convenient in some cases,
+   * note that it is simple to write algorithms that are slow compared to an
+   * optimal solution, since the sparsity of the matrix is not used.
    */
   value_type el (const size_type i,
                  const size_type j) const;
 
   /**
-   * Return the main diagonal element in
-   * the <i>i</i>th row. This function
-   * throws an error if the matrix is not
-   * quadratic and also if the diagonal
-   * blocks of the matrix are not
-   * quadratic.
+   * Return the main diagonal element in the <i>i</i>th row. This function
+   * throws an error if the matrix is not quadratic and also if the diagonal
+   * blocks of the matrix are not quadratic.
    *
-   * This function is considerably
-   * faster than the operator()(),
-   * since for quadratic matrices, the
-   * diagonal entry may be the
-   * first to be stored in each row
-   * and access therefore does not
-   * involve searching for the
-   * right column number.
+   * This function is considerably faster than the operator()(), since for
+   * quadratic matrices, the diagonal entry may be the first to be stored in
+   * each row and access therefore does not involve searching for the right
+   * column number.
    */
   value_type diag_element (const size_type i) const;
 
   /**
-   * Call the compress() function on all
-   * the subblocks of the matrix.
-  *
-  *
-  * See @ref GlossCompress "Compressing
-  * distributed objects" for more
-  * information.
+   * Call the compress() function on all the subblocks of the matrix.
+   *
+   *
+   * See @ref GlossCompress "Compressing distributed objects" for more
+   * information.
    */
   void compress (::dealii::VectorOperation::values operation);
 
@@ -795,72 +630,50 @@ public:
   void compress () DEAL_II_DEPRECATED;
 
   /**
-   * Multiply the entire matrix by a
-   * fixed factor.
+   * Multiply the entire matrix by a fixed factor.
    */
   BlockMatrixBase &operator *= (const value_type factor);
 
   /**
-   * Divide the entire matrix by a
-   * fixed factor.
+   * Divide the entire matrix by a fixed factor.
    */
   BlockMatrixBase &operator /= (const value_type factor);
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add $M*src$ on
-   * $dst$ with $M$ being this
-   * matrix.
+   * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+   * this matrix.
    */
   template <class BlockVectorType>
   void vmult_add (BlockVectorType       &dst,
                   const BlockVectorType &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add
-   * <i>M<sup>T</sup>src</i> to
-   * <i>dst</i> with <i>M</i> being
-   * this matrix. This function
-   * does the same as vmult_add()
-   * but takes the transposed
-   * matrix.
+   * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>src</i> to
+   * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+   * as vmult_add() but takes the transposed matrix.
    */
   template <class BlockVectorType>
   void Tvmult_add (BlockVectorType       &dst,
                    const BlockVectorType &src) const;
 
   /**
-   * Return the norm of the vector
-   * <i>v</i> with respect to the
-   * norm induced by this matrix,
-   * i.e. <i>v<sup>T</sup>Mv)</i>. This
-   * is useful, e.g. in the finite
-   * element context, where the
-   * <i>L<sup>T</sup></i>-norm of a
-   * function equals the matrix
-   * norm with respect to the mass
-   * matrix of the vector
-   * representing the nodal values
-   * of the finite element
-   * function. Note that even
-   * though the function's name
-   * might suggest something
-   * different, for historic
-   * reasons not the norm but its
-   * square is returned, as defined
+   * Return the norm of the vector <i>v</i> with respect to the norm induced
+   * by this matrix, i.e. <i>v<sup>T</sup>Mv)</i>. This is useful, e.g. in the
+   * finite element context, where the <i>L<sup>T</sup></i>-norm of a function
+   * equals the matrix norm with respect to the mass matrix of the vector
+   * representing the nodal values of the finite element function. Note that
+   * even though the function's name might suggest something different, for
+   * historic reasons not the norm but its square is returned, as defined
    * above by the scalar product.
    *
-   * Obviously, the matrix needs to
-   * be square for this operation.
+   * Obviously, the matrix needs to be square for this operation.
    */
   template <class BlockVectorType>
   value_type
   matrix_norm_square (const BlockVectorType &v) const;
 
   /**
-   * Compute the matrix scalar
-   * product $\left(u,Mv\right)$.
+   * Compute the matrix scalar product $\left(u,Mv\right)$.
    */
   template <class BlockVectorType>
   value_type
@@ -868,9 +681,7 @@ public:
                          const BlockVectorType &v) const;
 
   /**
-   * Compute the residual
-   * <i>r=b-Ax</i>. Write the
-   * residual into <tt>dst</tt>.
+   * Compute the residual <i>r=b-Ax</i>. Write the residual into <tt>dst</tt>.
    */
   template <class BlockVectorType>
   value_type residual (BlockVectorType       &dst,
@@ -878,21 +689,16 @@ public:
                        const BlockVectorType &b) const;
 
   /**
-   * Print the matrix to the given
-   * stream, using the format
-   * <tt>(line,col) value</tt>, i.e. one
-   * nonzero entry of the matrix per
-   * line. The optional flag outputs the
-   * sparsity pattern in a different style
-   * according to the underlying
-   * sparsematrix type.
+   * Print the matrix to the given stream, using the format <tt>(line,col)
+   * value</tt>, i.e. one nonzero entry of the matrix per line. The optional
+   * flag outputs the sparsity pattern in a different style according to the
+   * underlying sparsematrix type.
    */
   void print (std::ostream &out,
               const bool    alternative_output = false) const;
 
   /**
-   * STL-like iterator with the
-   * first entry.
+   * STL-like iterator with the first entry.
    */
   iterator begin ();
 
@@ -902,8 +708,7 @@ public:
   iterator end ();
 
   /**
-   * STL-like iterator with the
-   * first entry of row <tt>r</tt>.
+   * STL-like iterator with the first entry of row <tt>r</tt>.
    */
   iterator begin (const size_type r);
 
@@ -912,8 +717,7 @@ public:
    */
   iterator end (const size_type r);
   /**
-   * STL-like iterator with the
-   * first entry.
+   * STL-like iterator with the first entry.
    */
   const_iterator begin () const;
 
@@ -923,8 +727,7 @@ public:
   const_iterator end () const;
 
   /**
-   * STL-like iterator with the
-   * first entry of row <tt>r</tt>.
+   * STL-like iterator with the first entry of row <tt>r</tt>.
    */
   const_iterator begin (const size_type r) const;
 
@@ -934,29 +737,26 @@ public:
   const_iterator end (const size_type r) const;
 
   /**
-   * Return a reference to the underlying
-   * BlockIndices data of the rows.
+   * Return a reference to the underlying BlockIndices data of the rows.
    */
   const BlockIndices &get_row_indices () const;
 
   /**
-   * Return a reference to the underlying
-   * BlockIndices data of the columns.
+   * Return a reference to the underlying BlockIndices data of the columns.
    */
   const BlockIndices &get_column_indices () const;
 
   /**
-   * Determine an estimate for the memory
-   * consumption (in bytes) of this
-   * object. Note that only the memory
-   * reserved on the current processor is
-   * returned in case this is called in
-   * an MPI-based program.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. Note that only the memory reserved on the current processor is
+   * returned in case this is called in an MPI-based program.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -975,22 +775,15 @@ public:
   //@}
 protected:
   /**
-   * Release all memory and return
-   * to a state just like after
-   * having called the default
-   * constructor. It also forgets
-   * the sparsity pattern it was
+   * Release all memory and return to a state just like after having called
+   * the default constructor. It also forgets the sparsity pattern it was
    * previously tied to.
    *
-   * This calls clear for all
-   * sub-matrices and then resets this
-   * object to have no blocks at all.
+   * This calls clear for all sub-matrices and then resets this object to have
+   * no blocks at all.
    *
-   * This function is protected
-   * since it may be necessary to
-   * release additional structures.
-   * A derived class can make it
-   * public again, if it is
+   * This function is protected since it may be necessary to release
+   * additional structures. A derived class can make it public again, if it is
    * sufficient.
    */
   void clear ();
@@ -1007,79 +800,48 @@ protected:
   Table<2,SmartPointer<BlockType, BlockMatrixBase<MatrixType> > > sub_objects;
 
   /**
-   * This function collects the
-   * sizes of the sub-objects and
-   * stores them in internal
-   * arrays, in order to be able to
-   * relay global indices into the
-   * matrix to indices into the
-   * subobjects. You *must* call
-   * this function each time after
-   * you have changed the size of
-   * the sub-objects.
+   * This function collects the sizes of the sub-objects and stores them in
+   * internal arrays, in order to be able to relay global indices into the
+   * matrix to indices into the subobjects. You *must* call this function each
+   * time after you have changed the size of the sub-objects.
    *
-   * Derived classes should call this
-   * function whenever the size of the
-   * sub-objects has changed and the @p
-   * X_block_indices arrays need to be
-   * updated.
+   * Derived classes should call this function whenever the size of the sub-
+   * objects has changed and the @p X_block_indices arrays need to be updated.
    *
-   * Note that this function is not public
-   * since not all derived classes need to
-   * export its interface. For example, for
-   * the usual deal.II SparseMatrix class,
-   * the sizes are implicitly determined
-   * whenever reinit() is called, and
-   * individual blocks cannot be
-   * resized. For that class, this function
-   * therefore does not have to be
-   * public. On the other hand, for the
-   * PETSc classes, there is no associated
-   * sparsity pattern object that
-   * determines the block sizes, and for
-   * these the function needs to be
-   * publicly available. These classes
-   * therefore export this function.
+   * Note that this function is not public since not all derived classes need
+   * to export its interface. For example, for the usual deal.II SparseMatrix
+   * class, the sizes are implicitly determined whenever reinit() is called,
+   * and individual blocks cannot be resized. For that class, this function
+   * therefore does not have to be public. On the other hand, for the PETSc
+   * classes, there is no associated sparsity pattern object that determines
+   * the block sizes, and for these the function needs to be publicly
+   * available. These classes therefore export this function.
    */
   void collect_sizes ();
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M*src$ with $M$
-   * being this matrix.
+   * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+   * matrix.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType>
   void vmult_block_block (BlockVectorType       &dst,
                           const BlockVectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block column.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block column.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType,
             class VectorType>
@@ -1087,22 +849,14 @@ protected:
                              const VectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block row.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block row.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType,
             class VectorType>
@@ -1110,67 +864,43 @@ protected:
                              const BlockVectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class VectorType>
   void vmult_nonblock_nonblock (VectorType       &dst,
                                 const VectorType &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M^T*src$ with $M$
-   * being this matrix. This
-   * function does the same as
-   * vmult() but takes the
-   * transposed matrix.
+   * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+   * matrix. This function does the same as vmult() but takes the transposed
+   * matrix.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType>
   void Tvmult_block_block (BlockVectorType       &dst,
                            const BlockVectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block row.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block row.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType,
             class VectorType>
@@ -1178,22 +908,14 @@ protected:
                               const VectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block column.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block column.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class BlockVectorType,
             class VectorType>
@@ -1201,22 +923,14 @@ protected:
                               const BlockVectorType &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block.
    *
-   * Due to problems with deriving template
-   * arguments between the block and
-   * non-block versions of the vmult/Tvmult
-   * functions, the actual functions are
-   * implemented in derived classes, with
-   * implementations forwarding the calls
-   * to the implementations provided here
-   * under a unique name for which template
-   * arguments can be derived by the
-   * compiler.
+   * Due to problems with deriving template arguments between the block and
+   * non-block versions of the vmult/Tvmult functions, the actual functions
+   * are implemented in derived classes, with implementations forwarding the
+   * calls to the implementations provided here under a unique name for which
+   * template arguments can be derived by the compiler.
    */
   template <class VectorType>
   void Tvmult_nonblock_nonblock (VectorType       &dst,
@@ -1226,20 +940,15 @@ protected:
 protected:
 
   /**
-   * Some matrix types, in particular PETSc,
-   * need to synchronize set and add
-   * operations. This has to be done for all
-   * matrices in the BlockMatrix.
-   * This routine prepares adding of elements
-   * by notifying all blocks. Called by all
-   * internal routines before adding
-   * elements.
+   * Some matrix types, in particular PETSc, need to synchronize set and add
+   * operations. This has to be done for all matrices in the BlockMatrix. This
+   * routine prepares adding of elements by notifying all blocks. Called by
+   * all internal routines before adding elements.
    */
   void prepare_add_operation();
 
   /**
-   * Notifies all blocks to let them prepare
-   * for setting elements, see
+   * Notifies all blocks to let them prepare for setting elements, see
    * prepare_add_operation().
    */
   void prepare_set_operation();
@@ -1248,57 +957,47 @@ protected:
 private:
 
   /**
-   * A structure containing some fields used by the
-   * set() and add() functions that is used to pre-sort
-   * the input fields. Since one can reasonably expect
-   * to call set() and add() from multiple threads at once
-   * as long as the matrix indices that are touched are
-   * disjoint, these temporary data fields need to be
-   * guarded by a mutex; the structure therefore contains such
-   * a mutex as a member variable.
+   * A structure containing some fields used by the set() and add() functions
+   * that is used to pre-sort the input fields. Since one can reasonably
+   * expect to call set() and add() from multiple threads at once as long as
+   * the matrix indices that are touched are disjoint, these temporary data
+   * fields need to be guarded by a mutex; the structure therefore contains
+   * such a mutex as a member variable.
    */
   struct TemporaryData
   {
     /**
-     * Temporary vector for counting the
-     * elements written into the
-     * individual blocks when doing a
-     * collective add or set.
+     * Temporary vector for counting the elements written into the individual
+     * blocks when doing a collective add or set.
      */
     std::vector<size_type> counter_within_block;
 
     /**
-     * Temporary vector for column
-     * indices on each block when writing
-     * local to global data on each
-     * sparse matrix.
+     * Temporary vector for column indices on each block when writing local to
+     * global data on each sparse matrix.
      */
     std::vector<std::vector<size_type> > column_indices;
 
     /**
-     * Temporary vector for storing the
-     * local values (they need to be
-     * reordered when writing local to
-     * global).
+     * Temporary vector for storing the local values (they need to be
+     * reordered when writing local to global).
      */
     std::vector<std::vector<double> > column_values;
 
     /**
-     * A mutex variable used to guard access to the member
-     * variables of this structure;
+     * A mutex variable used to guard access to the member variables of this
+     * structure;
      */
     Threads::Mutex mutex;
 
     /**
-     * Copy operator. This is needed because the default copy
-     * operator of this class is deleted (since Threads::Mutex is
-     * not copyable) and hence the default copy operator of the
-     * enclosing class is also deleted.
+     * Copy operator. This is needed because the default copy operator of this
+     * class is deleted (since Threads::Mutex is not copyable) and hence the
+     * default copy operator of the enclosing class is also deleted.
      *
-     * The implementation here simply does nothing -- TemporaryData
-     * objects are just scratch objects that are resized at the
-     * beginning of their use, so there is no point actually copying
-     * anything.
+     * The implementation here simply does nothing -- TemporaryData objects
+     * are just scratch objects that are resized at the beginning of their
+     * use, so there is no point actually copying anything.
      */
     TemporaryData &operator = (const TemporaryData &)
     {
@@ -1307,18 +1006,16 @@ private:
   };
 
   /**
-   * A set of scratch arrays that can be used by the add()
-   * and set() functions that take pointers to data to
-   * pre-sort indices before use. Access from multiple threads
-   * is synchronized via the mutex variable that is part of the
-   * structure.
+   * A set of scratch arrays that can be used by the add() and set() functions
+   * that take pointers to data to pre-sort indices before use. Access from
+   * multiple threads is synchronized via the mutex variable that is part of
+   * the structure.
    */
   TemporaryData temporary_data;
 
   /**
-   * Make the iterator class a
-   * friend. We have to work around
-   * a compiler bug here again.
+   * Make the iterator class a friend. We have to work around a compiler bug
+   * here again.
    */
   template <typename, bool>
   friend class BlockMatrixIterators::Accessor;
index ca47ae182317fbbfc588cf045d6830714dfdf986..29fdddbc9d9ce8fcffd16f189e553050d3457cfa 100644 (file)
@@ -50,20 +50,17 @@ class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix<number> >
 {
 public:
   /**
-   * Typedef the base class for simpler
-   * access to its own typedefs.
+   * Typedef the base class for simpler access to its own typedefs.
    */
   typedef BlockMatrixBase<SparseMatrix<number> > BaseClass;
 
   /**
-   * Typedef the type of the underlying
-   * matrix.
+   * Typedef the type of the underlying matrix.
    */
   typedef typename BaseClass::BlockType  BlockType;
 
   /**
-   * Import the typedefs from the base
-   * class.
+   * Import the typedefs from the base class.
    */
   typedef typename BaseClass::value_type      value_type;
   typedef typename BaseClass::pointer         pointer;
@@ -79,47 +76,28 @@ public:
    */
 //@{
   /**
-   * Constructor; initializes the
-   * matrix to be empty, without
-   * any structure, i.e.  the
-   * matrix is not usable at
-   * all. This constructor is
-   * therefore only useful for
-   * matrices which are members of
-   * a class. All other matrices
-   * should be created at a point
-   * in the data flow where all
-   * necessary information is
-   * available.
+   * Constructor; initializes the matrix to be empty, without any structure,
+   * i.e.  the matrix is not usable at all. This constructor is therefore only
+   * useful for matrices which are members of a class. All other matrices
+   * should be created at a point in the data flow where all necessary
+   * information is available.
    *
-   * You have to initialize the
-   * matrix before usage with
-   * reinit(BlockSparsityPattern). The
-   * number of blocks per row and
-   * column are then determined by
-   * that function.
+   * You have to initialize the matrix before usage with
+   * reinit(BlockSparsityPattern). The number of blocks per row and column are
+   * then determined by that function.
    */
   BlockSparseMatrix ();
 
   /**
-   * Constructor. Takes the given
-   * matrix sparsity structure to
-   * represent the sparsity pattern
-   * of this matrix. You can change
-   * the sparsity pattern later on
-   * by calling the reinit()
-   * function.
+   * Constructor. Takes the given matrix sparsity structure to represent the
+   * sparsity pattern of this matrix. You can change the sparsity pattern
+   * later on by calling the reinit() function.
    *
-   * This constructor initializes
-   * all sub-matrices with the
-   * sub-sparsity pattern within
-   * the argument.
+   * This constructor initializes all sub-matrices with the sub-sparsity
+   * pattern within the argument.
    *
-   * You have to make sure that the
-   * lifetime of the sparsity
-   * structure is at least as long
-   * as that of this matrix or as
-   * long as reinit() is not called
+   * You have to make sure that the lifetime of the sparsity structure is at
+   * least as long as that of this matrix or as long as reinit() is not called
    * with a new sparsity structure.
    */
   BlockSparseMatrix (const BlockSparsityPattern &sparsity);
@@ -132,58 +110,40 @@ public:
 
 
   /**
-   * Pseudo copy operator only copying
-   * empty objects. The sizes of the block
+   * Pseudo copy operator only copying empty objects. The sizes of the block
    * matrices need to be the same.
    */
   BlockSparseMatrix &
   operator = (const BlockSparseMatrix &);
 
   /**
-   * This operator assigns a scalar to a
-   * matrix. Since this does usually not
-   * make much sense (should we set all
-   * matrix entries to this value? Only
-   * the nonzero entries of the sparsity
-   * pattern?), this operation is only
-   * allowed if the actual value to be
-   * assigned is zero. This operator only
-   * exists to allow for the obvious
-   * notation <tt>matrix=0</tt>, which
-   * sets all elements of the matrix to
-   * zero, but keep the sparsity pattern
-   * previously used.
+   * This operator assigns a scalar to a matrix. Since this does usually not
+   * make much sense (should we set all matrix entries to this value? Only the
+   * nonzero entries of the sparsity pattern?), this operation is only allowed
+   * if the actual value to be assigned is zero. This operator only exists to
+   * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+   * of the matrix to zero, but keep the sparsity pattern previously used.
    */
   BlockSparseMatrix &
   operator = (const double d);
 
   /**
-   * Release all memory and return
-   * to a state just like after
-   * having called the default
-   * constructor. It also forgets
-   * the sparsity pattern it was
+   * Release all memory and return to a state just like after having called
+   * the default constructor. It also forgets the sparsity pattern it was
    * previously tied to.
    *
-   * This calls SparseMatrix::clear on all
-   * sub-matrices and then resets this
+   * This calls SparseMatrix::clear on all sub-matrices and then resets this
    * object to have no blocks at all.
    */
   void clear ();
 
   /**
-   * Reinitialize the sparse matrix
-   * with the given sparsity
-   * pattern. The latter tells the
-   * matrix how many nonzero
-   * elements there need to be
+   * Reinitialize the sparse matrix with the given sparsity pattern. The
+   * latter tells the matrix how many nonzero elements there need to be
    * reserved.
    *
-   * Basically, this function only
-   * calls SparseMatrix::reinit() of the
-   * sub-matrices with the block
-   * sparsity patterns of the
-   * parameter.
+   * Basically, this function only calls SparseMatrix::reinit() of the sub-
+   * matrices with the block sparsity patterns of the parameter.
    *
    * You have to make sure that the lifetime of the sparsity structure is at
    * least as long as that of this matrix or as long as reinit(const
@@ -199,59 +159,44 @@ public:
    */
 //@{
   /**
-   * Return whether the object is
-   * empty. It is empty if either
-   * both dimensions are zero or no
-   * BlockSparsityPattern is
-   * associated.
+   * Return whether the object is empty. It is empty if either both dimensions
+   * are zero or no BlockSparsityPattern is associated.
    */
   bool empty () const;
 
   /**
-   * Return the number of entries
-   * in a specific row.
+   * Return the number of entries in a specific row.
    */
   size_type get_row_length (const size_type row) const;
 
   /**
-   * Return the number of nonzero
-   * elements of this
-   * matrix. Actually, it returns
-   * the number of entries in the
-   * sparsity pattern; if any of
-   * the entries should happen to
-   * be zero, it is counted anyway.
+   * Return the number of nonzero elements of this matrix. Actually, it
+   * returns the number of entries in the sparsity pattern; if any of the
+   * entries should happen to be zero, it is counted anyway.
    */
   size_type n_nonzero_elements () const;
 
   /**
-   * Return the number of actually
-   * nonzero elements. Just counts the
-   * number of actually nonzero elements
-   * (with absolute value larger than
-   * threshold) of all the blocks.
+   * Return the number of actually nonzero elements. Just counts the number of
+   * actually nonzero elements (with absolute value larger than threshold) of
+   * all the blocks.
    */
   size_type n_actually_nonzero_elements (const double threshold = 0.0) const;
 
   /**
-   * Return a (constant) reference
-   * to the underlying sparsity
-   * pattern of this matrix.
+   * Return a (constant) reference to the underlying sparsity pattern of this
+   * matrix.
    *
-   * Though the return value is
-   * declared <tt>const</tt>, you
-   * should be aware that it may
-   * change if you call any
-   * nonconstant function of
-   * objects which operate on it.
+   * Though the return value is declared <tt>const</tt>, you should be aware
+   * that it may change if you call any nonconstant function of objects which
+   * operate on it.
    */
   const BlockSparsityPattern &
   get_sparsity_pattern () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 //@}
@@ -261,20 +206,16 @@ public:
    */
 //@{
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M*src$ with $M$
-   * being this matrix.
+   * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+   * matrix.
    */
   template <typename block_number>
   void vmult (BlockVector<block_number>       &dst,
               const BlockVector<block_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block column.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block column.
    */
   template <typename block_number,
             typename nonblock_number>
@@ -282,11 +223,8 @@ public:
               const Vector<nonblock_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block row.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block row.
    */
   template <typename block_number,
             typename nonblock_number>
@@ -294,34 +232,25 @@ public:
               const BlockVector<block_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block.
    */
   template <typename nonblock_number>
   void vmult (Vector<nonblock_number>       &dst,
               const Vector<nonblock_number> &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M^T*src$ with $M$
-   * being this matrix. This
-   * function does the same as
-   * vmult() but takes the
-   * transposed matrix.
+   * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+   * matrix. This function does the same as vmult() but takes the transposed
+   * matrix.
    */
   template <typename block_number>
   void Tvmult (BlockVector<block_number>       &dst,
                const BlockVector<block_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block row.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block row.
    */
   template <typename block_number,
             typename nonblock_number>
@@ -329,11 +258,8 @@ public:
                const Vector<nonblock_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block column.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block column.
    */
   template <typename block_number,
             typename nonblock_number>
@@ -341,11 +267,8 @@ public:
                const BlockVector<block_number> &src) const;
 
   /**
-   * Matrix-vector
-   * multiplication. Just like the
-   * previous function, but only
-   * applicable if the matrix has
-   * only one block.
+   * Matrix-vector multiplication. Just like the previous function, but only
+   * applicable if the matrix has only one block.
    */
   template <typename nonblock_number>
   void Tvmult (Vector<nonblock_number>       &dst,
@@ -357,19 +280,11 @@ public:
    */
 //@{
   /**
-   * Apply the Jacobi
-   * preconditioner, which
-   * multiplies every element of
-   * the <tt>src</tt> vector by the
-   * inverse of the respective
-   * diagonal element and
-   * multiplies the result with the
-   * relaxation parameter
-   * <tt>omega</tt>.
+   * Apply the Jacobi preconditioner, which multiplies every element of the
+   * <tt>src</tt> vector by the inverse of the respective diagonal element and
+   * multiplies the result with the relaxation parameter <tt>omega</tt>.
    *
-   * All diagonal blocks must be
-   * square matrices for this
-   * operation.
+   * All diagonal blocks must be square matrices for this operation.
    */
   template <class BlockVectorType>
   void precondition_Jacobi (BlockVectorType       &dst,
@@ -377,11 +292,9 @@ public:
                             const number           omega = 1.) const;
 
   /**
-   * Apply the Jacobi
-   * preconditioner to a simple vector.
+   * Apply the Jacobi preconditioner to a simple vector.
    *
-   * The matrix must be a single
-   * square block for this.
+   * The matrix must be a single square block for this.
    */
   template <typename number2>
   void precondition_Jacobi (Vector<number2>       &dst,
@@ -394,45 +307,24 @@ public:
    */
 //@{
   /**
-   * Print the matrix in the usual
-   * format, i.e. as a matrix and
-   * not as a list of nonzero
-   * elements. For better
-   * readability, elements not in
-   * the matrix are displayed as
-   * empty space, while matrix
-   * elements which are explicitly
-   * set to zero are displayed as
-   * such.
+   * Print the matrix in the usual format, i.e. as a matrix and not as a list
+   * of nonzero elements. For better readability, elements not in the matrix
+   * are displayed as empty space, while matrix elements which are explicitly
+   * set to zero are displayed as such.
    *
-   * The parameters allow for a
-   * flexible setting of the output
-   * format: <tt>precision</tt> and
-   * <tt>scientific</tt> are used
-   * to determine the number
-   * format, where <tt>scientific =
-   * false</tt> means fixed point
-   * notation.  A zero entry for
-   * <tt>width</tt> makes the
-   * function compute a width, but
-   * it may be changed to a
-   * positive value, if output is
-   * crude.
+   * The parameters allow for a flexible setting of the output format:
+   * <tt>precision</tt> and <tt>scientific</tt> are used to determine the
+   * number format, where <tt>scientific = false</tt> means fixed point
+   * notation.  A zero entry for <tt>width</tt> makes the function compute a
+   * width, but it may be changed to a positive value, if output is crude.
    *
-   * Additionally, a character for
-   * an empty value may be
-   * specified.
+   * Additionally, a character for an empty value may be specified.
    *
-   * Finally, the whole matrix can
-   * be multiplied with a common
-   * denominator to produce more
-   * readable output, even
-   * integers.
+   * Finally, the whole matrix can be multiplied with a common denominator to
+   * produce more readable output, even integers.
    *
-   * @attention This function may
-   * produce <b>large</b> amounts
-   * of output if applied to a
-   * large matrix!
+   * @attention This function may produce <b>large</b> amounts of output if
+   * applied to a large matrix!
    */
   void print_formatted (std::ostream       &out,
                         const unsigned int  precision   = 3,
@@ -441,8 +333,10 @@ public:
                         const char         *zero_string = " ",
                         const double        denominator = 1.) const;
 //@}
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -452,13 +346,9 @@ public:
 
 private:
   /**
-   * Pointer to the block sparsity
-   * pattern used for this
-   * matrix. In order to guarantee
-   * that it is not deleted while
-   * still in use, we subscribe to
-   * it using the SmartPointer
-   * class.
+   * Pointer to the block sparsity pattern used for this matrix. In order to
+   * guarantee that it is not deleted while still in use, we subscribe to it
+   * using the SmartPointer class.
    */
   SmartPointer<const BlockSparsityPattern,BlockSparseMatrix<number> > sparsity_pattern;
 };
index 2f1aacf066697b970e98174e188a207d8c895ad5..afb566bad7731899ad45fc401b344f5a51c19ec5 100644 (file)
@@ -40,9 +40,9 @@ template <typename Number> class BlockVector;
  * A block matrix consisting of blocks of type SparseMatrixEZ.
  *
  * Like the other Block-objects, this matrix can be used like a
- * SparseMatrixEZ, when it comes to access to entries. Then, there
- * are functions for the multiplication with BlockVector and
- * access to the individual blocks.
+ * SparseMatrixEZ, when it comes to access to entries. Then, there are
+ * functions for the multiplication with BlockVector and access to the
+ * individual blocks.
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Guido Kanschat, 2002, 2003
@@ -57,100 +57,65 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Default constructor. The
-   * result is an empty object with
-   * zero dimensions.
+   * Default constructor. The result is an empty object with zero dimensions.
    */
   BlockSparseMatrixEZ ();
 
   /**
-   * Constructor setting up an
-   * object with given unmber of
-   * block rows and columns. The
-   * blocks themselves still have
-   * zero dimension.
+   * Constructor setting up an object with given unmber of block rows and
+   * columns. The blocks themselves still have zero dimension.
    */
   BlockSparseMatrixEZ (const unsigned int block_rows,
                        const unsigned int block_cols);
 
   /**
-   * Copy constructor. This is
-   * needed for some container
-   * classes. It creates an object
-   * of the same number of block
-   * rows and columns. Since it
-   * calls the copy constructor of
-   * SparseMatrixEZ, the
-   * block s must be empty.
+   * Copy constructor. This is needed for some container classes. It creates
+   * an object of the same number of block rows and columns. Since it calls
+   * the copy constructor of SparseMatrixEZ, the block s must be empty.
    */
   BlockSparseMatrixEZ (const BlockSparseMatrixEZ<Number> &);
 
   /**
-   * Copy operator. Like the copy
-   * constructor, this may be
-   * called for objects with empty
-   * blocks only.
+   * Copy operator. Like the copy constructor, this may be called for objects
+   * with empty blocks only.
    */
   BlockSparseMatrixEZ &operator = (const BlockSparseMatrixEZ<Number> &);
 
   /**
-   * This operator assigns a scalar to
-   * a matrix. Since this does usually
-   * not make much sense (should we set
-   * all matrix entries to this value?
-   * Only the nonzero entries of the
-   * sparsity pattern?), this operation
-   * is only allowed if the actual
-   * value to be assigned is zero. This
-   * operator only exists to allow for
-   * the obvious notation
-   * <tt>matrix=0</tt>, which sets all
-   * elements of the matrix to zero,
-   * but keep the sparsity pattern
-   * previously used.
+   * This operator assigns a scalar to a matrix. Since this does usually not
+   * make much sense (should we set all matrix entries to this value? Only the
+   * nonzero entries of the sparsity pattern?), this operation is only allowed
+   * if the actual value to be assigned is zero. This operator only exists to
+   * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+   * of the matrix to zero, but keep the sparsity pattern previously used.
    */
   BlockSparseMatrixEZ &operator = (const double d);
 
 
   /**
-   * Set matrix to zero dimensions
-   * and release memory.
+   * Set matrix to zero dimensions and release memory.
    */
   void clear ();
 
   /**
-   * Initialize to given block
-   * numbers.  After this
-   * operation, the matrix will
-   * have the block dimensions
-   * provided. Each block will have
-   * zero dimensions and must be
-   * initialized
-   * subsequently. After setting
-   * the sizes of the blocks,
-   * collect_sizes() must be
-   * called to update internal data
+   * Initialize to given block numbers.  After this operation, the matrix will
+   * have the block dimensions provided. Each block will have zero dimensions
+   * and must be initialized subsequently. After setting the sizes of the
+   * blocks, collect_sizes() must be called to update internal data
    * structures.
    */
   void reinit (const unsigned int n_block_rows,
                const unsigned int n_block_cols);
   /**
-   * This function collects the
-   * sizes of the sub-objects and
-   * stores them in internal
-   * arrays, in order to be able to
-   * relay global indices into the
-   * matrix to indices into the
-   * subobjects. You *must* call
-   * this function each time after
-   * you have changed the size of
-   * the sub-objects.
+   * This function collects the sizes of the sub-objects and stores them in
+   * internal arrays, in order to be able to relay global indices into the
+   * matrix to indices into the subobjects. You *must* call this function each
+   * time after you have changed the size of the sub-objects.
    */
   void collect_sizes ();
 
   /**
-   * Access the block with the
-   * given coordinates.
+   * Access the block with the given coordinates.
    */
   SparseMatrixEZ<Number> &
   block (const unsigned int row,
@@ -158,137 +123,101 @@ public:
 
 
   /**
-   * Access the block with the
-   * given coordinates. Version for
-   * constant objects.
+   * Access the block with the given coordinates. Version for constant
+   * objects.
    */
   const SparseMatrixEZ<Number> &
   block (const unsigned int row,
          const unsigned int column) const;
 
   /**
-   * Return the number of blocks in a
-   * column.
+   * Return the number of blocks in a column.
    */
   unsigned int n_block_rows () const;
 
   /**
-   * Return the number of blocks in a
-   * row.
+   * Return the number of blocks in a row.
    */
   unsigned int n_block_cols () const;
 
   /**
-   * Return whether the object is
-   * empty. It is empty if no
-   * memory is allocated, which is
-   * the same as that both
-   * dimensions are zero. This
-   * function is just the
-   * concatenation of the
-   * respective call to all
-   * sub-matrices.
+   * Return whether the object is empty. It is empty if no memory is
+   * allocated, which is the same as that both dimensions are zero. This
+   * function is just the concatenation of the respective call to all sub-
+   * matrices.
    */
   bool empty () const;
 
   /**
-   * Return number of rows of this
-   * matrix, which equals the
-   * dimension of the image
-   * space. It is the sum of rows
-   * of the rows of sub-matrices.
+   * Return number of rows of this matrix, which equals the dimension of the
+   * image space. It is the sum of rows of the rows of sub-matrices.
    */
   size_type n_rows () const;
 
   /**
-   * Return number of columns of
-   * this matrix, which equals the
-   * dimension of the range
-   * space. It is the sum of
-   * columns of the columns of
-   * sub-matrices.
+   * Return number of columns of this matrix, which equals the dimension of
+   * the range space. It is the sum of columns of the columns of sub-matrices.
    */
   size_type n_cols () const;
 
   /**
-   * Return the dimension of the
-   * image space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the image space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type m () const;
 
   /**
-   * Return the dimension of the
-   * range space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the range space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type n () const;
 
   /**
-   * Set the element <tt>(i,j)</tt>
-   * to @p value.  Throws an error
-   * if the entry does not exist or
-   * if <tt>value</tt> is not a
-   * finite number. Still, it is
-   * allowed to store zero values
-   * in non-existent fields.
+   * Set the element <tt>(i,j)</tt> to @p value.  Throws an error if the entry
+   * does not exist or if <tt>value</tt> is not a finite number. Still, it is
+   * allowed to store zero values in non-existent fields.
    */
   void set (const size_type i,
             const size_type j,
             const Number value);
 
   /**
-   * Add @p value to the element
-   * <tt>(i,j)</tt>.  Throws an
-   * error if the entry does not
-   * exist or if <tt>value</tt> is
-   * not a finite number. Still, it
-   * is allowed to store zero
-   * values in non-existent fields.
+   * Add @p value to the element <tt>(i,j)</tt>.  Throws an error if the entry
+   * does not exist or if <tt>value</tt> is not a finite number. Still, it is
+   * allowed to store zero values in non-existent fields.
    */
   void add (const size_type i, const size_type j,
             const Number value);
 
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M*src$ with $M$
-   * being this matrix.
+   * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+   * matrix.
    */
   template <typename somenumber>
   void vmult (BlockVector<somenumber>       &dst,
               const BlockVector<somenumber> &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M^T*src$ with $M$
-   * being this matrix. This
-   * function does the same as
-   * vmult() but takes the
-   * transposed matrix.
+   * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+   * matrix. This function does the same as vmult() but takes the transposed
+   * matrix.
    */
   template <typename somenumber>
   void Tvmult (BlockVector<somenumber>       &dst,
                const BlockVector<somenumber> &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add $M*src$ on
-   * $dst$ with $M$ being this
-   * matrix.
+   * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+   * this matrix.
    */
   template <typename somenumber>
   void vmult_add (BlockVector<somenumber>       &dst,
                   const BlockVector<somenumber> &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add $M^T*src$
-   * to $dst$ with $M$ being this
-   * matrix. This function does the
-   * same as vmult_add() but takes
+   * Adding Matrix-vector multiplication. Add $M^T*src$ to $dst$ with $M$
+   * being this matrix. This function does the same as vmult_add() but takes
    * the transposed matrix.
    */
   template <typename somenumber>
@@ -297,31 +226,23 @@ public:
 
 
   /**
-   * Print statistics. If @p full
-   * is @p true, prints a
-   * histogram of all existing row
-   * lengths and allocated row
-   * lengths. Otherwise, just the
-   * relation of allocated and used
-   * entries is shown.
+   * Print statistics. If @p full is @p true, prints a histogram of all
+   * existing row lengths and allocated row lengths. Otherwise, just the
+   * relation of allocated and used entries is shown.
    */
   template <class STREAM>
   void print_statistics (STREAM &s, bool full = false);
 
 private:
   /**
-   * Object storing and managing
-   * the transformation of row
-   * indices to indices of the
-   * sub-objects.
+   * Object storing and managing the transformation of row indices to indices
+   * of the sub-objects.
    */
   BlockIndices    row_indices;
 
   /**
-   * Object storing and managing
-   * the transformation of column
-   * indices to indices of the
-   * sub-objects.
+   * Object storing and managing the transformation of column indices to
+   * indices of the sub-objects.
    */
   BlockIndices    column_indices;
 
index f3a95f4c99cd4eaba6e44ff5ecad71da4af58f4e..1953611503670d13fa6e82bc854ca2c15f4c01e4 100644 (file)
@@ -59,22 +59,20 @@ namespace TrilinosWrappers
  * member functions of the member sparsity patterns.
  *
  * The largest difference between the SparsityPattern and
- * CompressedSparsityPattern classes and this class is that
- * mostly, the matrices have different properties and you will want to
- * work on the blocks making up the matrix rather than the whole
- * matrix. You can access the different blocks using the
- * <tt>block(row,col)</tt> function.
+ * CompressedSparsityPattern classes and this class is that mostly, the
+ * matrices have different properties and you will want to work on the blocks
+ * making up the matrix rather than the whole matrix. You can access the
+ * different blocks using the <tt>block(row,col)</tt> function.
  *
- * Attention: this object is not automatically notified if the size of
- * one of its subobjects' size is changed. After you initialize the
- * sizes of the subobjects, you will therefore have to call the
- * <tt>collect_sizes()</tt> function of this class! Note that, of course, all
- * sub-matrices in a (block-)row have to have the same number of rows, and
- * that all sub-matrices in a (block-)column have to have the same number of
- * columns.
+ * Attention: this object is not automatically notified if the size of one of
+ * its subobjects' size is changed. After you initialize the sizes of the
+ * subobjects, you will therefore have to call the <tt>collect_sizes()</tt>
+ * function of this class! Note that, of course, all sub-matrices in a
+ * (block-)row have to have the same number of rows, and that all sub-matrices
+ * in a (block-)column have to have the same number of columns.
  *
- * You will in general not want to use this class, but one of the
- * derived classes.
+ * You will in general not want to use this class, but one of the derived
+ * classes.
  *
  * @todo Handle optimization of diagonal elements of the underlying
  * SparsityPattern correctly.
@@ -92,52 +90,35 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Define a value which is used
-   * to indicate that a certain
-   * value in the @p colnums array
-   * is unused, i.e. does not
-   * represent a certain column
-   * number index.
+   * Define a value which is used to indicate that a certain value in the @p
+   * colnums array is unused, i.e. does not represent a certain column number
+   * index.
    *
-   * This value is only an alias to
-   * the respective value of the
+   * This value is only an alias to the respective value of the
    * SparsityPattern class.
    */
   static const size_type invalid_entry = SparsityPattern::invalid_entry;
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   BlockSparsityPatternBase ();
 
   /**
-   * Initialize the matrix with the
-   * given number of block rows and
-   * columns. The blocks themselves
-   * are still empty, and you have
-   * to call collect_sizes() after
-   * you assign them sizes.
+   * Initialize the matrix with the given number of block rows and columns.
+   * The blocks themselves are still empty, and you have to call
+   * collect_sizes() after you assign them sizes.
    */
   BlockSparsityPatternBase (const size_type n_block_rows,
                             const size_type n_block_columns);
 
   /**
-   * Copy constructor. This
-   * constructor is only allowed to
-   * be called if the sparsity pattern to be
-   * copied is empty, i.e. there
-   * are no block allocated at
-   * present. This is for the same
-   * reason as for the
-   * SparsityPattern, see there
-   * for the details.
+   * Copy constructor. This constructor is only allowed to be called if the
+   * sparsity pattern to be copied is empty, i.e. there are no block allocated
+   * at present. This is for the same reason as for the SparsityPattern, see
+   * there for the details.
    */
   BlockSparsityPatternBase (const BlockSparsityPatternBase &bsp);
 
@@ -147,61 +128,38 @@ public:
   ~BlockSparsityPatternBase ();
 
   /**
-   * Resize the matrix, by setting
-   * the number of block rows and
-   * columns. This deletes all
-   * blocks and replaces them by
-   * unitialized ones, i.e. ones
-   * for which also the sizes are
-   * not yet set. You have to do
-   * that by calling the reinit()
-   * functions of the blocks
-   * themselves. Do not forget to
-   * call collect_sizes() after
-   * that on this object.
+   * Resize the matrix, by setting the number of block rows and columns. This
+   * deletes all blocks and replaces them by unitialized ones, i.e. ones for
+   * which also the sizes are not yet set. You have to do that by calling the
+   * reinit() functions of the blocks themselves. Do not forget to call
+   * collect_sizes() after that on this object.
    *
-   * The reason that you have to
-   * set sizes of the blocks
-   * yourself is that the sizes may
-   * be varying, the maximum number
-   * of elements per row may be
-   * varying, etc. It is simpler
-   * not to reproduce the interface
-   * of the SparsityPattern
-   * class here but rather let the
-   * user call whatever function
+   * The reason that you have to set sizes of the blocks yourself is that the
+   * sizes may be varying, the maximum number of elements per row may be
+   * varying, etc. It is simpler not to reproduce the interface of the
+   * SparsityPattern class here but rather let the user call whatever function
    * she desires.
    */
   void reinit (const size_type n_block_rows,
                const size_type n_block_columns);
 
   /**
-   * Copy operator. For this the
-   * same holds as for the copy
-   * constructor: it is declared,
-   * defined and fine to be called,
-   * but the latter only for empty
+   * Copy operator. For this the same holds as for the copy constructor: it is
+   * declared, defined and fine to be called, but the latter only for empty
    * objects.
    */
   BlockSparsityPatternBase &operator = (const BlockSparsityPatternBase &);
 
   /**
-   * This function collects the
-   * sizes of the sub-objects and
-   * stores them in internal
-   * arrays, in order to be able to
-   * relay global indices into the
-   * matrix to indices into the
-   * subobjects. You *must* call
-   * this function each time after
-   * you have changed the size of
-   * the sub-objects.
+   * This function collects the sizes of the sub-objects and stores them in
+   * internal arrays, in order to be able to relay global indices into the
+   * matrix to indices into the subobjects. You *must* call this function each
+   * time after you have changed the size of the sub-objects.
    */
   void collect_sizes ();
 
   /**
-   * Access the block with the
-   * given coordinates.
+   * Access the block with the given coordinates.
    */
   SparsityPatternBase &
   block (const size_type row,
@@ -209,103 +167,77 @@ public:
 
 
   /**
-   * Access the block with the
-   * given coordinates. Version for
-   * constant objects.
+   * Access the block with the given coordinates. Version for constant
+   * objects.
    */
   const SparsityPatternBase &
   block (const size_type row,
          const size_type column) const;
 
   /**
-   * Grant access to the object
-   * describing the distribution of
-   * row indices to the individual
-   * blocks.
+   * Grant access to the object describing the distribution of row indices to
+   * the individual blocks.
    */
   const BlockIndices &
   get_row_indices () const;
 
   /**
-   * Grant access to the object
-   * describing the distribution of
-   * column indices to the individual
-   * blocks.
+   * Grant access to the object describing the distribution of column indices
+   * to the individual blocks.
    */
   const BlockIndices &
   get_column_indices () const;
 
   /**
-   * This function compresses the
-   * sparsity structures that this
-   * object represents. It simply
-   * calls @p compress for all
-   * sub-objects.
+   * This function compresses the sparsity structures that this object
+   * represents. It simply calls @p compress for all sub-objects.
    */
   void compress ();
 
   /**
-   * Return the number of blocks in a
-   * column.
+   * Return the number of blocks in a column.
    */
   size_type n_block_rows () const;
 
   /**
-   * Return the number of blocks in a
-   * row.
+   * Return the number of blocks in a row.
    */
   size_type n_block_cols () const;
 
   /**
-   * Return whether the object is
-   * empty. It is empty if no
-   * memory is allocated, which is
-   * the same as that both
-   * dimensions are zero. This
-   * function is just the
-   * concatenation of the
-   * respective call to all
-   * sub-matrices.
+   * Return whether the object is empty. It is empty if no memory is
+   * allocated, which is the same as that both dimensions are zero. This
+   * function is just the concatenation of the respective call to all sub-
+   * matrices.
    */
   bool empty () const;
 
   /**
-   * Return the maximum number of
-   * entries per row. It returns
-   * the maximal number of entries
-   * per row accumulated over all
-   * blocks in a row, and the
+   * Return the maximum number of entries per row. It returns the maximal
+   * number of entries per row accumulated over all blocks in a row, and the
    * maximum over all rows.
    */
   size_type max_entries_per_row () const;
 
   /**
-   * Add a nonzero entry to the matrix.
-   * This function may only be called
-   * for non-compressed sparsity patterns.
+   * Add a nonzero entry to the matrix. This function may only be called for
+   * non-compressed sparsity patterns.
    *
-   * If the entry already exists, nothing
-   * bad happens.
+   * If the entry already exists, nothing bad happens.
    *
-   * This function simply finds out
-   * to which block <tt>(i,j)</tt> belongs
-   * and then relays to that block.
+   * This function simply finds out to which block <tt>(i,j)</tt> belongs and
+   * then relays to that block.
    */
   void add (const size_type i, const size_type j);
 
   /**
-   * Add several nonzero entries to the
-   * specified matrix row.  This function
-   * may only be called for
-   * non-compressed sparsity patterns.
+   * Add several nonzero entries to the specified matrix row.  This function
+   * may only be called for non-compressed sparsity patterns.
    *
-   * If some of the entries already
-   * exist, nothing bad happens.
+   * If some of the entries already exist, nothing bad happens.
    *
-   * This function simply finds out to
-   * which blocks <tt>(row,col)</tt> for
-   * <tt>col</tt> in the iterator range
-   * belong and then relays to those
+   * This function simply finds out to which blocks <tt>(row,col)</tt> for
+   * <tt>col</tt> in the iterator range belong and then relays to those
    * blocks.
    */
   template <typename ForwardIterator>
@@ -315,84 +247,61 @@ public:
                     const bool       indices_are_sorted = false);
 
   /**
-   * Return number of rows of this
-   * matrix, which equals the
-   * dimension of the image
-   * space. It is the sum of rows
-   * of the (block-)rows of
-   * sub-matrices.
+   * Return number of rows of this matrix, which equals the dimension of the
+   * image space. It is the sum of rows of the (block-)rows of sub-matrices.
    */
   size_type n_rows () const;
 
   /**
-   * Return number of columns of
-   * this matrix, which equals the
-   * dimension of the range
-   * space. It is the sum of
-   * columns of the (block-)columns
-   * of sub-matrices.
+   * Return number of columns of this matrix, which equals the dimension of
+   * the range space. It is the sum of columns of the (block-)columns of sub-
+   * matrices.
    */
   size_type n_cols () const;
 
   /**
-   * Check if a value at a certain
-   * position may be non-zero.
+   * Check if a value at a certain position may be non-zero.
    */
   bool exists (const size_type i, const size_type j) const;
 
   /**
-   * Number of entries in a
-   * specific row, added up over
-   * all the blocks that form this
-   * row.
+   * Number of entries in a specific row, added up over all the blocks that
+   * form this row.
    */
   unsigned int row_length (const size_type row) const;
 
   /**
-   * Return the number of nonzero
-   * elements of this
-   * matrix. Actually, it returns
-   * the number of entries in the
-   * sparsity pattern; if any of
-   * the entries should happen to
-   * be zero, it is counted anyway.
+   * Return the number of nonzero elements of this matrix. Actually, it
+   * returns the number of entries in the sparsity pattern; if any of the
+   * entries should happen to be zero, it is counted anyway.
    *
-   * This function may only be
-   * called if the matrix struct is
-   * compressed. It does not make
-   * too much sense otherwise
-   * anyway.
+   * This function may only be called if the matrix struct is compressed. It
+   * does not make too much sense otherwise anyway.
    *
-   * In the present context, it is
-   * the sum of the values as
-   * returned by the sub-objects.
+   * In the present context, it is the sum of the values as returned by the
+   * sub-objects.
    */
   size_type n_nonzero_elements () const;
 
   /**
-   * Print the sparsity of the
-   * matrix. The output consists of
-   * one line per row of the format
-   * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
-   * is the row number and
-   * <i>jn</i> are the allocated
-   * columns in this row.
+   * Print the sparsity of the matrix. The output consists of one line per row
+   * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+   * <i>jn</i> are the allocated columns in this row.
    */
   void print (std::ostream &out) const;
 
   /**
-   * Print the sparsity of the matrix
-   * in a format that <tt>gnuplot</tt> understands
-   * and which can be used to plot the
-   * sparsity pattern in a graphical
-   * way. This is the same functionality
-   * implemented for usual sparsity
-   * patterns, see @ref SparsityPattern.
+   * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
+   * understands and which can be used to plot the sparsity pattern in a
+   * graphical way. This is the same functionality implemented for usual
+   * sparsity patterns, see @ref SparsityPattern.
    */
   void print_gnuplot (std::ostream &out) const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -432,43 +341,33 @@ protected:
   Table<2,SmartPointer<SparsityPatternBase, BlockSparsityPatternBase<SparsityPatternBase> > > sub_objects;
 
   /**
-   * Object storing and managing
-   * the transformation of row
-   * indices to indices of the
-   * sub-objects.
+   * Object storing and managing the transformation of row indices to indices
+   * of the sub-objects.
    */
   BlockIndices    row_indices;
 
   /**
-   * Object storing and managing
-   * the transformation of column
-   * indices to indices of the
-   * sub-objects.
+   * Object storing and managing the transformation of column indices to
+   * indices of the sub-objects.
    */
   BlockIndices    column_indices;
 
 private:
   /**
-   * Temporary vector for counting the
-   * elements written into the
-   * individual blocks when doing a
-   * collective add or set.
+   * Temporary vector for counting the elements written into the individual
+   * blocks when doing a collective add or set.
    */
   std::vector<size_type > counter_within_block;
 
   /**
-   * Temporary vector for column
-   * indices on each block when writing
-   * local to global data on each
-   * sparse matrix.
+   * Temporary vector for column indices on each block when writing local to
+   * global data on each sparse matrix.
    */
   std::vector<std::vector<size_type > > block_column_indices;
 
   /**
-   * Make the block sparse matrix a
-   * friend, so that it can use our
-   * #row_indices and
-   * #column_indices objects.
+   * Make the block sparse matrix a friend, so that it can use our
+   * #row_indices and #column_indices objects.
    */
   template <typename number>
   friend class BlockSparseMatrix;
@@ -478,9 +377,9 @@ private:
 
 /**
  * This class extends the base class to implement an array of sparsity
- * patterns that can be used by block sparse matrix objects. It only
- * adds a few additional member functions, but the main interface
- * stems from the base class, see there for more information.
+ * patterns that can be used by block sparse matrix objects. It only adds a
+ * few additional member functions, but the main interface stems from the base
+ * class, see there for more information.
  *
  * This class is an example of the "static" type of @ref Sparsity.
  *
@@ -491,56 +390,37 @@ class BlockSparsityPattern : public BlockSparsityPatternBase<SparsityPattern>
 public:
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   BlockSparsityPattern ();
 
   /**
-   * Initialize the matrix with the
-   * given number of block rows and
-   * columns. The blocks themselves
-   * are still empty, and you have
-   * to call collect_sizes() after
-   * you assign them sizes.
+   * Initialize the matrix with the given number of block rows and columns.
+   * The blocks themselves are still empty, and you have to call
+   * collect_sizes() after you assign them sizes.
    */
   BlockSparsityPattern (const size_type n_rows,
                         const size_type n_columns);
 
   /**
-   * Forwarding to
-   * BlockSparsityPatternBase::reinit().
+   * Forwarding to BlockSparsityPatternBase::reinit().
    */
   void reinit (const size_type n_block_rows,
                const size_type n_block_columns);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns as well as a row
-   * length vector.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns as well as a row length vector.
    *
-   * The row length vector should
-   * be in the format produced by
-   * DoFTools. Alternatively, there
-   * is a simplified version,
-   * where each of the inner
-   * vectors has length one. Then,
-   * the corresponding entry is
-   * used as the maximal row length.
+   * The row length vector should be in the format produced by DoFTools.
+   * Alternatively, there is a simplified version, where each of the inner
+   * vectors has length one. Then, the corresponding entry is used as the
+   * maximal row length.
    *
-   * For the diagonal blocks, the
-   * inner SparsityPattern is
-   * initialized with optimized
-   * diagonals, while this is not
-   * done for the off-diagonal blocks.
+   * For the diagonal blocks, the inner SparsityPattern is initialized with
+   * optimized diagonals, while this is not done for the off-diagonal blocks.
    */
   void reinit (const BlockIndices &row_indices,
                const BlockIndices &col_indices,
@@ -548,56 +428,38 @@ public:
 
 
   /**
-   * Return whether the structure
-   * is compressed or not,
-   * i.e. whether all sub-matrices
-   * are compressed.
+   * Return whether the structure is compressed or not, i.e. whether all sub-
+   * matrices are compressed.
    */
   bool is_compressed () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-   * Copy data from an object of
-   * type
-   * BlockCompressedSparsityPattern,
-   * i.e. resize this object to the
-   * size of the given argument,
-   * and copy over the contents of
-   * each of the
-   * subobjects. Previous content
-   * of this object is lost.
+   * Copy data from an object of type BlockCompressedSparsityPattern, i.e.
+   * resize this object to the size of the given argument, and copy over the
+   * contents of each of the subobjects. Previous content of this object is
+   * lost.
    */
   void copy_from (const BlockCompressedSparsityPattern &csp);
 
   /**
-   * Copy data from an object of
-   * type
-   * BlockCompressedSetSparsityPattern,
-   * i.e. resize this object to the
-   * size of the given argument,
-   * and copy over the contents of
-   * each of the
-   * subobjects. Previous content
-   * of this object is lost.
+   * Copy data from an object of type BlockCompressedSetSparsityPattern, i.e.
+   * resize this object to the size of the given argument, and copy over the
+   * contents of each of the subobjects. Previous content of this object is
+   * lost.
    */
   void copy_from (const BlockCompressedSetSparsityPattern &csp);
 
   /**
-   * Copy data from an object of
-   * type
-   * BlockCompressedSimpleSparsityPattern,
-   * i.e. resize this object to the
-   * size of the given argument,
-   * and copy over the contents of
-   * each of the
-   * subobjects. Previous content
-   * of this object is lost.
+   * Copy data from an object of type BlockCompressedSimpleSparsityPattern,
+   * i.e. resize this object to the size of the given argument, and copy over
+   * the contents of each of the subobjects. Previous content of this object
+   * is lost.
    */
   void copy_from (const BlockCompressedSimpleSparsityPattern &csp);
 
@@ -618,29 +480,27 @@ public:
  *
  * This class is an example of the "dynamic" type of @ref Sparsity.
  *
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
  *
- * <b>Note:</b> This class used to be called
- * CompressedBlockSparsityPattern. However, since it's a block wrapper around
- * the CompressedSparsityPattern class, this is a misnomer and the class has
- * been renamed.
+ * <b>Note:</b> This class used to be called CompressedBlockSparsityPattern.
+ * However, since it's a block wrapper around the CompressedSparsityPattern
+ * class, this is a misnomer and the class has been renamed.
  *
  * <h3>Example</h3>
  *
- * Usage of this class is very similar to CompressedSparsityPattern,
- * but since the use of block indices causes some additional
- * complications, we give a short example.
+ * Usage of this class is very similar to CompressedSparsityPattern, but since
+ * the use of block indices causes some additional complications, we give a
+ * short example.
  *
  * @dontinclude compressed_block_sparsity_pattern.cc
  *
  * After the the DoFHandler <tt>dof</tt> and the ConstraintMatrix
- * <tt>constraints</tt> have been set up with a system element, we
- * must count the degrees of freedom in each matrix block:
+ * <tt>constraints</tt> have been set up with a system element, we must count
+ * the degrees of freedom in each matrix block:
  *
- * @skipline dofs_per_block
- * @until count
+ * @skipline dofs_per_block @until count
  *
  * Now, we are ready to set up the BlockCompressedSparsityPattern.
  *
@@ -650,8 +510,7 @@ public:
  *
  * @until condense
  *
- * In the end, it is copied to a normal BlockSparsityPattern for later
- * use.
+ * In the end, it is copied to a normal BlockSparsityPattern for later use.
  *
  * @until copy
  *
@@ -662,85 +521,56 @@ class BlockCompressedSparsityPattern : public BlockSparsityPatternBase<Compresse
 public:
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   BlockCompressedSparsityPattern ();
 
   /**
-   * Initialize the matrix with the
-   * given number of block rows and
-   * columns. The blocks themselves
-   * are still empty, and you have
-   * to call collect_sizes() after
-   * you assign them sizes.
+   * Initialize the matrix with the given number of block rows and columns.
+   * The blocks themselves are still empty, and you have to call
+   * collect_sizes() after you assign them sizes.
    */
   BlockCompressedSparsityPattern (const size_type n_rows,
                                   const size_type n_columns);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns. This function is
-   * equivalent to calling the
-   * previous constructor with the
-   * length of the two index vector
-   * and then entering the index
-   * values.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns. This function is equivalent to calling the
+   * previous constructor with the length of the two index vector and then
+   * entering the index values.
    */
   BlockCompressedSparsityPattern (const std::vector<size_type> &row_block_sizes,
                                   const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns.
    */
   BlockCompressedSparsityPattern (const BlockIndices &row_indices,
                                   const BlockIndices &col_indices);
 
   /**
-   * Resize the matrix to a tensor
-   * product of matrices with
-   * dimensions defined by the
-   * arguments.
+   * Resize the matrix to a tensor product of matrices with dimensions defined
+   * by the arguments.
    *
-   * The matrix will have as many
-   * block rows and columns as
-   * there are entries in the two
-   * arguments. The block at
-   * position (<i>i,j</i>) will
-   * have the dimensions
-   * <tt>row_block_sizes[i]</tt>
-   * times <tt>col_block_sizes[j]</tt>.
+   * The matrix will have as many block rows and columns as there are entries
+   * in the two arguments. The block at position (<i>i,j</i>) will have the
+   * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
    */
   void reinit (const std::vector<size_type> &row_block_sizes,
                const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Resize the matrix to a tensor
-   * product of matrices with
-   * dimensions defined by the
-   * arguments. The two
-   * BlockIndices objects must be
-   * initialized and the sparsity
-   * pattern will have the
-   * same block structure afterwards.
+   * Resize the matrix to a tensor product of matrices with dimensions defined
+   * by the arguments. The two BlockIndices objects must be initialized and
+   * the sparsity pattern will have the same block structure afterwards.
    */
   void reinit (const BlockIndices &row_indices, const BlockIndices &col_indices);
 
   /**
-   * Allow the use of the reinit
-   * functions of the base class as
-   * well.
+   * Allow the use of the reinit functions of the base class as well.
    */
   using BlockSparsityPatternBase<CompressedSparsityPattern>::reinit;
 };
@@ -768,9 +598,9 @@ typedef BlockCompressedSparsityPattern CompressedBlockSparsityPattern DEAL_II_DE
  *
  * This class is an example of the "dynamic" type of @ref Sparsity.
  *
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
  *
  * @author Wolfgang Bangerth, 2007
  */
@@ -779,85 +609,56 @@ class BlockCompressedSetSparsityPattern : public BlockSparsityPatternBase<Compre
 public:
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   BlockCompressedSetSparsityPattern ();
 
   /**
-   * Initialize the matrix with the
-   * given number of block rows and
-   * columns. The blocks themselves
-   * are still empty, and you have
-   * to call collect_sizes() after
-   * you assign them sizes.
+   * Initialize the matrix with the given number of block rows and columns.
+   * The blocks themselves are still empty, and you have to call
+   * collect_sizes() after you assign them sizes.
    */
   BlockCompressedSetSparsityPattern (const size_type n_rows,
                                      const size_type n_columns);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns. This function is
-   * equivalent to calling the
-   * previous constructor with the
-   * length of the two index vector
-   * and then entering the index
-   * values.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns. This function is equivalent to calling the
+   * previous constructor with the length of the two index vector and then
+   * entering the index values.
    */
   BlockCompressedSetSparsityPattern (const std::vector<size_type> &row_block_sizes,
                                      const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns.
    */
   BlockCompressedSetSparsityPattern (const BlockIndices &row_indices,
                                      const BlockIndices &col_indices);
 
   /**
-   * Resize the matrix to a tensor
-   * product of matrices with
-   * dimensions defined by the
-   * arguments.
+   * Resize the matrix to a tensor product of matrices with dimensions defined
+   * by the arguments.
    *
-   * The matrix will have as many
-   * block rows and columns as
-   * there are entries in the two
-   * arguments. The block at
-   * position (<i>i,j</i>) will
-   * have the dimensions
-   * <tt>row_block_sizes[i]</tt>
-   * times <tt>col_block_sizes[j]</tt>.
+   * The matrix will have as many block rows and columns as there are entries
+   * in the two arguments. The block at position (<i>i,j</i>) will have the
+   * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
    */
   void reinit (const std::vector<size_type> &row_block_sizes,
                const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Resize the matrix to a tensor
-   * product of matrices with
-   * dimensions defined by the
-   * arguments. The two
-   * BlockIndices objects must be
-   * initialized and the sparsity
-   * pattern will have the
-   * same block structure afterwards.
+   * Resize the matrix to a tensor product of matrices with dimensions defined
+   * by the arguments. The two BlockIndices objects must be initialized and
+   * the sparsity pattern will have the same block structure afterwards.
    */
   void reinit (const BlockIndices &row_indices, const BlockIndices &col_indices);
 
   /**
-   * Allow the use of the reinit
-   * functions of the base class as
-   * well.
+   * Allow the use of the reinit functions of the base class as well.
    */
   using BlockSparsityPatternBase<CompressedSetSparsityPattern>::reinit;
 };
@@ -871,14 +672,14 @@ public:
  * sparsity patterns that can be used to initialize objects of type
  * BlockSparsityPattern. It is used in the same way as the
  * BlockCompressedSparsityPattern except that it builds upon the
- * CompressedSimpleSparsityPattern instead of the CompressedSparsityPattern. See
- * the documentation of the BlockCompressedSparsityPattern for examples.
+ * CompressedSimpleSparsityPattern instead of the CompressedSparsityPattern.
+ * See the documentation of the BlockCompressedSparsityPattern for examples.
  *
  * This class is an example of the "dynamic" type of @ref Sparsity.
  *
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
  *
  * This class is used in step-22 and step-31.
  *
@@ -889,95 +690,65 @@ class BlockCompressedSimpleSparsityPattern : public BlockSparsityPatternBase<Com
 public:
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   BlockCompressedSimpleSparsityPattern ();
 
   /**
-   * Initialize the matrix with the
-   * given number of block rows and
-   * columns. The blocks themselves
-   * are still empty, and you have
-   * to call collect_sizes() after
-   * you assign them sizes.
+   * Initialize the matrix with the given number of block rows and columns.
+   * The blocks themselves are still empty, and you have to call
+   * collect_sizes() after you assign them sizes.
    */
   BlockCompressedSimpleSparsityPattern (const size_type n_rows,
                                         const size_type n_columns);
 
   /**
-   * Initialize the pattern with
-   * two BlockIndices for the block
-   * structures of matrix rows and
-   * columns. This function is
-   * equivalent to calling the
-   * previous constructor with the
-   * length of the two index vector
-   * and then entering the index
-   * values.
+   * Initialize the pattern with two BlockIndices for the block structures of
+   * matrix rows and columns. This function is equivalent to calling the
+   * previous constructor with the length of the two index vector and then
+   * entering the index values.
    */
   BlockCompressedSimpleSparsityPattern (const std::vector<size_type> &row_block_sizes,
                                         const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Initialize the pattern with symmetric
-   * blocks. The number of IndexSets in the
-   * vector determine the number of rows
-   * and columns of blocks. The size of
-   * each block is determined by the size()
-   * of the respective IndexSet. Each block
-   * only stores the rows given by the
-   * values in the IndexSet, which is
-   * useful for distributed memory parallel
-   * computations and usually corresponds
-   * to the locally owned DoFs.
+   * Initialize the pattern with symmetric blocks. The number of IndexSets in
+   * the vector determine the number of rows and columns of blocks. The size
+   * of each block is determined by the size() of the respective IndexSet.
+   * Each block only stores the rows given by the values in the IndexSet,
+   * which is useful for distributed memory parallel computations and usually
+   * corresponds to the locally owned DoFs.
    */
   BlockCompressedSimpleSparsityPattern (const std::vector<IndexSet> &partitioning);
 
   /**
-   * Resize the pattern to a tensor product
-   * of matrices with dimensions defined by
-   * the arguments.
+   * Resize the pattern to a tensor product of matrices with dimensions
+   * defined by the arguments.
    *
-   * The matrix will have as many
-   * block rows and columns as
-   * there are entries in the two
-   * arguments. The block at
-   * position (<i>i,j</i>) will
-   * have the dimensions
-   * <tt>row_block_sizes[i]</tt>
-   * times <tt>col_block_sizes[j]</tt>.
+   * The matrix will have as many block rows and columns as there are entries
+   * in the two arguments. The block at position (<i>i,j</i>) will have the
+   * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
    */
   void reinit (const std::vector<size_type> &row_block_sizes,
                const std::vector<size_type> &col_block_sizes);
 
   /**
-   * Resize the pattern with symmetric
-   * blocks determined by the size() of
-   * each IndexSet. See the constructor
-   * taking a vector of IndexSets for
-   * details.
+   * Resize the pattern with symmetric blocks determined by the size() of each
+   * IndexSet. See the constructor taking a vector of IndexSets for details.
    */
   void reinit(const std::vector<IndexSet> &partitioning);
 
   /**
-   * Access to column number field.
-   * Return the column number of
-   * the @p index th entry in row @p row.
+   * Access to column number field. Return the column number of the @p index
+   * th entry in row @p row.
    */
   size_type column_number (const size_type row,
                            const unsigned int index) const;
 
   /**
-   * Allow the use of the reinit
-   * functions of the base class as
-   * well.
+   * Allow the use of the reinit functions of the base class as well.
    */
   using BlockSparsityPatternBase<CompressedSimpleSparsityPattern>::reinit;
 };
@@ -991,17 +762,16 @@ public:
 /**
  * This class extends the base class to implement an array of Trilinos
  * sparsity patterns that can be used to initialize Trilinos block sparse
- * matrices that can be distributed among different processors. It is used
- * in the same way as the BlockSparsityPattern except that it builds upon
- * the TrilinosWrappers::SparsityPattern instead of the
- * dealii::SparsityPattern. See the documentation of the
- * BlockSparsityPattern for examples.
+ * matrices that can be distributed among different processors. It is used in
+ * the same way as the BlockSparsityPattern except that it builds upon the
+ * TrilinosWrappers::SparsityPattern instead of the dealii::SparsityPattern.
+ * See the documentation of the BlockSparsityPattern for examples.
  *
- * This class is has properties of the "dynamic" type of @ref Sparsity (in
- * the sense that it can extend the memory if too little elements were
- * allocated), but otherwise is more like the basic deal.II SparsityPattern
- * (in the sense that the method compress() needs to be called before the
- * pattern can be used).
+ * This class is has properties of the "dynamic" type of @ref Sparsity (in the
+ * sense that it can extend the memory if too little elements were allocated),
+ * but otherwise is more like the basic deal.II SparsityPattern (in the sense
+ * that the method compress() needs to be called before the pattern can be
+ * used).
  *
  * This class is used in step-32.
  *
@@ -1016,15 +786,14 @@ namespace TrilinosWrappers
 
     /**
      * Initialize the matrix empty, that is with no memory allocated. This is
-     * useful if you want such objects as member variables in other
-     * classes. You can make the structure usable by calling the reinit()
-     * function.
+     * useful if you want such objects as member variables in other classes.
+     * You can make the structure usable by calling the reinit() function.
      */
     BlockSparsityPattern ();
 
     /**
-     * Initialize the matrix with the given number of block rows and
-     * columns. The blocks themselves are still empty, and you have to call
+     * Initialize the matrix with the given number of block rows and columns.
+     * The blocks themselves are still empty, and you have to call
      * collect_sizes() after you assign them sizes.
      */
     BlockSparsityPattern (const size_type n_rows,
@@ -1064,11 +833,11 @@ namespace TrilinosWrappers
      * and columns of the matrix, where the size() of the IndexSets specifies
      * the size of the blocks and the values in each IndexSet denotes the rows
      * that are going to be saved in each block. The additional index set
-     * writable_rows is used to set all rows that we allow to write
-     * locally. This constructor is used to create matrices that allow several
-     * threads to write simultaneously into the matrix (to different rows, of
-     * course), see the method TrilinosWrappers::SparsityPattern::reinit
-     * method with three index set arguments for more details.
+     * writable_rows is used to set all rows that we allow to write locally.
+     * This constructor is used to create matrices that allow several threads
+     * to write simultaneously into the matrix (to different rows, of course),
+     * see the method TrilinosWrappers::SparsityPattern::reinit method with
+     * three index set arguments for more details.
      */
     BlockSparsityPattern (const std::vector<IndexSet> &row_parallel_partitioning,
                           const std::vector<IndexSet> &column_parallel_partitioning,
index f1b0b98fa769cd2e8ed74f75c23953559614576a..e22702c30b3f938f151b6f5d53b49b3a1dcfe1b3 100644 (file)
@@ -61,20 +61,17 @@ class BlockVector : public BlockVectorBase<Vector<Number> >
 {
 public:
   /**
-   * Typedef the base class for simpler
-   * access to its own typedefs.
+   * Typedef the base class for simpler access to its own typedefs.
    */
   typedef BlockVectorBase<Vector<Number> > BaseClass;
 
   /**
-   * Typedef the type of the underlying
-   * vector.
+   * Typedef the type of the underlying vector.
    */
   typedef typename BaseClass::BlockType  BlockType;
 
   /**
-   * Import the typedefs from the base
-   * class.
+   * Import the typedefs from the base class.
    */
   typedef typename BaseClass::value_type      value_type;
   typedef typename BaseClass::real_type       real_type;
@@ -87,30 +84,20 @@ public:
   typedef typename BaseClass::const_iterator  const_iterator;
 
   /**
-   *  Constructor. There are three
-   *  ways to use this
-   *  constructor. First, without
-   *  any arguments, it generates
-   *  an object with no
-   *  blocks. Given one argument,
-   *  it initializes <tt>num_blocks</tt>
-   *  blocks, but these blocks have
-   *  size zero. The third variant
-   *  finally initializes all
-   *  blocks to the same size
-   *  <tt>block_size</tt>.
+   * Constructor. There are three ways to use this constructor. First, without
+   * any arguments, it generates an object with no blocks. Given one argument,
+   * it initializes <tt>num_blocks</tt> blocks, but these blocks have size
+   * zero. The third variant finally initializes all blocks to the same size
+   * <tt>block_size</tt>.
    *
-   *  Confer the other constructor
-   *  further down if you intend to
-   *  use blocks of different
-   *  sizes.
+   * Confer the other constructor further down if you intend to use blocks of
+   * different sizes.
    */
   explicit BlockVector (const unsigned int num_blocks = 0,
                         const size_type block_size = 0);
 
   /**
-   * Copy-Constructor. Dimension set to
-   * that of V, all components are copied
+   * Copy-Constructor. Dimension set to that of V, all components are copied
    * from V
    */
   BlockVector (const BlockVector<Number> &V);
@@ -118,24 +105,16 @@ public:
 
 #ifndef DEAL_II_EXPLICIT_CONSTRUCTOR_BUG
   /**
-   * Copy constructor taking a BlockVector of
-   * another data type. This will fail if
-   * there is no conversion path from
-   * <tt>OtherNumber</tt> to <tt>Number</tt>. Note that
-   * you may lose accuracy when copying
-   * to a BlockVector with data elements with
-   * less accuracy.
+   * Copy constructor taking a BlockVector of another data type. This will
+   * fail if there is no conversion path from <tt>OtherNumber</tt> to
+   * <tt>Number</tt>. Note that you may lose accuracy when copying to a
+   * BlockVector with data elements with less accuracy.
    *
-   * Older versions of gcc did not honor
-   * the @p explicit keyword on template
-   * constructors. In such cases, it is
-   * easy to accidentally write code that
-   * can be very inefficient, since the
-   * compiler starts performing hidden
-   * conversions. To avoid this, this
-   * function is disabled if we have
-   * detected a broken compiler during
-   * configuration.
+   * Older versions of gcc did not honor the @p explicit keyword on template
+   * constructors. In such cases, it is easy to accidentally write code that
+   * can be very inefficient, since the compiler starts performing hidden
+   * conversions. To avoid this, this function is disabled if we have detected
+   * a broken compiler during configuration.
    */
   template <typename OtherNumber>
   explicit
@@ -145,48 +124,31 @@ public:
 
 #ifdef DEAL_II_WITH_TRILINOS
   /**
-   * A copy constructor taking a
-   * (parallel) Trilinos block
-   * vector and copying it into
-   * the deal.II own format.
+   * A copy constructor taking a (parallel) Trilinos block vector and copying
+   * it into the deal.II own format.
    */
   BlockVector (const TrilinosWrappers::BlockVector &v);
 
 #endif
   /**
-   * Constructor. Set the number of
-   * blocks to
-   * <tt>block_sizes.size()</tt> and
-   * initialize each block with
-   * <tt>block_sizes[i]</tt> zero
-   * elements.
+   * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt> and
+   * initialize each block with <tt>block_sizes[i]</tt> zero elements.
    */
   BlockVector (const std::vector<size_type> &block_sizes);
 
   /**
-   * Constructor. Initialize vector
-   * to the structure found in the
-   * BlockIndices argument.
+   * Constructor. Initialize vector to the structure found in the BlockIndices
+   * argument.
    */
   BlockVector (const BlockIndices &block_indices);
 
   /**
-   * Constructor. Set the number of
-   * blocks to
-   * <tt>n.size()</tt>. Initialize the
-   * vector with the elements
-   * pointed to by the range of
-   * iterators given as second and
-   * third argument. Apart from the
-   * first argument, this
-   * constructor is in complete
-   * analogy to the respective
-   * constructor of the
-   * <tt>std::vector</tt> class, but the
-   * first argument is needed in
-   * order to know how to subdivide
-   * the block vector into
-   * different blocks.
+   * Constructor. Set the number of blocks to <tt>n.size()</tt>. Initialize
+   * the vector with the elements pointed to by the range of iterators given
+   * as second and third argument. Apart from the first argument, this
+   * constructor is in complete analogy to the respective constructor of the
+   * <tt>std::vector</tt> class, but the first argument is needed in order to
+   * know how to subdivide the block vector into different blocks.
    */
   template <typename InputIterator>
   BlockVector (const std::vector<size_type>    &n,
@@ -199,39 +161,32 @@ public:
   ~BlockVector ();
 
   /**
-   * Call the compress() function on all
-   * the subblocks.
-  *
-  * This functionality only needs to be
-  * called if using MPI based vectors and
-  * exists in other objects for
-  * compatibility.
-  *
-  * See @ref GlossCompress "Compressing
-  * distributed objects" for more
-  * information.
+   * Call the compress() function on all the subblocks.
+   *
+   * This functionality only needs to be called if using MPI based vectors and
+   * exists in other objects for compatibility.
+   *
+   * See @ref GlossCompress "Compressing distributed objects" for more
+   * information.
    */
   void compress (::dealii::VectorOperation::values operation
                  =::dealii::VectorOperation::unknown);
 
   /**
-   * Copy operator: fill all components of
-   * the vector with the given scalar
+   * Copy operator: fill all components of the vector with the given scalar
    * value.
    */
   BlockVector &operator = (const value_type s);
 
   /**
-   * Copy operator for arguments of the
-   * same type. Resize the
-   * present vector if necessary.
+   * Copy operator for arguments of the same type. Resize the present vector
+   * if necessary.
    */
   BlockVector &
   operator= (const BlockVector &V);
 
   /**
-   * Copy operator for template arguments
-   * of different types. Resize the
+   * Copy operator for template arguments of different types. Resize the
    * present vector if necessary.
    */
   template <class Number2>
@@ -239,184 +194,119 @@ public:
   operator= (const BlockVector<Number2> &V);
 
   /**
-   * Copy a regular vector into a
-   * block vector.
+   * Copy a regular vector into a block vector.
    */
   BlockVector &
   operator= (const Vector<Number> &V);
 
 #ifdef DEAL_II_WITH_TRILINOS
   /**
-   * A copy constructor from a
-   * Trilinos block vector to a
-   * deal.II block vector.
+   * A copy constructor from a Trilinos block vector to a deal.II block
+   * vector.
    */
   BlockVector &
   operator= (const TrilinosWrappers::BlockVector &V);
 #endif
   /**
-   * Reinitialize the BlockVector to
-   * contain <tt>num_blocks</tt> blocks of
+   * Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
    * size <tt>block_size</tt> each.
    *
-   * If the second argument is left
-   * at its default value, then the
-   * block vector allocates the
-   * specified number of blocks but
-   * leaves them at zero size. You
-   * then need to later
-   * reinitialize the individual
-   * blocks, and call
-   * collect_sizes() to update the
-   * block system's knowledge of
-   * its individual block's sizes.
+   * If the second argument is left at its default value, then the block
+   * vector allocates the specified number of blocks but leaves them at zero
+   * size. You then need to later reinitialize the individual blocks, and call
+   * collect_sizes() to update the block system's knowledge of its individual
+   * block's sizes.
    *
-   * If <tt>fast==false</tt>, the vector
-   * is filled with zeros.
+   * If <tt>fast==false</tt>, the vector is filled with zeros.
    */
   void reinit (const unsigned int num_blocks,
                const size_type block_size = 0,
                const bool fast = false);
 
   /**
-   * Reinitialize the BlockVector such that
-   * it contains
-   * <tt>block_sizes.size()</tt>
-   * blocks. Each block is reinitialized to
+   * Reinitialize the BlockVector such that it contains
+   * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
    * dimension <tt>block_sizes[i]</tt>.
    *
-   * If the number of blocks is the
-   * same as before this function
-   * was called, all vectors remain
-   * the same and reinit() is
-   * called for each vector.
+   * If the number of blocks is the same as before this function was called,
+   * all vectors remain the same and reinit() is called for each vector.
    *
-   * If <tt>fast==false</tt>, the vector
-   * is filled with zeros.
+   * If <tt>fast==false</tt>, the vector is filled with zeros.
    *
-   * Note that you must call this
-   * (or the other reinit()
-   * functions) function, rather
-   * than calling the reinit()
-   * functions of an individual
-   * block, to allow the block
-   * vector to update its caches of
-   * vector sizes. If you call
-   * reinit() on one of the
-   * blocks, then subsequent
-   * actions on this object may
-   * yield unpredictable results
-   * since they may be routed to
-   * the wrong block.
+   * Note that you must call this (or the other reinit() functions) function,
+   * rather than calling the reinit() functions of an individual block, to
+   * allow the block vector to update its caches of vector sizes. If you call
+   * reinit() on one of the blocks, then subsequent actions on this object may
+   * yield unpredictable results since they may be routed to the wrong block.
    */
   void reinit (const std::vector<size_type> &N,
                const bool                    fast=false);
 
   /**
-   * Reinitialize the BlockVector
-   * to reflect the structure found
-   * in BlockIndices.
+   * Reinitialize the BlockVector to reflect the structure found in
+   * BlockIndices.
    *
-   * If the number of blocks is the
-   * same as before this function
-   * was called, all vectors remain
-   * the same and reinit() is
-   * called for each vector.
+   * If the number of blocks is the same as before this function was called,
+   * all vectors remain the same and reinit() is called for each vector.
    *
-   * If <tt>fast==false</tt>, the vector
-   * is filled with zeros.
+   * If <tt>fast==false</tt>, the vector is filled with zeros.
    */
   void reinit (const BlockIndices &block_indices,
                const bool fast=false);
 
   /**
-   * Change the dimension to that
-   * of the vector <tt>V</tt>. The same
-   * applies as for the other
-   * reinit() function.
+   * Change the dimension to that of the vector <tt>V</tt>. The same applies
+   * as for the other reinit() function.
    *
-   * The elements of <tt>V</tt> are not
-   * copied, i.e.  this function is
-   * the same as calling <tt>reinit
-   * (V.size(), fast)</tt>.
+   * The elements of <tt>V</tt> are not copied, i.e.  this function is the
+   * same as calling <tt>reinit (V.size(), fast)</tt>.
    *
-   * Note that you must call this
-   * (or the other reinit()
-   * functions) function, rather
-   * than calling the reinit()
-   * functions of an individual
-   * block, to allow the block
-   * vector to update its caches of
-   * vector sizes. If you call
-   * reinit() of one of the
-   * blocks, then subsequent
-   * actions of this object may
-   * yield unpredictable results
-   * since they may be routed to
-   * the wrong block.
+   * Note that you must call this (or the other reinit() functions) function,
+   * rather than calling the reinit() functions of an individual block, to
+   * allow the block vector to update its caches of vector sizes. If you call
+   * reinit() of one of the blocks, then subsequent actions of this object may
+   * yield unpredictable results since they may be routed to the wrong block.
    */
   template <typename Number2>
   void reinit (const BlockVector<Number2> &V,
                const bool                 fast=false);
 
   /**
-   * Scale each element of the
-   * vector by the given factor.
+   * Scale each element of the vector by the given factor.
    *
-   * This function is deprecated
-   * and will be removed in a
-   * future version. Use
-   * <tt>operator *=</tt> and
-   * <tt>operator /=</tt> instead.
+   * This function is deprecated and will be removed in a future version. Use
+   * <tt>operator *=</tt> and <tt>operator /=</tt> instead.
    *
-   * @deprecated Use <tt>operator*=</tt>
-   * instead.
+   * @deprecated Use <tt>operator*=</tt> instead.
    */
   void scale (const value_type factor) DEAL_II_DEPRECATED;
 
   /**
-   * Multiply each element of this
-   * vector by the corresponding
-   * element of <tt>v</tt>.
+   * Multiply each element of this vector by the corresponding element of
+   * <tt>v</tt>.
    */
   template <class BlockVector2>
   void scale (const BlockVector2 &v);
 
   /**
-   * Swap the contents of this
-   * vector and the other vector
-   * <tt>v</tt>. One could do this
-   * operation with a temporary
-   * variable and copying over the
-   * data elements, but this
-   * function is significantly more
-   * efficient since it only swaps
-   * the pointers to the data of
-   * the two vectors and therefore
-   * does not need to allocate
-   * temporary storage and move
-   * data around.
+   * Swap the contents of this vector and the other vector <tt>v</tt>. One
+   * could do this operation with a temporary variable and copying over the
+   * data elements, but this function is significantly more efficient since it
+   * only swaps the pointers to the data of the two vectors and therefore does
+   * not need to allocate temporary storage and move data around.
    *
-   * Limitation: right now this
-   * function only works if both
-   * vectors have the same number
-   * of blocks. If needed, the
-   * numbers of blocks should be
+   * Limitation: right now this function only works if both vectors have the
+   * same number of blocks. If needed, the numbers of blocks should be
    * exchanged, too.
    *
-   * This function is analog to the
-   * the swap() function of all C++
-   * standard containers. Also,
-   * there is a global function
-   * swap(u,v) that simply calls
-   * <tt>u.swap(v)</tt>, again in analogy
-   * to standard functions.
+   * This function is analog to the the swap() function of all C++ standard
+   * containers. Also, there is a global function swap(u,v) that simply calls
+   * <tt>u.swap(v)</tt>, again in analogy to standard functions.
    */
   void swap (BlockVector<Number> &v);
 
   /**
-   *  Output of vector in user-defined
-   *  format.
+   * Output of vector in user-defined format.
    */
   void print (const char *format = 0) const;
 
@@ -429,34 +319,29 @@ public:
               const bool          across = true) const;
 
   /**
-   * Write the vector en bloc to a
-   * stream. This is done in a binary mode,
-   * so the output is neither readable by
-   * humans nor (probably) by other
-   * computers using a different operating
-   * system or number format.
+   * Write the vector en bloc to a stream. This is done in a binary mode, so
+   * the output is neither readable by humans nor (probably) by other
+   * computers using a different operating system or number format.
    */
   void block_write (std::ostream &out) const;
 
   /**
-   * Read a vector en block from a
-   * file. This is done using the inverse
-   * operations to the above function, so
-   * it is reasonably fast because the
+   * Read a vector en block from a file. This is done using the inverse
+   * operations to the above function, so it is reasonably fast because the
    * bitstream is not interpreted.
    *
    * The vector is resized if necessary.
    *
-   * A primitive form of error checking is
-   * performed which will recognize the
-   * bluntest attempts to interpret some
-   * data as a vector stored bitwise to a
+   * A primitive form of error checking is performed which will recognize the
+   * bluntest attempts to interpret some data as a vector stored bitwise to a
    * file, but not more.
    */
   void block_read (std::istream &in);
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -576,9 +461,9 @@ void BlockVector<Number>::scale (const BlockVector2 &v)
 
 
 /**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
  *
  * @relates BlockVector
  * @author Wolfgang Bangerth, 2000
index 543b4a495ee6e707bb21486360c0b5dbc72fc005..943100c2fc40bac22e64cb6236fddb9625bc7940 100644 (file)
@@ -49,9 +49,9 @@ template <typename> class BlockVectorBase;
  * @code
  *   IsBlockVector<BlockVector<double> >::value
  * @endcode
- * is true. This is sometimes useful in template contexts where we may
- * want to do things differently depending on whether a template type
- * denotes a regular or a block vector type.
+ * is true. This is sometimes useful in template contexts where we may want to
+ * do things differently depending on whether a template type denotes a
+ * regular or a block vector type.
  *
  * @author Wolfgang Bangerth, 2010
  */
@@ -69,26 +69,22 @@ private:
   };
 
   /**
-   * Overload returning true if the class
-   * is derived from BlockVectorBase,
+   * Overload returning true if the class is derived from BlockVectorBase,
    * which is what block vectors do.
    */
   template <typename T>
   static yes_type check_for_block_vector (const BlockVectorBase<T> *);
 
   /**
-   * Catch all for all other potential
-   * vector types that are not block
+   * Catch all for all other potential vector types that are not block
    * matrices.
    */
   static no_type check_for_block_vector (...);
 
 public:
   /**
-   * A statically computable value that
-   * indicates whether the template
-   * argument to this class is a block
-   * vector (in fact whether the type is
+   * A statically computable value that indicates whether the template
+   * argument to this class is a block vector (in fact whether the type is
    * derived from BlockVectorBase<T>).
    */
   static const bool value = (sizeof(check_for_block_vector
@@ -116,11 +112,8 @@ namespace internal
   namespace BlockVectorIterators
   {
     /**
-     * Declaration of the general
-     * template of a structure which is
-     * used to determine some types
-     * based on the template arguments
-     * of other classes.
+     * Declaration of the general template of a structure which is used to
+     * determine some types based on the template arguments of other classes.
      */
     template <class BlockVectorType, bool constness>
     struct Types
@@ -130,47 +123,34 @@ namespace internal
 
 
     /**
-     * Declaration of a specialized
-     * template of a structure which is
-     * used to determine some types
-     * based on the template arguments
-     * of other classes.
+     * Declaration of a specialized template of a structure which is used to
+     * determine some types based on the template arguments of other classes.
      *
-     * This is for the use of non-const
-     * iterators.
+     * This is for the use of non-const iterators.
      */
     template <class BlockVectorType>
     struct Types<BlockVectorType,false>
     {
       /**
-       * Type of the vector
-       * underlying the block vector
-       * used in non-const
-       * iterators. There, the
-       * vector must not be constant.
+       * Type of the vector underlying the block vector used in non-const
+       * iterators. There, the vector must not be constant.
        */
       typedef typename BlockVectorType::BlockType Vector;
 
       /**
-       * Type of the block vector
-       * used in non-const
-       * iterators. There, the block
-       * vector must not be constant.
+       * Type of the block vector used in non-const iterators. There, the
+       * block vector must not be constant.
        */
       typedef BlockVectorType BlockVector;
 
       /**
-       * Type of the numbers we point
-       * to. Here, they are not
-       * constant.
+       * Type of the numbers we point to. Here, they are not constant.
        */
       typedef typename BlockVector::value_type value_type;
 
       /**
-       * Typedef the result of a
-       * dereferencing operation for an
-       * iterator of the underlying
-       * iterator.
+       * Typedef the result of a dereferencing operation for an iterator of
+       * the underlying iterator.
        */
       typedef typename Vector::reference dereference_type;
     };
@@ -178,113 +158,67 @@ namespace internal
 
 
     /**
-     * Declaration of a specialized
-     * template of a structure which is
-     * used to determine some types
-     * based on the template arguments
-     * of other classes.
+     * Declaration of a specialized template of a structure which is used to
+     * determine some types based on the template arguments of other classes.
      *
-     * This is for the use of
-     * const_iterator.
+     * This is for the use of const_iterator.
      */
     template <class BlockVectorType>
     struct Types<BlockVectorType,true>
     {
       /**
-       * Type of the vector
-       * underlying the block vector
-       * used in
-       * const_iterator. There,
-       * the vector must be
-       * constant.
+       * Type of the vector underlying the block vector used in
+       * const_iterator. There, the vector must be constant.
        */
       typedef const typename BlockVectorType::BlockType Vector;
 
       /**
-       * Type of the block vector
-       * used in
-       * const_iterator. There,
-       * the block vector must be
-       * constant.
+       * Type of the block vector used in const_iterator. There, the block
+       * vector must be constant.
        */
       typedef const BlockVectorType BlockVector;
 
       /**
-       * Type of the numbers we point
-       * to. Here, they are constant
-       * since the block vector we
-       * use is constant.
+       * Type of the numbers we point to. Here, they are constant since the
+       * block vector we use is constant.
        */
       typedef const typename BlockVector::value_type value_type;
 
       /**
-       * Typedef the result of a
-       * dereferencing operation for an
-       * iterator of the underlying
-       * iterator. Since this is for
-       * constant iterators, we can only
-       * return values, no actual
-       * references.
+       * Typedef the result of a dereferencing operation for an iterator of
+       * the underlying iterator. Since this is for constant iterators, we can
+       * only return values, no actual references.
        */
       typedef value_type dereference_type;
     };
 
 
     /**
-     * General random-access iterator
-     * class for block vectors. Since
-     * we do not want to have two
-     * classes for non-const
-     * iterator and
-     * const_iterator, we take a
-     * second template argument which
-     * denotes whether the vector we
-     * point into is a constant object
-     * or not. The first template
-     * argument is always the number
-     * type of the block vector in use.
+     * General random-access iterator class for block vectors. Since we do not
+     * want to have two classes for non-const iterator and const_iterator, we
+     * take a second template argument which denotes whether the vector we
+     * point into is a constant object or not. The first template argument is
+     * always the number type of the block vector in use.
      *
-     * This class satisfies all
-     * requirements of random access
-     * iterators defined in the C++
-     * standard. Operations on these
-     * iterators are constant in the
-     * number of elements in the block
-     * vector. However, they are
-     * sometimes linear in the number
-     * of blocks in the vector, but
-     * since that does rarely change
-     * dynamically within an
-     * application, this is a constant
-     * and we again have that the
-     * iterator satisfies the
-     * requirements of a random access
-     * iterator.
+     * This class satisfies all requirements of random access iterators
+     * defined in the C++ standard. Operations on these iterators are constant
+     * in the number of elements in the block vector. However, they are
+     * sometimes linear in the number of blocks in the vector, but since that
+     * does rarely change dynamically within an application, this is a
+     * constant and we again have that the iterator satisfies the requirements
+     * of a random access iterator.
      *
-     * The implementation of this class
-     * has to work around some problems
-     * in compilers and standard
-     * libraries. One of these requires
-     * us to write all comparison
-     * operators twice, once comparison
-     * with iterators of the same type
-     * and once with iterators pointing
-     * to numbers of opposite constness
-     * specification. The reason is
-     * that if we would have written
-     * the comparison operators as a
-     * template on the constness of the
-     * right hand side, then gcc2.95
-     * signals an error that these
-     * operators ambiguate operators
-     * declared somewhere within the
-     * standard library. Likewise, we
-     * have to work around some
-     * problems with granting other
-     * iterators friendship. This makes
-     * the implementation somewhat
-     * non-optimal at places, but at
-     * least everything works.
+     * The implementation of this class has to work around some problems in
+     * compilers and standard libraries. One of these requires us to write all
+     * comparison operators twice, once comparison with iterators of the same
+     * type and once with iterators pointing to numbers of opposite constness
+     * specification. The reason is that if we would have written the
+     * comparison operators as a template on the constness of the right hand
+     * side, then gcc2.95 signals an error that these operators ambiguate
+     * operators declared somewhere within the standard library. Likewise, we
+     * have to work around some problems with granting other iterators
+     * friendship. This makes the implementation somewhat non-optimal at
+     * places, but at least everything works.
      *
      * @author Wolfgang Bangerth, 2001
      */
@@ -295,10 +229,8 @@ namespace internal
     {
     private:
       /**
-       * Typedef an iterator with
-       * opposite constness
-       * requirements on the elements
-       * it points to.
+       * Typedef an iterator with opposite constness requirements on the
+       * elements it points to.
        */
       typedef Iterator<BlockVectorType,!constness> InverseConstnessIterator;
 
@@ -309,12 +241,8 @@ namespace internal
       typedef types::global_dof_index size_type;
 
       /**
-       * Type of the number this
-       * iterator points
-       * to. Depending on the value
-       * of the second template
-       * parameter, this is either a
-       * constant or non-const
+       * Type of the number this iterator points to. Depending on the value of
+       * the second template parameter, this is either a constant or non-const
        * number.
        */
       typedef
@@ -322,12 +250,9 @@ namespace internal
       value_type;
 
       /**
-       * Declare some typedefs which
-       * are standard for iterators
-       * and are used by algorithms
-       * to enquire about the
-       * specifics of the iterators
-       * they work on.
+       * Declare some typedefs which are standard for iterators and are used
+       * by algorithms to enquire about the specifics of the iterators they
+       * work on.
        */
       typedef std::random_access_iterator_tag               iterator_type;
       typedef std::ptrdiff_t                                difference_type;
@@ -339,29 +264,20 @@ namespace internal
       dereference_type;
 
       /**
-       * Typedef the type of the
-       * block vector (which differs
-       * in constness, depending on
-       * the second template
-       * parameter).
+       * Typedef the type of the block vector (which differs in constness,
+       * depending on the second template parameter).
        */
       typedef
       typename Types<BlockVectorType,constness>::BlockVector
       BlockVector;
 
       /**
-       * Construct an iterator from
-       * a vector to which we point
-       * and the global index of
-       * the element pointed to.
+       * Construct an iterator from a vector to which we point and the global
+       * index of the element pointed to.
        *
-       * Depending on the value of
-       * the <tt>constness</tt> template
-       * argument of this class,
-       * the first argument of this
-       * constructor is either is a
-       * const or non-const
-       * reference.
+       * Depending on the value of the <tt>constness</tt> template argument of
+       * this class, the first argument of this constructor is either is a
+       * const or non-const reference.
        */
       Iterator (BlockVector     &parent,
                 const size_type  global_index);
@@ -372,24 +288,16 @@ namespace internal
       Iterator (const Iterator<BlockVectorType,constness> &c);
 
       /**
-       * Copy constructor for
-       * conversion between iterators
-       * with different constness
-       * requirements. This
-       * constructor throws an error
-       * if an attempt is made at
-       * converting a constant to a
-       * non-constant iterator.
+       * Copy constructor for conversion between iterators with different
+       * constness requirements. This constructor throws an error if an
+       * attempt is made at converting a constant to a non-constant iterator.
        */
       Iterator (const InverseConstnessIterator &c);
 
     private:
       /**
-       * Constructor used internally
-       * in this class. The arguments
-       * match exactly the values of
-       * the respective member
-       * variables.
+       * Constructor used internally in this class. The arguments match
+       * exactly the values of the respective member variables.
        */
       Iterator (BlockVector     &parent,
                 const size_type  global_index,
@@ -406,195 +314,146 @@ namespace internal
       Iterator &operator = (const Iterator &c);
 
       /**
-       * Dereferencing operator. If the
-       * template argument
-       * <tt>constness</tt> is
-       * <tt>true</tt>, then no writing to
-       * the result is possible, making
+       * Dereferencing operator. If the template argument <tt>constness</tt>
+       * is <tt>true</tt>, then no writing to the result is possible, making
        * this a const_iterator.
        */
       dereference_type operator * () const;
 
       /**
-       * Random access operator,
-       * grant access to arbitrary
-       * elements relative to the one
-       * presently pointed to.
+       * Random access operator, grant access to arbitrary elements relative
+       * to the one presently pointed to.
        */
       dereference_type operator [] (const difference_type d) const;
 
       /**
-       * Prefix increment operator. This
-       * operator advances the iterator to
-       * the next element and returns a
-       * reference to <tt>*this</tt>.
+       * Prefix increment operator. This operator advances the iterator to the
+       * next element and returns a reference to <tt>*this</tt>.
        */
       Iterator &operator ++ ();
 
       /**
-       * Postfix increment
-       * operator. This operator
-       * advances the iterator to
-       * the next element and
-       * returns a copy of the old
-       * value of this iterator.
+       * Postfix increment operator. This operator advances the iterator to
+       * the next element and returns a copy of the old value of this
+       * iterator.
        */
       Iterator operator ++ (int);
 
       /**
-       * Prefix decrement operator. This
-       * operator retracts the iterator to
-       * the previous element and returns a
-       * reference to <tt>*this</tt>.
+       * Prefix decrement operator. This operator retracts the iterator to the
+       * previous element and returns a reference to <tt>*this</tt>.
        */
       Iterator &operator -- ();
 
       /**
-       * Postfix decrement
-       * operator. This operator
-       * retracts the iterator to
-       * the previous element and
-       * returns a copy of the old
-       * value of this iterator.
+       * Postfix decrement operator. This operator retracts the iterator to
+       * the previous element and returns a copy of the old value of this
+       * iterator.
        */
       Iterator operator -- (int);
 
       /**
-       * Compare for equality of
-       * iterators. This operator
-       * checks whether the vectors
-       * pointed to are the same,
-       * and if not it throws an
-       * exception.
+       * Compare for equality of iterators. This operator checks whether the
+       * vectors pointed to are the same, and if not it throws an exception.
        */
       bool operator == (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator == (const InverseConstnessIterator &i) const;
 
       /**
-       * Compare for inequality of
-       * iterators. This operator
-       * checks whether the vectors
-       * pointed to are the same,
-       * and if not it throws an
-       * exception.
+       * Compare for inequality of iterators. This operator checks whether the
+       * vectors pointed to are the same, and if not it throws an exception.
        */
       bool operator != (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator != (const InverseConstnessIterator &i) const;
 
       /**
-       * Check whether this
-       * iterators points to an
-       * element previous to the
-       * one pointed to by the
-       * given argument. This
-       * operator checks whether
-       * the vectors pointed to are
-       * the same, and if not it
-       * throws an exception.
+       * Check whether this iterators points to an element previous to the one
+       * pointed to by the given argument. This operator checks whether the
+       * vectors pointed to are the same, and if not it throws an exception.
        */
       bool operator < (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator < (const InverseConstnessIterator &i) const;
 
       /**
-       * Comparison operator alike
-       * to the one above.
+       * Comparison operator alike to the one above.
        */
       bool operator <= (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator <= (const InverseConstnessIterator &i) const;
 
       /**
-       * Comparison operator alike
-       * to the one above.
+       * Comparison operator alike to the one above.
        */
       bool operator > (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator > (const InverseConstnessIterator &i) const;
 
       /**
-       * Comparison operator alike
-       * to the one above.
+       * Comparison operator alike to the one above.
        */
       bool operator >= (const Iterator &i) const;
 
       /**
-       * Same, but compare with an
-       * iterator of different
-       * constness.
+       * Same, but compare with an iterator of different constness.
        */
       bool operator >= (const InverseConstnessIterator &i) const;
 
       /**
-       * Return the distance between
-       * the two iterators, in
-       * elements.
+       * Return the distance between the two iterators, in elements.
        */
       difference_type operator - (const Iterator &i) const;
 
       /**
-       * Same, but for iterators of
-       * opposite constness.
+       * Same, but for iterators of opposite constness.
        */
       difference_type operator - (const InverseConstnessIterator &i) const;
 
       /**
-       * Return an iterator which is
-       * the given number of elements
-       * in front of the present one.
+       * Return an iterator which is the given number of elements in front of
+       * the present one.
        */
       Iterator operator + (const difference_type &d) const;
 
       /**
-       * Return an iterator which is
-       * the given number of elements
-       * behind the present one.
+       * Return an iterator which is the given number of elements behind the
+       * present one.
        */
       Iterator operator - (const difference_type &d) const;
 
       /**
-       * Move the iterator <tt>d</tt>
-       * elements forward at once,
-       * and return the result.
+       * Move the iterator <tt>d</tt> elements forward at once, and return the
+       * result.
        */
       Iterator &operator += (const difference_type &d);
 
       /**
-       * Move the iterator <tt>d</tt>
-       * elements backward at once,
-       * and return the result.
+       * Move the iterator <tt>d</tt> elements backward at once, and return
+       * the result.
        */
       Iterator &operator -= (const difference_type &d);
 
-      /** @addtogroup Exceptions
-       * @{ */
+      /**
+       * @addtogroup Exceptions
+       * @{
+       */
 
       /**
        * Exception.
@@ -607,44 +466,29 @@ namespace internal
       //@}
     private:
       /**
-       * Pointer to the block
-       * vector object to which
-       * this iterator
-       * points. Depending on the
-       * value of the <tt>constness</tt>
-       * template argument of this
-       * class, this is a <tt>const</tt>
-       * or non-<tt>const</tt> pointer.
+       * Pointer to the block vector object to which this iterator points.
+       * Depending on the value of the <tt>constness</tt> template argument of
+       * this class, this is a <tt>const</tt> or non-<tt>const</tt> pointer.
        */
       BlockVector *parent;
 
       /**
-       * Global index of the
-       * element to which we
-       * presently point.
+       * Global index of the element to which we presently point.
        */
       size_type     global_index;
 
       /**
-       * Current block and index
-       * within this block of the
-       * element presently pointed
-       * to.
+       * Current block and index within this block of the element presently
+       * pointed to.
        */
       unsigned int current_block;
       size_type index_within_block;
 
       /**
-       * Indices of the global
-       * element address at which
-       * we have to move on to
-       * another block when moving
-       * forward and
-       * backward. These indices
-       * are kept as a cache since
-       * this is much more
-       * efficient than always
-       * asking the parent object.
+       * Indices of the global element address at which we have to move on to
+       * another block when moving forward and backward. These indices are
+       * kept as a cache since this is much more efficient than always asking
+       * the parent object.
        */
       size_type next_break_forward;
       size_type next_break_backward;
@@ -661,13 +505,9 @@ namespace internal
 
 
       /**
-       * Mark all other instances of
-       * this template as friends. In
-       * fact, we only need the
-       * inverse constness iterator
-       * as friend, but this is
-       * something that ISO C++ does
-       * not allow to specify.
+       * Mark all other instances of this template as friends. In fact, we
+       * only need the inverse constness iterator as friend, but this is
+       * something that ISO C++ does not allow to specify.
        */
       template <typename N, bool C>
       friend class Iterator;
@@ -677,19 +517,18 @@ namespace internal
 
 
 /**
- * A vector composed of several blocks each representing a vector of
- * its own.
+ * A vector composed of several blocks each representing a vector of its own.
  *
  * The BlockVector is a collection of Vectors (e.g. of either deal.II Vector
  * objects or PETScWrappers::Vector object). Each of the vectors inside can
  * have a different size.
  *
  * The functionality of BlockVector includes everything a Vector can do, plus
- * the access to a single Vector inside the BlockVector by
- * <tt>block(i)</tt>. It also has a complete random access iterator, just as
- * the other Vector classes or the standard C++ library template
- * <tt>std::vector</tt>. Therefore, all algorithms working on iterators also
- * work with objects of this class.
+ * the access to a single Vector inside the BlockVector by <tt>block(i)</tt>.
+ * It also has a complete random access iterator, just as the other Vector
+ * classes or the standard C++ library template <tt>std::vector</tt>.
+ * Therefore, all algorithms working on iterators also work with objects of
+ * this class.
  *
  * While this base class implements most of the functionality by dispatching
  * calls to its member functions to the respective functions on each of the
@@ -702,16 +541,14 @@ namespace internal
  *
  * <h3>Accessing individual blocks, and resizing vectors</h3>
  *
- * Apart from using this object as a whole, you can use each block
- * separately as a vector, using the block() function.  There
- * is a single caveat: if you have changed the size of one or several
- * blocks, you must call the function collect_sizes() of the block
- * vector to update its internal structures.
+ * Apart from using this object as a whole, you can use each block separately
+ * as a vector, using the block() function.  There is a single caveat: if you
+ * have changed the size of one or several blocks, you must call the function
+ * collect_sizes() of the block vector to update its internal structures.
  *
- * @attention Warning: If you change the sizes of single blocks
- * without calling collect_sizes(), results may be unpredictable. The
- * debug version does not check consistency here for performance
- * reasons!
+ * @attention Warning: If you change the sizes of single blocks without
+ * calling collect_sizes(), results may be unpredictable. The debug version
+ * does not check consistency here for performance reasons!
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2000, 2001, 2002, 2004
@@ -721,8 +558,7 @@ class BlockVectorBase : public Subscriptor
 {
 public:
   /**
-   * Typedef the type of the underlying
-   * vector.
+   * Typedef the type of the underlying vector.
    */
   typedef VectorType BlockType;
 
@@ -746,36 +582,24 @@ public:
   typedef types::global_dof_index             size_type;
 
   /**
-   * Declare a type that has holds
-   * real-valued numbers with the
-   * same precision as the template
-   * argument to this class. If the
-   * template argument of this
-   * class is a real data type,
-   * then real_type equals the
-   * template argument. If the
-   * template argument is a
-   * std::complex type then
-   * real_type equals the type
-   * underlying the complex
-   * numbers.
+   * Declare a type that has holds real-valued numbers with the same precision
+   * as the template argument to this class. If the template argument of this
+   * class is a real data type, then real_type equals the template argument.
+   * If the template argument is a std::complex type then real_type equals the
+   * type underlying the complex numbers.
    *
-   * This typedef is used to
-   * represent the return type of
-   * norms.
+   * This typedef is used to represent the return type of norms.
    */
   typedef typename BlockType::real_type real_type;
 
   /**
-   * A variable that indicates whether this vector
-   * supports distributed data storage. If true, then
-   * this vector also needs an appropriate compress()
-   * function that allows communicating recent set or
-   * add operations to individual elements to be communicated
-   * to other processors.
+   * A variable that indicates whether this vector supports distributed data
+   * storage. If true, then this vector also needs an appropriate compress()
+   * function that allows communicating recent set or add operations to
+   * individual elements to be communicated to other processors.
    *
-   * For the current class, the variable equals the
-   * value declared for the type of the individual blocks.
+   * For the current class, the variable equals the value declared for the
+   * type of the individual blocks.
    */
   static const bool supports_distributed_data = BlockType::supports_distributed_data;
 
@@ -785,30 +609,21 @@ public:
   BlockVectorBase ();
 
   /**
-   * Update internal structures
-   * after resizing
-   * vectors. Whenever you reinited
-   * a block of a block vector, the
-   * internal data structures are
-   * corrupted. Therefore, you
-   * should call this function
-   * after al blocks got their new
+   * Update internal structures after resizing vectors. Whenever you reinited
+   * a block of a block vector, the internal data structures are corrupted.
+   * Therefore, you should call this function after al blocks got their new
    * size.
    */
   void collect_sizes ();
 
   /**
-   * Call the compress() function on all
-   * the subblocks of the matrix.
-  *
-  * This functionality only needs to be
-  * called if using MPI based vectors and
-  * exists in other objects for
-  * compatibility.
-  *
-  * See @ref GlossCompress "Compressing
-  * distributed objects" for more
-  * information.
+   * Call the compress() function on all the subblocks of the matrix.
+   *
+   * This functionality only needs to be called if using MPI based vectors and
+   * exists in other objects for compatibility.
+   *
+   * See @ref GlossCompress "Compressing distributed objects" for more
+   * information.
    */
   void compress (::dealii::VectorOperation::values operation);
 
@@ -830,14 +645,9 @@ public:
   block (const unsigned int i) const;
 
   /**
-   * Return a reference on the
-   * object that describes the
-   * mapping between block and
-   * global indices. The use of
-   * this function is highly
-   * deprecated and it should
-   * vanish in one of the next
-   * versions
+   * Return a reference on the object that describes the mapping between block
+   * and global indices. The use of this function is highly deprecated and it
+   * should vanish in one of the next versions
    */
   const BlockIndices &
   get_block_indices () const;
@@ -848,55 +658,48 @@ public:
   unsigned int n_blocks () const;
 
   /**
-   * Return dimension of the vector. This
-   * is the sum of the dimensions of all
+   * Return dimension of the vector. This is the sum of the dimensions of all
    * components.
    */
   std::size_t size () const;
 
   /**
-   * Return an index set that describes which elements of this vector
-   * are owned by the current processor. Note that this index set does
-   * not include elements this vector may store locally as ghost
-   * elements but that are in fact owned by another processor.
-   * As a consequence, the index sets returned on different
-   * processors if this is a distributed vector will form disjoint
-   * sets that add up to the complete index set.
-   * Obviously, if a vector is created on only one processor, then
-   * the result would satisfy
+   * Return an index set that describes which elements of this vector are
+   * owned by the current processor. Note that this index set does not include
+   * elements this vector may store locally as ghost elements but that are in
+   * fact owned by another processor. As a consequence, the index sets
+   * returned on different processors if this is a distributed vector will
+   * form disjoint sets that add up to the complete index set. Obviously, if a
+   * vector is created on only one processor, then the result would satisfy
    * @code
    *   vec.locally_owned_elements() == complete_index_set (vec.size())
    * @endcode
    *
-   * For block vectors, this function returns the union of the
-   * locally owned elements of the individual blocks, shifted by
-   * their respective index offsets.
+   * For block vectors, this function returns the union of the locally owned
+   * elements of the individual blocks, shifted by their respective index
+   * offsets.
    */
   IndexSet locally_owned_elements () const;
 
   /**
-   * Return an iterator pointing to
-   * the first element.
+   * Return an iterator pointing to the first element.
    */
   iterator begin ();
 
   /**
-   * Return an iterator pointing to
-   * the first element of a
-   * constant block vector.
+   * Return an iterator pointing to the first element of a constant block
+   * vector.
    */
   const_iterator begin () const;
 
   /**
-   * Return an iterator pointing to
-   * the element past the end.
+   * Return an iterator pointing to the element past the end.
    */
   iterator end ();
 
   /**
-   * Return an iterator pointing to
-   * the element past the end of a
-   * constant block vector.
+   * Return an iterator pointing to the element past the end of a constant
+   * block vector.
    */
   const_iterator end () const;
 
@@ -906,8 +709,7 @@ public:
   value_type operator() (const size_type i) const;
 
   /**
-   * Access components, returns U(i)
-   * as a writeable reference.
+   * Access components, returns U(i) as a writeable reference.
    */
   reference operator() (const size_type i);
 
@@ -919,30 +721,25 @@ public:
   value_type operator[] (const size_type i) const;
 
   /**
-   * Access components, returns U(i)
-   * as a writeable reference.
+   * Access components, returns U(i) as a writeable reference.
    *
    * Exactly the same as operator().
    */
   reference operator[] (const size_type i);
 
   /**
-   * A collective get operation: instead
-   * of getting individual elements of a
-   * vector, this function allows to get
-   * a whole set of elements at once. The
-   * indices of the elements to be read
-   * are stated in the first argument,
-   * the corresponding values are returned in the
-   * second.
+   * A collective get operation: instead of getting individual elements of a
+   * vector, this function allows to get a whole set of elements at once. The
+   * indices of the elements to be read are stated in the first argument, the
+   * corresponding values are returned in the second.
    */
   template <typename OtherNumber>
   void extract_subvector_to (const std::vector<size_type> &indices,
                              std::vector<OtherNumber> &values) const;
 
   /**
-   * Just as the above, but with pointers.
-   * Useful in minimizing copying of data around.
+   * Just as the above, but with pointers. Useful in minimizing copying of
+   * data around.
    */
   template <typename ForwardIterator, typename OutputIterator>
   void extract_subvector_to (ForwardIterator          indices_begin,
@@ -950,39 +747,33 @@ public:
                              OutputIterator           values_begin) const;
 
   /**
-   * Copy operator: fill all components of
-   * the vector with the given scalar
+   * Copy operator: fill all components of the vector with the given scalar
    * value.
    */
   BlockVectorBase &operator = (const value_type s);
 
   /**
-   * Copy operator for arguments of the
-   * same type.
+   * Copy operator for arguments of the same type.
    */
   BlockVectorBase &
   operator= (const BlockVectorBase &V);
 
   /**
-   * Copy operator for template arguments
-   * of different types.
+   * Copy operator for template arguments of different types.
    */
   template <class VectorType2>
   BlockVectorBase &
   operator= (const BlockVectorBase<VectorType2> &V);
 
   /**
-   * Copy operator from non-block
-   * vectors to block vectors.
+   * Copy operator from non-block vectors to block vectors.
    */
   BlockVectorBase &
   operator = (const VectorType &v);
 
   /**
-   * Check for equality of two block vector
-   * types. This operation is only allowed
-   * if the two vectors already have the
-   * same block structure.
+   * Check for equality of two block vector types. This operation is only
+   * allowed if the two vectors already have the same block structure.
    */
   template <class VectorType2>
   bool
@@ -999,35 +790,31 @@ public:
   real_type norm_sqr () const;
 
   /**
-   * Return the mean value of the elements
-   * of this vector.
+   * Return the mean value of the elements of this vector.
    */
   value_type mean_value () const;
 
   /**
-   * Return the $l_1$-norm of the vector,
-   * i.e. the sum of the absolute values.
+   * Return the $l_1$-norm of the vector, i.e. the sum of the absolute values.
    */
   real_type l1_norm () const;
 
   /**
-   * Return the $l_2$-norm of the vector,
-   * i.e. the square root of the sum of
+   * Return the $l_2$-norm of the vector, i.e. the square root of the sum of
    * the squares of the elements.
    */
   real_type l2_norm () const;
 
   /**
-   * Return the maximum absolute value of
-   * the elements of this vector, which is
-   * the $l_\infty$-norm of a vector.
+   * Return the maximum absolute value of the elements of this vector, which
+   * is the $l_\infty$-norm of a vector.
    */
   real_type linfty_norm () const;
 
   /**
-   * Performs a combined operation of a vector addition and a subsequent
-   * inner product, returning the value of the inner product. In other words,
-   * the result of this function is the same as if the user called
+   * Performs a combined operation of a vector addition and a subsequent inner
+   * product, returning the value of the inner product. In other words, the
+   * result of this function is the same as if the user called
    * @code
    * this->add(a, V);
    * return_value = *this * W;
@@ -1035,89 +822,70 @@ public:
    *
    * The reason this function exists is that this operation involves less
    * memory transfer than calling the two functions separately on deal.II's
-   * vector classes (Vector<Number> and parallel::distributed::Vector<double>).
-   * This method only needs to load three vectors, @p this, @p V, @p W,
-   * whereas calling separate methods means to load the calling vector @p this
-   * twice. Since most vector operations are memory transfer limited, this
-   * reduces the time by 25\% (or 50\% if @p W equals @p this).
+   * vector classes (Vector<Number> and
+   * parallel::distributed::Vector<double>). This method only needs to load
+   * three vectors, @p this, @p V, @p W, whereas calling separate methods
+   * means to load the calling vector @p this twice. Since most vector
+   * operations are memory transfer limited, this reduces the time by 25\% (or
+   * 50\% if @p W equals @p this).
    */
   value_type add_and_dot (const value_type       a,
                           const BlockVectorBase &V,
                           const BlockVectorBase &W);
 
   /**
-   * Returns true if the given global index is
-   * in the local range of this processor.
-   * Asks the corresponding block.
+   * Returns true if the given global index is in the local range of this
+   * processor. Asks the corresponding block.
    */
   bool in_local_range (const size_type global_index) const;
 
   /**
-   * Return whether the vector contains only
-   * elements with value zero. This function
-   * is mainly for internal consistency
-   * check and should seldom be used when
-   * not in debug mode since it uses quite
-   * some time.
+   * Return whether the vector contains only elements with value zero. This
+   * function is mainly for internal consistency check and should seldom be
+   * used when not in debug mode since it uses quite some time.
    */
   bool all_zero () const;
 
   /**
-   * Return @p true if the vector has no
-   * negative entries, i.e. all entries are
-   * zero or positive. This function is
-   * used, for example, to check whether
-   * refinement indicators are really all
-   * positive (or zero).
+   * Return @p true if the vector has no negative entries, i.e. all entries
+   * are zero or positive. This function is used, for example, to check
+   * whether refinement indicators are really all positive (or zero).
    */
   bool is_non_negative () const;
 
   /**
-   * Addition operator.  Fast equivalent to
-   * <tt>U.add(1, V)</tt>.
+   * Addition operator.  Fast equivalent to <tt>U.add(1, V)</tt>.
    */
   BlockVectorBase &
   operator += (const BlockVectorBase &V);
 
   /**
-   * Subtraction operator.  Fast equivalent
-   * to <tt>U.add(-1, V)</tt>.
+   * Subtraction operator.  Fast equivalent to <tt>U.add(-1, V)</tt>.
    */
   BlockVectorBase &
   operator -= (const BlockVectorBase &V);
 
 
   /**
-   * A collective add operation:
-   * This funnction adds a whole
-   * set of values stored in @p
-   * values to the vector
-   * components specified by @p
-   * indices.
+   * A collective add operation: This funnction adds a whole set of values
+   * stored in @p values to the vector components specified by @p indices.
    */
   template <typename Number>
   void add (const std::vector<size_type> &indices,
             const std::vector<Number>    &values);
 
   /**
-   * This is a second collective
-   * add operation. As a
-   * difference, this function
-   * takes a deal.II vector of
-   * values.
+   * This is a second collective add operation. As a difference, this function
+   * takes a deal.II vector of values.
    */
   template <typename Number>
   void add (const std::vector<size_type> &indices,
             const Vector<Number>         &values);
 
   /**
-   * Take an address where
-   * <tt>n_elements</tt> are stored
-   * contiguously and add them into
-   * the vector. Handles all cases
-   * which are not covered by the
-   * other two <tt>add()</tt>
-   * functions above.
+   * Take an address where <tt>n_elements</tt> are stored contiguously and add
+   * them into the vector. Handles all cases which are not covered by the
+   * other two <tt>add()</tt> functions above.
    */
   template <typename Number>
   void add (const size_type  n_elements,
@@ -1125,56 +893,46 @@ public:
             const Number    *values);
 
   /**
-   * $U(0-DIM)+=s$.  Addition of <tt>s</tt>
-   * to all components. Note that
-   * <tt>s</tt> is a scalar and not a
-   * vector.
+   * $U(0-DIM)+=s$.  Addition of <tt>s</tt> to all components. Note that
+   * <tt>s</tt> is a scalar and not a vector.
    */
   void add (const value_type s);
 
   /**
-   * U+=V.
-   * Simple vector addition, equal to the
-   * <tt>operator +=</tt>.
+   * U+=V. Simple vector addition, equal to the <tt>operator +=</tt>.
    */
   void add (const BlockVectorBase &V);
 
   /**
-   * U+=a*V.
-   * Simple addition of a scaled vector.
+   * U+=a*V. Simple addition of a scaled vector.
    */
   void add (const value_type a, const BlockVectorBase &V);
 
   /**
-   * U+=a*V+b*W.
-   * Multiple addition of scaled vectors.
+   * U+=a*V+b*W. Multiple addition of scaled vectors.
    */
   void add (const value_type a, const BlockVectorBase &V,
             const value_type b, const BlockVectorBase &W);
 
   /**
-   * U=s*U+V.
-   * Scaling and simple vector addition.
+   * U=s*U+V. Scaling and simple vector addition.
    */
   void sadd (const value_type s, const BlockVectorBase &V);
 
   /**
-   * U=s*U+a*V.
-   * Scaling and simple addition.
+   * U=s*U+a*V. Scaling and simple addition.
    */
   void sadd (const value_type s, const value_type a, const BlockVectorBase &V);
 
   /**
-   * U=s*U+a*V+b*W.
-   * Scaling and multiple addition.
+   * U=s*U+a*V+b*W. Scaling and multiple addition.
    */
   void sadd (const value_type s, const value_type a,
              const BlockVectorBase &V,
              const value_type b, const BlockVectorBase &W);
 
   /**
-   * U=s*U+a*V+b*W+c*X.
-   * Scaling and multiple addition.
+   * U=s*U+a*V+b*W+c*X. Scaling and multiple addition.
    */
   void sadd (const value_type s, const value_type a,
              const BlockVectorBase &V,
@@ -1182,61 +940,50 @@ public:
              const value_type c, const BlockVectorBase &X);
 
   /**
-   * Scale each element of the
-   * vector by a constant
-   * value.
+   * Scale each element of the vector by a constant value.
    */
   BlockVectorBase &operator *= (const value_type factor);
 
   /**
-   * Scale each element of the
-   * vector by the inverse of the
-   * given value.
+   * Scale each element of the vector by the inverse of the given value.
    */
   BlockVectorBase &operator /= (const value_type factor);
 
   /**
-   * Multiply each element of this
-   * vector by the corresponding
-   * element of <tt>v</tt>.
+   * Multiply each element of this vector by the corresponding element of
+   * <tt>v</tt>.
    */
   template <class BlockVector2>
   void scale (const BlockVector2 &v);
 
   /**
-   *  U=a*V. Assignment.
+   * U=a*V. Assignment.
    */
   template <class BlockVector2>
   void equ (const value_type a, const BlockVector2 &V);
 
   /**
-   * U=a*V+b*W.
-   * Replacing by sum.
+   * U=a*V+b*W. Replacing by sum.
    */
   void equ (const value_type a, const BlockVectorBase &V,
             const value_type b, const BlockVectorBase &W);
 
   /**
-   * This function does nothing but is
-   * there for compatibility with the
-   * @p PETScWrappers::Vector class.
+   * This function does nothing but is there for compatibility with the @p
+   * PETScWrappers::Vector class.
    *
-   * For the PETSc vector wrapper class,
-   * this function updates the ghost
-   * values of the PETSc vector. This
-   * is necessary after any modification
+   * For the PETSc vector wrapper class, this function updates the ghost
+   * values of the PETSc vector. This is necessary after any modification
    * before reading ghost values.
    *
-   * However, for the implementation of
-   * this class, it is immaterial and thus
+   * However, for the implementation of this class, it is immaterial and thus
    * an empty function.
    */
   void update_ghost_values () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -1247,16 +994,13 @@ protected:
   std::vector<VectorType> components;
 
   /**
-   * Object managing the
-   * transformation between global
-   * indices and indices within the
-   * different blocks.
+   * Object managing the transformation between global indices and indices
+   * within the different blocks.
    */
   BlockIndices block_indices;
 
   /**
-   * Make the iterator class a
-   * friend.
+   * Make the iterator class a friend.
    */
   template <typename N, bool C>
   friend class dealii::internal::BlockVectorIterators::Iterator;
index 7649cd67cf586ed714ac631ce58899b7baa00411..78e8f32cc8a72c1ba255c7f89b2b1c84518abc8f 100644 (file)
@@ -294,8 +294,8 @@ namespace ChunkSparseMatrixIterators
     MatrixType;
 
     /**
-     * A typedef for the type you get when you dereference an iterator
-     * of the current kind.
+     * A typedef for the type you get when you dereference an iterator of the
+     * current kind.
      */
     typedef
     const Accessor<number,Constness> &value_type;
@@ -364,10 +364,10 @@ namespace ChunkSparseMatrixIterators
     bool operator > (const Iterator &) const;
 
     /**
-     * Return the distance between the current iterator and the argument.
-     * The distance is given by how many times one has to apply operator++
-     * to the current iterator to get the argument (for a positive return
-     * value), or operator-- (for a negative return value).
+     * Return the distance between the current iterator and the argument. The
+     * distance is given by how many times one has to apply operator++ to the
+     * current iterator to get the argument (for a positive return value), or
+     * operator-- (for a negative return value).
      */
     int operator - (const Iterator &p) const;
 
@@ -388,13 +388,12 @@ namespace ChunkSparseMatrixIterators
 
 
 /**
- * Sparse matrix. This class implements the function to store values
- * in the locations of a sparse matrix denoted by a
- * SparsityPattern. The separation of sparsity pattern and values is
- * done since one can store data elements of different type in these
- * locations without the SparsityPattern having to know this, and more
- * importantly one can associate more than one matrix with the same
- * sparsity pattern.
+ * Sparse matrix. This class implements the function to store values in the
+ * locations of a sparse matrix denoted by a SparsityPattern. The separation
+ * of sparsity pattern and values is done since one can store data elements of
+ * different type in these locations without the SparsityPattern having to
+ * know this, and more importantly one can associate more than one matrix with
+ * the same sparsity pattern.
  *
  * The use of this class is demonstrated in step-51.
  *
@@ -414,17 +413,16 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Type of matrix entries. In analogy to
-   * the STL container classes.
+   * Type of matrix entries. In analogy to the STL container classes.
    */
   typedef number value_type;
 
   /**
    * Declare a type that has holds real-valued numbers with the same precision
    * as the template argument to this class. If the template argument of this
-   * class is a real data type, then real_type equals the template
-   * argument. If the template argument is a std::complex type then real_type
-   * equals the type underlying the complex numbers.
+   * class is a real data type, then real_type equals the template argument.
+   * If the template argument is a std::complex type then real_type equals the
+   * type underlying the complex numbers.
    *
    * This typedef is used to represent the return type of norms.
    */
@@ -760,9 +758,9 @@ public:
 
   /**
    * Return the value of the entry (<i>i,j</i>).  This may be an expensive
-   * operation and you should always take care where to call this function.
-   * In order to avoid abuse, this function throws an exception if the
-   * required element does not exist in the matrix.
+   * operation and you should always take care where to call this function. In
+   * order to avoid abuse, this function throws an exception if the required
+   * element does not exist in the matrix.
    *
    * In case you want a function that returns zero instead (for entries that
    * are not in the sparsity pattern of the matrix), use the el() function.
@@ -1255,10 +1253,10 @@ public:
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously been written by block_write() from a
-   * file. This is done using the inverse operations to the above function, so
-   * it is reasonably fast because the bitstream is not interpreted except for
-   * a few numbers up front.
+   * Read data that has previously been written by block_write() from a file.
+   * This is done using the inverse operations to the above function, so it is
+   * reasonably fast because the bitstream is not interpreted except for a few
+   * numbers up front.
    *
    * The object is resized on this operation, and all previous contents are
    * lost. Note, however, that no checks are performed whether new data and
@@ -1272,8 +1270,10 @@ public:
    */
   void block_read (std::istream &in);
 //@}
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -1338,8 +1338,7 @@ private:
   template <typename somenumber> friend class ChunkSparseMatrix;
 
   /**
-   * Also give access to internal details to the iterator/accessor
-   * classes.
+   * Also give access to internal details to the iterator/accessor classes.
    */
   template <typename,bool> friend class ChunkSparseMatrixIterators::Iterator;
   template <typename,bool> friend class ChunkSparseMatrixIterators::Accessor;
index 99b49fac07268f3840921d95c97a9246c2ac68a8..ca69cc46f58cef10f35691ddac4170f8def055f2 100644 (file)
@@ -52,11 +52,9 @@ namespace internal
     typedef types::global_dof_index size_type;
 
     /**
-     * Add the result of multiplying a chunk
-     * of size chunk_size times chunk_size by
-     * a source vector fragment of size
-     * chunk_size to the destination vector
-     * fragment.
+     * Add the result of multiplying a chunk of size chunk_size times
+     * chunk_size by a source vector fragment of size chunk_size to the
+     * destination vector fragment.
      */
     template <typename MatrixIterator,
               typename SrcIterator,
index 31e6ab75f90fb8b678eb959151e5e8cac61e3c6f..913d30395a673a27f4898297214fe061fd291e36 100644 (file)
@@ -48,13 +48,13 @@ namespace ChunkSparsityPatternIterators
   class Iterator;
 
   /**
-   * Accessor class for iterators into sparsity patterns. This class is
-   * also the base class for both const and non-const accessor classes
-   * into sparse matrices.
+   * Accessor class for iterators into sparsity patterns. This class is also
+   * the base class for both const and non-const accessor classes into sparse
+   * matrices.
    *
-   * Note that this class only allows read access to elements, providing
-   * their row and column number. It does not allow modifying the
-   * sparsity pattern itself.
+   * Note that this class only allows read access to elements, providing their
+   * row and column number. It does not allow modifying the sparsity pattern
+   * itself.
    *
    * @author Martin Kronbichler
    * @date 2013
@@ -96,8 +96,8 @@ namespace ChunkSparsityPatternIterators
      * entries are valid. However, before compression, the sparsity pattern
      * allocated some memory to be used while still adding new nonzero
      * entries; if you create iterators in this phase of the sparsity
-     * pattern's lifetime, you will iterate over elements that are not
-     * valid. If this is so, then this function will return false.
+     * pattern's lifetime, you will iterate over elements that are not valid.
+     * If this is so, then this function will return false.
      */
     bool is_valid_entry () const;
 
@@ -214,9 +214,9 @@ namespace ChunkSparsityPatternIterators
 
 
 /**
- * Structure representing the sparsity pattern of a sparse matrix.
- * This class is an example of the "static" type of @ref Sparsity.
- * It uses the compressed row storage (CSR) format to store data.
+ * Structure representing the sparsity pattern of a sparse matrix. This class
+ * is an example of the "static" type of @ref Sparsity. It uses the compressed
+ * row storage (CSR) format to store data.
  *
  * The use of this class is demonstrated in step-51.
  *
@@ -287,9 +287,8 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg max_per_row maximum number of nonzero entries per row
+   * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+   * number of nonzero entries per row
    */
   ChunkSparsityPattern (const size_type m,
                         const size_type n,
@@ -297,8 +296,8 @@ public:
                         const size_type chunk_size);
 
   /**
-   * @deprecated This constructor is deprecated. Use the version
-   * without the last argument
+   * @deprecated This constructor is deprecated. Use the version without the
+   * last argument
    */
   ChunkSparsityPattern (const size_type m,
                         const size_type n,
@@ -309,10 +308,9 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
+   * @arg m number of rows @arg n number of columns @arg row_lengths possible
+   * number of nonzero entries for each row.  This vector must have one entry
+   * for each row.
    */
   ChunkSparsityPattern (const size_type m,
                         const size_type n,
@@ -320,8 +318,8 @@ public:
                         const size_type chunk_size);
 
   /**
-   * @deprecated This constructor is deprecated. Use the version
-   * without the last argument
+   * @deprecated This constructor is deprecated. Use the version without the
+   * last argument
    */
   ChunkSparsityPattern (const size_type               m,
                         const size_type               n,
@@ -344,17 +342,17 @@ public:
   /**
    * Initialize a quadratic matrix.
    *
-   * @arg m number of rows and columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
+   * @arg m number of rows and columns @arg row_lengths possible number of
+   * nonzero entries for each row.  This vector must have one entry for each
+   * row.
    */
   ChunkSparsityPattern (const size_type                m,
                         const std::vector<size_type>  &row_lengths,
                         const size_type                chunk_size);
 
   /**
-   * @deprecated This constructor is deprecated. Use the version
-   * without the last argument
+   * @deprecated This constructor is deprecated. Use the version without the
+   * last argument
    */
   ChunkSparsityPattern (const size_type               m,
                         const std::vector<size_type> &row_lengths,
@@ -387,8 +385,8 @@ public:
                const size_type chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   void reinit (const size_type m,
                const size_type n,
@@ -406,11 +404,8 @@ public:
    * allocated if the new size extends the old one. This is done to save time
    * and to avoid fragmentation of the heap.
    *
-   * If the number of rows equals
-   * the number of columns then
-   * diagonal elements are stored
-   * first in each row to allow
-   * optimized access in relaxation
+   * If the number of rows equals the number of columns then diagonal elements
+   * are stored first in each row to allow optimized access in relaxation
    * methods of SparseMatrix.
    */
   void reinit (const size_type m,
@@ -419,8 +414,8 @@ public:
                const size_type chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   void reinit (const size_type                m,
                const size_type                n,
@@ -437,8 +432,8 @@ public:
                const size_type chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   void reinit (const size_type m,
                const size_type n,
@@ -544,8 +539,8 @@ public:
                   const size_type chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   template <typename ForwardIterator>
   void copy_from (const size_type       n_rows,
@@ -557,17 +552,17 @@ public:
 
   /**
    * Copy data from an object of type CompressedSparsityPattern,
-   * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern.
-   * Previous content of this object is lost, and the sparsity pattern is in
-   * compressed mode afterwards.
+   * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Previous
+   * content of this object is lost, and the sparsity pattern is in compressed
+   * mode afterwards.
    */
   template <typename SparsityType>
   void copy_from (const SparsityType &csp,
                   const size_type     chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   template <typename SparsityType>
   void copy_from (const SparsityType &csp,
@@ -586,8 +581,8 @@ public:
                   const size_type chunk_size);
 
   /**
-   * @deprecated This function is deprecated. Use the function
-   * without the last argument
+   * @deprecated This function is deprecated. Use the function without the
+   * last argument
    */
   template <typename number>
   void copy_from (const FullMatrix<number> &matrix,
@@ -704,8 +699,8 @@ public:
    * Determine whether the matrix uses the special convention for quadratic
    * matrices that the diagonal entries are stored first in each row.
    *
-   * @deprecated The function always returns true if the matrix is
-   * square and false if it is not.
+   * @deprecated The function always returns true if the matrix is square and
+   * false if it is not.
    */
   bool optimize_diagonal () const DEAL_II_DEPRECATED;
 
@@ -714,7 +709,8 @@ public:
    * explicitly, or if the sparsity pattern contains elements that have been
    * added through other means (implicitly) while building it. For the current
    * class, the result is true if and only if it is square because it then
-   * unconditionally stores the diagonal entries whether they have been added explicitly or not.
+   * unconditionally stores the diagonal entries whether they have been added
+   * explicitly or not.
    *
    * This function mainly serves the purpose of describing the current class
    * in cases where several kinds of sparsity patterns can be passed as
@@ -767,10 +763,10 @@ public:
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously been written by block_write() from a
-   * file. This is done using the inverse operations to the above function, so
-   * it is reasonably fast because the bitstream is not interpreted except for
-   * a few numbers up front.
+   * Read data that has previously been written by block_write() from a file.
+   * This is done using the inverse operations to the above function, so it is
+   * reasonably fast because the bitstream is not interpreted except for a few
+   * numbers up front.
    *
    * The object is resized on this operation, and all previous contents are
    * lost.
@@ -809,8 +805,10 @@ public:
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
   /**
    * Exception
    */
index 2e1a156d3178f1e782cb52483ec4417f5b501aa8..7ca89759c4cfd69c4e10288ea1ab2dc70c0106ed 100644 (file)
@@ -35,35 +35,31 @@ template <typename number> class SparseMatrix;
 
 
 /**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative, but the chosen data format is too unsuited
- * to be used for actual matrices. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative, but
+ * the chosen data format is too unsuited to be used for actual matrices. It
+ * is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
  *
  * Another viewpoint is that this class does not need up front allocation of a
  * certain amount of memory, but grows as necessary.  An extensive description
  * of sparsity patterns can be found in the documentation of the @ref Sparsity
  * module.
  *
- * This class is an example of the "dynamic" type of @ref Sparsity. It
- * is discussed in the step-27 and @ref step_22
- * "step-22" tutorial programs.
+ * This class is an example of the "dynamic" type of @ref Sparsity. It is
+ * discussed in the step-27 and @ref step_22 "step-22" tutorial programs.
  *
  * <h3>Interface</h3>
  *
  * Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
  *
  *
  * <h3>Usage</h3>
@@ -79,30 +75,28 @@ template <typename number> class SparseMatrix;
  * sp.copy_from (compressed_pattern);
  * @endcode
  *
- * See also step-11 and step-18 for usage
- * patterns of the related CompressedSparsityPattern class, and
- * step-27 of the current class.
+ * See also step-11 and step-18 for usage patterns of the related
+ * CompressedSparsityPattern class, and step-27 of the current class.
  *
  * <h3>Notes</h3>
  *
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
  *
- * This class is a variation of the CompressedSparsityPattern class.
- * Instead of using sorted vectors together with a caching algorithm
- * for storing the column indices of nonzero entries, the std::set
- * container is used. This solution might not be the fastest in all
- * situations, but seems to work much better than the
- * CompressedSparsityPattern in the context of hp-adaptivity (see for
- * example step-27), or generally when there are many
- * nonzero entries in each row of a matrix (see @ref step_22
- * "step-22").  On the other hand, a benchmark where nonzero entries
- * were randomly inserted into the sparsity pattern revealed that this
- * class is slower by a factor 4-6 in this situation. Hence, currently
- * the suggestion is to carefully analyze which of the
- * CompressedSparsityPattern classes works best in a certain
- * setting. An algorithm which performs equally well in all situations
- * still has to be found.
+ * This class is a variation of the CompressedSparsityPattern class. Instead
+ * of using sorted vectors together with a caching algorithm for storing the
+ * column indices of nonzero entries, the std::set container is used. This
+ * solution might not be the fastest in all situations, but seems to work much
+ * better than the CompressedSparsityPattern in the context of hp-adaptivity
+ * (see for example step-27), or generally when there are many nonzero entries
+ * in each row of a matrix (see @ref step_22 "step-22").  On the other hand, a
+ * benchmark where nonzero entries were randomly inserted into the sparsity
+ * pattern revealed that this class is slower by a factor 4-6 in this
+ * situation. Hence, currently the suggestion is to carefully analyze which of
+ * the CompressedSparsityPattern classes works best in a certain setting. An
+ * algorithm which performs equally well in all situations still has to be
+ * found.
  *
  *
  * @author Oliver Kayser-Herold, 2007
@@ -116,120 +110,85 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * An iterator that can be used to
-   * iterate over the elements of a single
-   * row. The result of dereferencing such
-   * an iterator is a column index.
+   * An iterator that can be used to iterate over the elements of a single
+   * row. The result of dereferencing such an iterator is a column index.
    */
   typedef std::set<size_type>::const_iterator row_iterator;
 
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   CompressedSetSparsityPattern ();
 
   /**
-   * Copy constructor. This constructor is
-   * only allowed to be called if the
-   * matrix structure to be copied is
-   * empty. This is so in order to prevent
-   * involuntary copies of objects for
-   * temporaries, which can use large
-   * amounts of computing time.  However,
-   * copy constructors are needed if yo
-   * want to use the STL data types on
-   * classes like this, e.g. to write such
-   * statements like <tt>v.push_back
-   * (CompressedSetSparsityPattern());</tt>,
-   * with @p v a vector of @p
-   * CompressedSetSparsityPattern objects.
+   * Copy constructor. This constructor is only allowed to be called if the
+   * matrix structure to be copied is empty. This is so in order to prevent
+   * involuntary copies of objects for temporaries, which can use large
+   * amounts of computing time.  However, copy constructors are needed if yo
+   * want to use the STL data types on classes like this, e.g. to write such
+   * statements like <tt>v.push_back (CompressedSetSparsityPattern());</tt>,
+   * with @p v a vector of @p CompressedSetSparsityPattern objects.
    */
   CompressedSetSparsityPattern (const CompressedSetSparsityPattern &);
 
   /**
-   * Initialize a rectangular
-   * matrix with @p m rows and
-   * @p n columns.
+   * Initialize a rectangular matrix with @p m rows and @p n columns.
    */
   CompressedSetSparsityPattern (const size_type m,
                                 const size_type n);
 
   /**
-   * Initialize a square matrix of
-   * dimension @p n.
+   * Initialize a square matrix of dimension @p n.
    */
   CompressedSetSparsityPattern (const size_type n);
 
   /**
-   * Copy operator. For this the
-   * same holds as for the copy
-   * constructor: it is declared,
-   * defined and fine to be called,
-   * but the latter only for empty
+   * Copy operator. For this the same holds as for the copy constructor: it is
+   * declared, defined and fine to be called, but the latter only for empty
    * objects.
    */
   CompressedSetSparsityPattern &operator = (const CompressedSetSparsityPattern &);
 
   /**
-   * Reallocate memory and set up
-   * data structures for a new
-   * matrix with @p m rows and
-   * @p n columns, with at most
-   * max_entries_per_row() nonzero
-   * entries per row.
+   * Reallocate memory and set up data structures for a new matrix with @p m
+   * rows and @p n columns, with at most max_entries_per_row() nonzero entries
+   * per row.
    */
   void reinit (const size_type m,
                const size_type n);
 
   /**
-   * Since this object is kept
-   * compressed at all times anway,
-   * this function does nothing,
-   * but is declared to make the
-   * interface of this class as
-   * much alike as that of the
-   * SparsityPattern class.
+   * Since this object is kept compressed at all times anway, this function
+   * does nothing, but is declared to make the interface of this class as much
+   * alike as that of the SparsityPattern class.
    */
   void compress ();
 
   /**
-   * Return whether the object is
-   * empty. It is empty if no
-   * memory is allocated, which is
-   * the same as that both
-   * dimensions are zero.
+   * Return whether the object is empty. It is empty if no memory is
+   * allocated, which is the same as that both dimensions are zero.
    */
   bool empty () const;
 
   /**
-   * Return the maximum number of
-   * entries per row. Note that
-   * this number may change as
-   * entries are added.
+   * Return the maximum number of entries per row. Note that this number may
+   * change as entries are added.
    */
   size_type max_entries_per_row () const;
 
   /**
-   * Add a nonzero entry to the
-   * matrix. If the entry already
-   * exists, nothing bad happens.
+   * Add a nonzero entry to the matrix. If the entry already exists, nothing
+   * bad happens.
    */
   void add (const size_type i,
             const size_type j);
 
   /**
-   * Add several nonzero entries to the
-   * specified row of the matrix. If the
-   * entries already exist, nothing bad
-   * happens.
+   * Add several nonzero entries to the specified row of the matrix. If the
+   * entries already exist, nothing bad happens.
    */
   template <typename ForwardIterator>
   void add_entries (const size_type row,
@@ -238,72 +197,51 @@ public:
                     const bool      indices_are_sorted = false);
 
   /**
-   * Check if a value at a certain
-   * position may be non-zero.
+   * Check if a value at a certain position may be non-zero.
    */
   bool exists (const size_type i,
                const size_type j) const;
 
   /**
-   * Make the sparsity pattern
-   * symmetric by adding the
-   * sparsity pattern of the
+   * Make the sparsity pattern symmetric by adding the sparsity pattern of the
    * transpose object.
    *
-   * This function throws an
-   * exception if the sparsity
-   * pattern does not represent a
-   * square matrix.
+   * This function throws an exception if the sparsity pattern does not
+   * represent a square matrix.
    */
   void symmetrize ();
 
   /**
-   * Print the sparsity of the
-   * matrix. The output consists of
-   * one line per row of the format
-   * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
-   * is the row number and
-   * <i>jn</i> are the allocated
-   * columns in this row.
+   * Print the sparsity of the matrix. The output consists of one line per row
+   * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+   * <i>jn</i> are the allocated columns in this row.
    */
   void print (std::ostream &out) const;
 
   /**
-   * Print the sparsity of the matrix in a
-   * format that @p gnuplot understands and
-   * which can be used to plot the sparsity
-   * pattern in a graphical way. The format
-   * consists of pairs <tt>i j</tt> of
-   * nonzero elements, each representing
-   * one entry of this matrix, one per line
-   * of the output file. Indices are
-   * counted from zero on, as usual. Since
-   * sparsity patterns are printed in the
-   * same way as matrices are displayed, we
-   * print the negative of the column
-   * index, which means that the
-   * <tt>(0,0)</tt> element is in the top
-   * left rather than in the bottom left
-   * corner.
+   * Print the sparsity of the matrix in a format that @p gnuplot understands
+   * and which can be used to plot the sparsity pattern in a graphical way.
+   * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+   * representing one entry of this matrix, one per line of the output file.
+   * Indices are counted from zero on, as usual. Since sparsity patterns are
+   * printed in the same way as matrices are displayed, we print the negative
+   * of the column index, which means that the <tt>(0,0)</tt> element is in
+   * the top left rather than in the bottom left corner.
    *
-   * Print the sparsity pattern in
-   * gnuplot by setting the data style
-   * to dots or points and use the
-   * @p plot command.
+   * Print the sparsity pattern in gnuplot by setting the data style to dots
+   * or points and use the @p plot command.
    */
   void print_gnuplot (std::ostream &out) const;
 
   /**
-   * Return number of rows of this
-   * matrix, which equals the dimension
-   * of the image space.
+   * Return number of rows of this matrix, which equals the dimension of the
+   * image space.
    */
   size_type n_rows () const;
 
   /**
-   * Return number of columns of this
-   * matrix, which equals the dimension
-   * of the range space.
+   * Return number of columns of this matrix, which equals the dimension of
+   * the range space.
    */
   size_type n_cols () const;
 
@@ -313,10 +251,8 @@ public:
   size_type row_length (const size_type row) const;
 
   /**
-   * Return an iterator that can loop over
-   * all entries in the given
-   * row. Dereferencing the iterator yields
-   * a column index.
+   * Return an iterator that can loop over all entries in the given row.
+   * Dereferencing the iterator yields a column index.
    */
   row_iterator row_begin (const size_type row) const;
 
@@ -327,35 +263,26 @@ public:
 
 
   /**
-   * Compute the bandwidth of the matrix
-   * represented by this structure. The
-   * bandwidth is the maximum of
-   * $|i-j|$ for which the index pair
-   * $(i,j)$ represents a nonzero entry
-   * of the matrix.
+   * Compute the bandwidth of the matrix represented by this structure. The
+   * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
+   * represents a nonzero entry of the matrix.
    */
   size_type bandwidth () const;
 
   /**
-   * Return the number of nonzero elements
-   * allocated through this sparsity
+   * Return the number of nonzero elements allocated through this sparsity
    * pattern.
    */
   size_type n_nonzero_elements () const;
 
   /**
-   * Return whether this object stores only
-   * those entries that have been added
-   * explicitly, or if the sparsity pattern
-   * contains elements that have been added
-   * through other means (implicitly) while
-   * building it. For the current class,
-   * the result is always true.
+   * Return whether this object stores only those entries that have been added
+   * explicitly, or if the sparsity pattern contains elements that have been
+   * added through other means (implicitly) while building it. For the current
+   * class, the result is always true.
    *
-   * This function mainly serves the
-   * purpose of describing the current
-   * class in cases where several kinds of
-   * sparsity patterns can be passed as
+   * This function mainly serves the purpose of describing the current class
+   * in cases where several kinds of sparsity patterns can be passed as
    * template arguments.
    */
   static
@@ -363,22 +290,18 @@ public:
 
 private:
   /**
-   * Number of rows that this sparsity
-   * structure shall represent.
+   * Number of rows that this sparsity structure shall represent.
    */
   size_type rows;
 
   /**
-   * Number of columns that this sparsity
-   * structure shall represent.
+   * Number of columns that this sparsity structure shall represent.
    */
   size_type cols;
 
   /**
-   * For each row of the matrix, store the
-   * allocated non-zero entries as a
-   * std::set of column indices. For a
-   * discussion of storage schemes see the
+   * For each row of the matrix, store the allocated non-zero entries as a
+   * std::set of column indices. For a discussion of storage schemes see the
    * CompressedSparsityPattern::Line class.
    */
   struct Line
@@ -391,14 +314,12 @@ private:
     Line ();
 
     /**
-     * Add the given column number to
-     * this line.
+     * Add the given column number to this line.
      */
     void add (const size_type col_num);
 
     /**
-     * Add the columns specified by the
-     * iterator range to this line.
+     * Add the columns specified by the iterator range to this line.
      */
     template <typename ForwardIterator>
     void add_entries (ForwardIterator begin,
@@ -407,9 +328,7 @@ private:
 
 
   /**
-   * Actual data: store for each
-   * row the set of nonzero
-   * entries.
+   * Actual data: store for each row the set of nonzero entries.
    */
   std::vector<Line> lines;
 };
index 35cde6b568e9fb78c75805a2632c93799b72aa29..56d19f8a7226a6dd8bd5793db159e8bdecd1ddc3 100644 (file)
@@ -38,18 +38,16 @@ template <typename number> class SparseMatrix;
 
 
 /**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative. The chosen data format is too unsuited
- * to be used for actual matrices, though. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative. The
+ * chosen data format is too unsuited to be used for actual matrices, though.
+ * It is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
  *
  * Another viewpoint is that this class does not need up front allocation of a
  * certain amount of memory, but grows as necessary.  An extensive description
@@ -61,10 +59,9 @@ template <typename number> class SparseMatrix;
  * <h3>Interface</h3>
  *
  * Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
  *
  *
  * <h3>Usage</h3>
@@ -83,8 +80,9 @@ template <typename number> class SparseMatrix;
  *
  * <h3>Notes</h3>
  *
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
  *
  * @author Timo Heister, 2008
  */
@@ -218,13 +216,13 @@ public:
 
   /**
    * Print the sparsity of the matrix in a format that @p gnuplot understands
-   * and which can be used to plot the sparsity pattern in a graphical
-   * way. The format consists of pairs <tt>i j</tt> of nonzero elements, each
-   * representing one entry of this matrix, one per line of the output
-   * file. Indices are counted from zero on, as usual. Since sparsity patterns
-   * are printed in the same way as matrices are displayed, we print the
-   * negative of the column index, which means that the <tt>(0,0)</tt> element
-   * is in the top left rather than in the bottom left corner.
+   * and which can be used to plot the sparsity pattern in a graphical way.
+   * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+   * representing one entry of this matrix, one per line of the output file.
+   * Indices are counted from zero on, as usual. Since sparsity patterns are
+   * printed in the same way as matrices are displayed, we print the negative
+   * of the column index, which means that the <tt>(0,0)</tt> element is in
+   * the top left rather than in the bottom left corner.
    *
    * Print the sparsity pattern in gnuplot by setting the data style to dots
    * or points and use the @p plot command.
@@ -257,8 +255,8 @@ public:
                            const size_type index) const;
 
   /**
-   * Return an iterator that can loop over all entries in the given
-   * row. Dereferencing the iterator yields a column index.
+   * Return an iterator that can loop over all entries in the given row.
+   * Dereferencing the iterator yields a column index.
    */
   row_iterator row_begin (const size_type row) const;
 
index 52a149878ebd5c472e4c545b81cace6f90b8f63b..59f1586dc91c4e8b879fb0bea2bb2034686eabeb 100644 (file)
@@ -37,18 +37,16 @@ template <typename number> class SparseMatrix;
 
 
 /**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative, but the chosen data format is too unsuited
- * to be used for actual matrices. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative, but
+ * the chosen data format is too unsuited to be used for actual matrices. It
+ * is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
  *
  * Another viewpoint is that this class does not need up front allocation of a
  * certain amount of memory, but grows as necessary.  An extensive description
@@ -60,10 +58,9 @@ template <typename number> class SparseMatrix;
  * <h3>Interface</h3>
  *
  * Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
  *
  *
  * <h3>Usage</h3>
@@ -79,13 +76,13 @@ template <typename number> class SparseMatrix;
  * sp.copy_from (compressed_pattern);
  * @endcode
  *
- * See also step-11 and step-18 for usage
- * patterns.
+ * See also step-11 and step-18 for usage patterns.
  *
  * <h3>Notes</h3>
  *
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
  *
  * @author Wolfgang Bangerth, 2001
  */
@@ -98,119 +95,84 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * An iterator that can be used to
-   * iterate over the elements of a single
-   * row. The result of dereferencing such
-   * an iterator is a column index.
+   * An iterator that can be used to iterate over the elements of a single
+   * row. The result of dereferencing such an iterator is a column index.
    */
   typedef std::vector<size_type>::const_iterator row_iterator;
 
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   CompressedSparsityPattern ();
 
   /**
-   * Copy constructor. This constructor is
-   * only allowed to be called if the
-   * matrix structure to be copied is
-   * empty. This is so in order to prevent
-   * involuntary copies of objects for
-   * temporaries, which can use large
-   * amounts of computing time.  However,
-   * copy constructors are needed if yo
-   * want to use the STL data types on
-   * classes like this, e.g. to write such
-   * statements like <tt>v.push_back
-   * (CompressedSparsityPattern());</tt>,
-   * with @p v a vector of @p
-   * CompressedSparsityPattern objects.
+   * Copy constructor. This constructor is only allowed to be called if the
+   * matrix structure to be copied is empty. This is so in order to prevent
+   * involuntary copies of objects for temporaries, which can use large
+   * amounts of computing time.  However, copy constructors are needed if yo
+   * want to use the STL data types on classes like this, e.g. to write such
+   * statements like <tt>v.push_back (CompressedSparsityPattern());</tt>, with
+   * @p v a vector of @p CompressedSparsityPattern objects.
    */
   CompressedSparsityPattern (const CompressedSparsityPattern &);
 
   /**
-   * Initialize a rectangular
-   * matrix with @p m rows and
-   * @p n columns.
+   * Initialize a rectangular matrix with @p m rows and @p n columns.
    */
   CompressedSparsityPattern (const size_type m,
                              const size_type n);
 
   /**
-   * Initialize a square matrix of
-   * dimension @p n.
+   * Initialize a square matrix of dimension @p n.
    */
   CompressedSparsityPattern (const size_type n);
 
   /**
-   * Copy operator. For this the
-   * same holds as for the copy
-   * constructor: it is declared,
-   * defined and fine to be called,
-   * but the latter only for empty
+   * Copy operator. For this the same holds as for the copy constructor: it is
+   * declared, defined and fine to be called, but the latter only for empty
    * objects.
    */
   CompressedSparsityPattern &operator = (const CompressedSparsityPattern &);
 
   /**
-   * Reallocate memory and set up
-   * data structures for a new
-   * matrix with @p m rows and
-   * @p n columns, with at most
-   * max_entries_per_row() nonzero
-   * entries per row.
+   * Reallocate memory and set up data structures for a new matrix with @p m
+   * rows and @p n columns, with at most max_entries_per_row() nonzero entries
+   * per row.
    */
   void reinit (const size_type m,
                const size_type n);
 
   /**
-   * Since this object is kept
-   * compressed at all times anway,
-   * this function does nothing,
-   * but is declared to make the
-   * interface of this class as
-   * much alike as that of the
-   * SparsityPattern class.
+   * Since this object is kept compressed at all times anway, this function
+   * does nothing, but is declared to make the interface of this class as much
+   * alike as that of the SparsityPattern class.
    */
   void compress ();
 
   /**
-   * Return whether the object is
-   * empty. It is empty if no
-   * memory is allocated, which is
-   * the same as that both
-   * dimensions are zero.
+   * Return whether the object is empty. It is empty if no memory is
+   * allocated, which is the same as that both dimensions are zero.
    */
   bool empty () const;
 
   /**
-   * Return the maximum number of
-   * entries per row. Note that
-   * this number may change as
-   * entries are added.
+   * Return the maximum number of entries per row. Note that this number may
+   * change as entries are added.
    */
   size_type max_entries_per_row () const;
 
   /**
-   * Add a nonzero entry to the
-   * matrix. If the entry already
-   * exists, nothing bad happens.
+   * Add a nonzero entry to the matrix. If the entry already exists, nothing
+   * bad happens.
    */
   void add (const size_type i,
             const size_type j);
 
   /**
-   * Add several nonzero entries to the
-   * specified row of the matrix. If the
-   * entries already exist, nothing bad
-   * happens.
+   * Add several nonzero entries to the specified row of the matrix. If the
+   * entries already exist, nothing bad happens.
    */
   template <typename ForwardIterator>
   void add_entries (const size_type row,
@@ -219,72 +181,51 @@ public:
                     const bool      indices_are_unique_and_sorted = false);
 
   /**
-   * Check if a value at a certain
-   * position may be non-zero.
+   * Check if a value at a certain position may be non-zero.
    */
   bool exists (const size_type i,
                const size_type j) const;
 
   /**
-   * Make the sparsity pattern
-   * symmetric by adding the
-   * sparsity pattern of the
+   * Make the sparsity pattern symmetric by adding the sparsity pattern of the
    * transpose object.
    *
-   * This function throws an
-   * exception if the sparsity
-   * pattern does not represent a
-   * square matrix.
+   * This function throws an exception if the sparsity pattern does not
+   * represent a square matrix.
    */
   void symmetrize ();
 
   /**
-   * Print the sparsity of the
-   * matrix. The output consists of
-   * one line per row of the format
-   * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
-   * is the row number and
-   * <i>jn</i> are the allocated
-   * columns in this row.
+   * Print the sparsity of the matrix. The output consists of one line per row
+   * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+   * <i>jn</i> are the allocated columns in this row.
    */
   void print (std::ostream &out) const;
 
   /**
-   * Print the sparsity of the matrix in a
-   * format that @p gnuplot understands and
-   * which can be used to plot the sparsity
-   * pattern in a graphical way. The format
-   * consists of pairs <tt>i j</tt> of
-   * nonzero elements, each representing
-   * one entry of this matrix, one per line
-   * of the output file. Indices are
-   * counted from zero on, as usual. Since
-   * sparsity patterns are printed in the
-   * same way as matrices are displayed, we
-   * print the negative of the column
-   * index, which means that the
-   * <tt>(0,0)</tt> element is in the top
-   * left rather than in the bottom left
-   * corner.
+   * Print the sparsity of the matrix in a format that @p gnuplot understands
+   * and which can be used to plot the sparsity pattern in a graphical way.
+   * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+   * representing one entry of this matrix, one per line of the output file.
+   * Indices are counted from zero on, as usual. Since sparsity patterns are
+   * printed in the same way as matrices are displayed, we print the negative
+   * of the column index, which means that the <tt>(0,0)</tt> element is in
+   * the top left rather than in the bottom left corner.
    *
-   * Print the sparsity pattern in
-   * gnuplot by setting the data style
-   * to dots or points and use the
-   * @p plot command.
+   * Print the sparsity pattern in gnuplot by setting the data style to dots
+   * or points and use the @p plot command.
    */
   void print_gnuplot (std::ostream &out) const;
 
   /**
-   * Return number of rows of this
-   * matrix, which equals the dimension
-   * of the image space.
+   * Return number of rows of this matrix, which equals the dimension of the
+   * image space.
    */
   size_type n_rows () const;
 
   /**
-   * Return number of columns of this
-   * matrix, which equals the dimension
-   * of the range space.
+   * Return number of columns of this matrix, which equals the dimension of
+   * the range space.
    */
   size_type n_cols () const;
 
@@ -294,18 +235,15 @@ public:
   size_type row_length (const size_type row) const;
 
   /**
-   * Access to column number field.
-   * Return the column number of
-   * the @p indexth entry in @p row.
+   * Access to column number field. Return the column number of the @p indexth
+   * entry in @p row.
    */
   size_type column_number (const size_type row,
                            const size_type index) const;
 
   /**
-   * Return an iterator that can loop over
-   * all entries in the given
-   * row. Dereferencing the iterator yields
-   * a column index.
+   * Return an iterator that can loop over all entries in the given row.
+   * Dereferencing the iterator yields a column index.
    */
   row_iterator row_begin (const size_type row) const;
 
@@ -315,35 +253,26 @@ public:
   row_iterator row_end (const size_type row) const;
 
   /**
-   * Compute the bandwidth of the matrix
-   * represented by this structure. The
-   * bandwidth is the maximum of
-   * $|i-j|$ for which the index pair
-   * $(i,j)$ represents a nonzero entry
-   * of the matrix.
+   * Compute the bandwidth of the matrix represented by this structure. The
+   * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
+   * represents a nonzero entry of the matrix.
    */
   size_type bandwidth () const;
 
   /**
-   * Return the number of nonzero elements
-   * allocated through this sparsity
+   * Return the number of nonzero elements allocated through this sparsity
    * pattern.
    */
   size_type n_nonzero_elements () const;
 
   /**
-   * Return whether this object stores only
-   * those entries that have been added
-   * explicitly, or if the sparsity pattern
-   * contains elements that have been added
-   * through other means (implicitly) while
-   * building it. For the current class,
-   * the result is always true.
+   * Return whether this object stores only those entries that have been added
+   * explicitly, or if the sparsity pattern contains elements that have been
+   * added through other means (implicitly) while building it. For the current
+   * class, the result is always true.
    *
-   * This function mainly serves the
-   * purpose of describing the current
-   * class in cases where several kinds of
-   * sparsity patterns can be passed as
+   * This function mainly serves the purpose of describing the current class
+   * in cases where several kinds of sparsity patterns can be passed as
    * template arguments.
    */
   static
@@ -351,73 +280,46 @@ public:
 
 private:
   /**
-   * Number of rows that this sparsity
-   * structure shall represent.
+   * Number of rows that this sparsity structure shall represent.
    */
   size_type rows;
 
   /**
-   * Number of columns that this sparsity
-   * structure shall represent.
+   * Number of columns that this sparsity structure shall represent.
    */
   size_type cols;
 
   /**
-   * Store some data for each row
-   * describing which entries of this row
-   * are nonzero. Data is organized as
-   * follows: if an entry is added to a
-   * row, it is first added to the #cache
-   * variable, irrespective of whether an
-   * entry with same column number has
-   * already been added. Only if the cache
-   * is full do we flush it by removing
-   * duplicates, removing entries that are
-   * already stored in the @p entries
-   * array, sorting everything, and merging
-   * the two arrays.
+   * Store some data for each row describing which entries of this row are
+   * nonzero. Data is organized as follows: if an entry is added to a row, it
+   * is first added to the #cache variable, irrespective of whether an entry
+   * with same column number has already been added. Only if the cache is full
+   * do we flush it by removing duplicates, removing entries that are already
+   * stored in the @p entries array, sorting everything, and merging the two
+   * arrays.
    *
-   * The reasoning behind this scheme is
-   * that memory allocation is expensive,
-   * and we only want to do it when really
-   * necessary. Previously (in deal.II
-   * versions up to 5.0), we used to store
-   * the column indices inside a std::set,
-   * but this would allocate 20 bytes each
-   * time we added an entry. (A std::set
-   * based class has later been revived in
-   * form of the
-   * CompressedSetSparsityPattern class, as
-   * this turned out to be more efficient
-   * for hp finite element programs such as
-   * step-27). Using the
-   * present scheme, we only need to
-   * allocate memory once for every 8 added
-   * entries, and we waste a lot less
-   * memory by not using a balanced tree
-   * for storing column indices.
+   * The reasoning behind this scheme is that memory allocation is expensive,
+   * and we only want to do it when really necessary. Previously (in deal.II
+   * versions up to 5.0), we used to store the column indices inside a
+   * std::set, but this would allocate 20 bytes each time we added an entry.
+   * (A std::set based class has later been revived in form of the
+   * CompressedSetSparsityPattern class, as this turned out to be more
+   * efficient for hp finite element programs such as step-27). Using the
+   * present scheme, we only need to allocate memory once for every 8 added
+   * entries, and we waste a lot less memory by not using a balanced tree for
+   * storing column indices.
    *
-   * Since some functions that are @p const
-   * need to access the data of this
-   * object, but need to flush caches
-   * before, the flush_cache() function is
-   * marked const, and the data members are
-   * marked @p mutable.
+   * Since some functions that are @p const need to access the data of this
+   * object, but need to flush caches before, the flush_cache() function is
+   * marked const, and the data members are marked @p mutable.
    *
-   * A small testseries about the size of
-   * the cache showed that the run time of
-   * a small program just testing the
-   * compressed sparsity pattern element
-   * insertion routine ran for 3.6 seconds
-   * with a cache size of 8, and 4.2
-   * seconds with a cache size of 16. We
-   * deem even smaller cache sizes
-   * undesirable, since they lead to more
-   * memory allocations, while larger cache
-   * sizes lead to waste of memory. The
-   * original version of this class, with
-   * one std::set per row took 8.2 seconds
-   * on the same program.
+   * A small testseries about the size of the cache showed that the run time
+   * of a small program just testing the compressed sparsity pattern element
+   * insertion routine ran for 3.6 seconds with a cache size of 8, and 4.2
+   * seconds with a cache size of 16. We deem even smaller cache sizes
+   * undesirable, since they lead to more memory allocations, while larger
+   * cache sizes lead to waste of memory. The original version of this class,
+   * with one std::set per row took 8.2 seconds on the same program.
    */
   struct Line
   {
@@ -429,16 +331,13 @@ private:
 
   public:
     /**
-     * Storage for the column indices of
-     * this row, unless they are still in
-     * the cache. This array is always
-     * kept sorted.
+     * Storage for the column indices of this row, unless they are still in
+     * the cache. This array is always kept sorted.
      */
     mutable std::vector<size_type> entries;
 
     /**
-     * Cache of entries that have not yet
-     * been written to #entries;
+     * Cache of entries that have not yet been written to #entries;
      */
     mutable size_type cache[cache_size];
 
@@ -453,14 +352,12 @@ private:
     Line ();
 
     /**
-     * Add the given column number to
-     * this line.
+     * Add the given column number to this line.
      */
     void add (const size_type col_num);
 
     /**
-     * Add the columns specified by the
-     * iterator range to this line.
+     * Add the columns specified by the iterator range to this line.
      */
     template <typename ForwardIterator>
     void add_entries (ForwardIterator begin,
@@ -468,17 +365,14 @@ private:
                       const bool indices_are_sorted);
 
     /**
-     * Flush the cache my merging it with
-     * the #entries array.
+     * Flush the cache my merging it with the #entries array.
      */
     void flush_cache () const;
   };
 
 
   /**
-   * Actual data: store for each
-   * row the set of nonzero
-   * entries.
+   * Actual data: store for each row the set of nonzero entries.
    */
   std::vector<Line> lines;
 };
index 305d5d72b190d6781141a9b3e19cc875b7f396cf..15a773b5ccbb716a028cb6e79794d5f975c57aee 100644 (file)
@@ -73,51 +73,48 @@ namespace internals
  * constraints is extensively described in the @ref constraints module. The
  * class is meant to deal with a limited number of constraints relative to the
  * total number of degrees of freedom, for example a few per cent up to maybe
- * 30 per cent; and with a linear combination of <i>M</i> other degrees of freedom
- * where <i>M</i> is also relatively small (no larger than at most around the
- * average number of entries per row of a linear system). It is <em>not</em>
- * meant to describe full rank linear systems.
+ * 30 per cent; and with a linear combination of <i>M</i> other degrees of
+ * freedom where <i>M</i> is also relatively small (no larger than at most
+ * around the average number of entries per row of a linear system). It is
+ * <em>not</em> meant to describe full rank linear systems.
  *
  * The algorithms used in the implementation of this class are described in
  * some detail in the @ref hp_paper "hp paper". There is also a significant
- * amount of documentation on how to use this class in the
- * @ref constraints module.
+ * amount of documentation on how to use this class in the @ref constraints
+ * module.
  *
  *
  * <h3>Description of constraints</h3>
  *
  * Each "line" in objects of this class corresponds to one constrained degree
- * of freedom, with the number of the line being <i>i</i>, entered by
- * using add_line() or add_lines(). The entries in
- * this line are pairs of the form
+ * of freedom, with the number of the line being <i>i</i>, entered by using
+ * add_line() or add_lines(). The entries in this line are pairs of the form
  * (<i>j</i>,<i>a<sub>ij</sub></i>), which are added by add_entry() or
- * add_entries(). The organization is essentially a
- * SparsityPattern, but with only a few lines containing nonzero
- * elements, and  therefore no data wasted on the others. For each
- * line, which has been added by the mechanism above, an elimination
- * of the constrained degree of freedom of the form
+ * add_entries(). The organization is essentially a SparsityPattern, but with
+ * only a few lines containing nonzero elements, and  therefore no data wasted
+ * on the others. For each line, which has been added by the mechanism above,
+ * an elimination of the constrained degree of freedom of the form
  * @f[
  *  x_i = \sum_j a_{ij} x_j + b_i
  * @f]
  * is performed, where <i>b<sub>i</sub></i> is optional and set by
- * set_inhomogeneity(). Thus, if a constraint is formulated for
- * instance as a zero mean value of several degrees of freedom, one of
- * the degrees has to be chosen to be eliminated.
+ * set_inhomogeneity(). Thus, if a constraint is formulated for instance as a
+ * zero mean value of several degrees of freedom, one of the degrees has to be
+ * chosen to be eliminated.
  *
- * Note that the constraints are linear
- * in the <i>x<sub>i</sub></i>, and that there might be a constant (non-homogeneous) term in
- * the constraint. This is exactly the form we need for hanging node
- * constraints, where we need to constrain one degree of freedom in terms of
- * others. There are other conditions of this form possible, for example for
- * implementing mean value conditions as is done in the step-11
- * tutorial program. The name of the class stems from the fact that these
- * constraints can be represented in matrix form as <b>X</b> <i>x</i> = <i>b</i>, and this object
- * then describes the matrix <b>X</b> (and the vector <i>b</i>;
- * originally, the ConstraintMatrix class was only meant to handle homogenous
- * constraints where <i>b</i>=0, thus the name). The most frequent way to
- * create/fill objects of this type is using the
- * DoFTools::make_hanging_node_constraints() function. The use of these
- * objects is first explained in step-6.
+ * Note that the constraints are linear in the <i>x<sub>i</sub></i>, and that
+ * there might be a constant (non-homogeneous) term in the constraint. This is
+ * exactly the form we need for hanging node constraints, where we need to
+ * constrain one degree of freedom in terms of others. There are other
+ * conditions of this form possible, for example for implementing mean value
+ * conditions as is done in the step-11 tutorial program. The name of the
+ * class stems from the fact that these constraints can be represented in
+ * matrix form as <b>X</b> <i>x</i> = <i>b</i>, and this object then describes
+ * the matrix <b>X</b> (and the vector <i>b</i>; originally, the
+ * ConstraintMatrix class was only meant to handle homogenous constraints
+ * where <i>b</i>=0, thus the name). The most frequent way to create/fill
+ * objects of this type is using the DoFTools::make_hanging_node_constraints()
+ * function. The use of these objects is first explained in step-6.
  *
  * Objects of the present type are organized in lines (rows), but only those
  * lines are stored where constraints are present. New constraints are added
@@ -128,14 +125,13 @@ namespace internals
  * been added, you need to call close(), which compresses the storage format
  * and sorts the entries.
  *
- * @note Many of the algorithms this class implements are discussed in
- * the @ref hp_paper . The algorithms are also related to those shown
- * in <i>M. S. Shephard: Linear multipoint constraints applied via
- * transformation as part of a direct stiffness assembly process. Int. J.
- * Numer. Meth. Engrg., vol. 20 (1984), pp. 2107-2112.</i>, with the
- * difference that the algorithms shown there completely eliminated
- * constrained degrees of freedom, whereas we usually keep them as part
- * of the linear system.
+ * @note Many of the algorithms this class implements are discussed in the
+ * @ref hp_paper . The algorithms are also related to those shown in <i>M. S.
+ * Shephard: Linear multipoint constraints applied via transformation as part
+ * of a direct stiffness assembly process. Int. J. Numer. Meth. Engrg., vol.
+ * 20 (1984), pp. 2107-2112.</i>, with the difference that the algorithms
+ * shown there completely eliminated constrained degrees of freedom, whereas
+ * we usually keep them as part of the linear system.
  *
  * @ingroup dofs
  * @ingroup constraints
@@ -180,10 +176,9 @@ public:
   /**
    * Constructor. The supplied IndexSet defines which indices might be
    * constrained inside this ConstraintMatrix. In a calculation with a
-   * parallel::distributed::DoFHandler one should use
-   * locally_relevant_dofs. The IndexSet allows the ConstraintMatrix to save
-   * memory. Otherwise internal data structures for all possible indices will
-   * be created.
+   * parallel::distributed::DoFHandler one should use locally_relevant_dofs.
+   * The IndexSet allows the ConstraintMatrix to save memory. Otherwise
+   * internal data structures for all possible indices will be created.
    */
   ConstraintMatrix (const IndexSet &local_constraints = IndexSet());
 
@@ -193,10 +188,10 @@ public:
   ConstraintMatrix (const ConstraintMatrix &constraint_matrix);
 
   /**
-   * clear() the ConstraintMatrix object and supply an IndexSet with lines that
-   * may be constrained. This function is only relevant in the distributed
-   * case to supply a different IndexSet. Otherwise this routine is equivalent
-   * to calling clear(). See the constructor for details.
+   * clear() the ConstraintMatrix object and supply an IndexSet with lines
+   * that may be constrained. This function is only relevant in the
+   * distributed case to supply a different IndexSet. Otherwise this routine
+   * is equivalent to calling clear(). See the constructor for details.
    */
   void reinit (const IndexSet &local_constraints = IndexSet());
 
@@ -256,11 +251,10 @@ public:
    * This function essentially exists to allow adding several constraints of
    * the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
    * <i>i</i> for which these constraints should be added are given by the
-   * argument of this function. On the other hand, just as if the
-   * single-argument add_line() function were called repeatedly, the
-   * constraints can later be modified to include linear dependencies using
-   * the add_entry() function as well as inhomogeneities using
-   * set_inhomogeneity().
+   * argument of this function. On the other hand, just as if the single-
+   * argument add_line() function were called repeatedly, the constraints can
+   * later be modified to include linear dependencies using the add_entry()
+   * function as well as inhomogeneities using set_inhomogeneity().
    */
   void add_lines (const std::vector<bool> &lines);
 
@@ -271,11 +265,10 @@ public:
    * This function essentially exists to allow adding several constraints of
    * the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
    * <i>i</i> for which these constraints should be added are given by the
-   * argument of this function. On the other hand, just as if the
-   * single-argument add_line() function were called repeatedly, the
-   * constraints can later be modified to include linear dependencies using
-   * the add_entry() function as well as inhomogeneities using
-   * set_inhomogeneity().
+   * argument of this function. On the other hand, just as if the single-
+   * argument add_line() function were called repeatedly, the constraints can
+   * later be modified to include linear dependencies using the add_entry()
+   * function as well as inhomogeneities using set_inhomogeneity().
    */
   void add_lines (const std::set<size_type> &lines);
 
@@ -286,19 +279,18 @@ public:
    * This function essentially exists to allow adding several constraints of
    * the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
    * <i>i</i> for which these constraints should be added are given by the
-   * argument of this function. On the other hand, just as if the
-   * single-argument add_line() function were called repeatedly, the
-   * constraints can later be modified to include linear dependencies using
-   * the add_entry() function as well as inhomogeneities using
-   * set_inhomogeneity().
+   * argument of this function. On the other hand, just as if the single-
+   * argument add_line() function were called repeatedly, the constraints can
+   * later be modified to include linear dependencies using the add_entry()
+   * function as well as inhomogeneities using set_inhomogeneity().
    */
   void add_lines (const IndexSet &lines);
 
   /**
    * Add an entry to a given line. The list of lines is searched from the back
    * to the front, so clever programming would add a new line (which is pushed
-   * to the back) and immediately afterwards fill the entries of that
-   * line. This way, no expensive searching is needed.
+   * to the back) and immediately afterwards fill the entries of that line.
+   * This way, no expensive searching is needed.
    *
    * If an entry with the same indices as the one this function call denotes
    * already exists, then this function simply returns provided that the value
@@ -320,7 +312,7 @@ public:
   /**
    * Set an imhomogeneity to the constraint line <i>i</i>, according to the
    * discussion in the general class description.
-  *
+   *
    * @note the line needs to be added with one of the add_line() calls first.
    */
   void set_inhomogeneity (const size_type line,
@@ -352,17 +344,17 @@ public:
    * Merge the constraints represented by the object given as argument into
    * the constraints represented by this object. Both objects may or may not
    * be closed (by having their function close() called before). If this
-   * object was closed before, then it will be closed afterwards as
-   * well. Note, however, that if the other argument is closed, then merging
-   * may be significantly faster.
+   * object was closed before, then it will be closed afterwards as well.
+   * Note, however, that if the other argument is closed, then merging may be
+   * significantly faster.
    *
    * Using the default value of the second arguments, the constraints in each
    * of the two objects (the old one represented by this object and the
    * argument) may not refer to the same degree of freedom, i.e. a degree of
    * freedom that is constrained in one object may not be constrained in the
-   * second. If this is nevertheless the case, an exception is
-   * thrown. However, this behavior can be changed by providing a different
-   * value for the second argument.
+   * second. If this is nevertheless the case, an exception is thrown.
+   * However, this behavior can be changed by providing a different value for
+   * the second argument.
    */
   void merge (const ConstraintMatrix &other_constraints,
               const MergeConflictBehavior merge_conflict_behavior = no_conflicts_allowed);
@@ -438,8 +430,8 @@ public:
                                  const size_type index2) const;
 
   /**
-   * Return the maximum number of other dofs that one dof is constrained
-   * to. For example, in 2d a hanging node is constrained only to its two
+   * Return the maximum number of other dofs that one dof is constrained to.
+   * For example, in 2d a hanging node is constrained only to its two
    * neighbors, so the returned value would be 2. However, for higher order
    * elements and/or higher dimensions, or other types of constraints, this
    * number is no more obvious.
@@ -450,8 +442,8 @@ public:
   size_type max_constraint_indirections () const;
 
   /**
-   * Returns <tt>true</tt> in case the dof is constrained and there is a
-   * non-trivial inhomogeneous valeus set to the dof.
+   * Returns <tt>true</tt> in case the dof is constrained and there is a non-
+   * trivial inhomogeneous valeus set to the dof.
    */
   bool is_inhomogeneously_constrained (const size_type index) const;
 
@@ -618,9 +610,9 @@ public:
    *
    * The constraint matrix object must be closed to call this function.
    *
-   * @deprecated The functions converting an uncondensed matrix into
-   * its condensed form are deprecated. Use the functions doing the
-   * in-place condensation leaving the size of the linear system unchanged.
+   * @deprecated The functions converting an uncondensed matrix into its
+   * condensed form are deprecated. Use the functions doing the in-place
+   * condensation leaving the size of the linear system unchanged.
    */
   template<typename number>
   void condense (const SparseMatrix<number> &uncondensed,
@@ -645,9 +637,8 @@ public:
    * Vector<float>, Vector<double>, BlockVector<tt><...></tt>, a PETSc or
    * Trilinos vector wrapper class, or any other type having the same
    * interface. Note that this function does not take any inhomogeneity into
-   * account and throws an exception in case there are any
-   * inhomogeneities. Use the function using both a matrix and vector for that
-   * case.
+   * account and throws an exception in case there are any inhomogeneities.
+   * Use the function using both a matrix and vector for that case.
    *
    * @note This function does not work for MPI vectors. Use condense() with
    * two vector arguments instead.
@@ -674,9 +665,9 @@ public:
    *
    * The constraint matrix object must be closed to call this function.
    *
-   * @deprecated The functions converting an uncondensed matrix into
-   * its condensed form are deprecated. Use the functions doing the
-   * in-place condensation leaving the size of the linear system unchanged.
+   * @deprecated The functions converting an uncondensed matrix into its
+   * condensed form are deprecated. Use the functions doing the in-place
+   * condensation leaving the size of the linear system unchanged.
    */
   template<typename number, class VectorType>
   void condense (const SparseMatrix<number> &uncondensed_matrix,
@@ -749,11 +740,11 @@ public:
    *
    * @note This function in itself is thread-safe, i.e., it works properly
    * also when several threads call it simultaneously. However, the function
-   * call is only thread-safe if the underlying global vector allows
-   * for simultaneous access and the access is not to rows with the same
-   * global index at the same time. This needs to be made sure from the
-   * caller's site. There is no locking mechanism inside this method to
-   * prevent data races.
+   * call is only thread-safe if the underlying global vector allows for
+   * simultaneous access and the access is not to rows with the same global
+   * index at the same time. This needs to be made sure from the caller's
+   * site. There is no locking mechanism inside this method to prevent data
+   * races.
    */
   template <class InVector, class OutVector>
   void
@@ -798,11 +789,11 @@ public:
    *
    * @note This function in itself is thread-safe, i.e., it works properly
    * also when several threads call it simultaneously. However, the function
-   * call is only thread-safe if the underlying global vector allows
-   * for simultaneous access and the access is not to rows with the same
-   * global index at the same time. This needs to be made sure from the
-   * caller's site. There is no locking mechanism inside this method to
-   * prevent data races.
+   * call is only thread-safe if the underlying global vector allows for
+   * simultaneous access and the access is not to rows with the same global
+   * index at the same time. This needs to be made sure from the caller's
+   * site. There is no locking mechanism inside this method to prevent data
+   * races.
    */
   template <typename VectorType>
   void
@@ -842,11 +833,11 @@ public:
    *
    * @note This function in itself is thread-safe, i.e., it works properly
    * also when several threads call it simultaneously. However, the function
-   * call is only thread-safe if the underlying global vector allows
-   * for simultaneous access and the access is not to rows with the same
-   * global index at the same time. This needs to be made sure from the
-   * caller's site. There is no locking mechanism inside this method to
-   * prevent data races.
+   * call is only thread-safe if the underlying global vector allows for
+   * simultaneous access and the access is not to rows with the same global
+   * index at the same time. This needs to be made sure from the caller's
+   * site. There is no locking mechanism inside this method to prevent data
+   * races.
    */
   template <typename ForwardIteratorVec, typename ForwardIteratorInd,
             class VectorType>
@@ -878,32 +869,30 @@ public:
    * corresponding to constrained nodes. Thus, if a degree of freedom in @p
    * local_dof_indices is constrained, we distribute the corresponding entries
    * in the matrix, but also add the absolute value of the diagonal entry of
-   * the local matrix to the corresponding entry in the global
-   * matrix. Assuming the discretized operator is positive definite,
-   * this guarantees that the diagonal entry is always
-   * non-zero, positive, and of the same order of magnitude as the other
-   * entries of the matrix. On the other hand, when solving a source
-   * problem $Au=f$ the exact value of the diagonal element is not
-   * important, since the value of
-   * the respective degree of freedom will be overwritten by the distribute()
-   * call later on anyway.
-   *
-   * @note The procedure described above adds an unforeseeable number
-   * of artificial eigenvalues to the spectrum of the
-   * matrix. Therefore, it is recommended to use the equivalent
-   * function with two local index vectors in such a case.
-   *
-   * By using this function to distribute local contributions to the
-   * global object, one saves the call to the condense function after the
-   * vectors and matrices are fully assembled.
+   * the local matrix to the corresponding entry in the global matrix.
+   * Assuming the discretized operator is positive definite, this guarantees
+   * that the diagonal entry is always non-zero, positive, and of the same
+   * order of magnitude as the other entries of the matrix. On the other hand,
+   * when solving a source problem $Au=f$ the exact value of the diagonal
+   * element is not important, since the value of the respective degree of
+   * freedom will be overwritten by the distribute() call later on anyway.
+   *
+   * @note The procedure described above adds an unforeseeable number of
+   * artificial eigenvalues to the spectrum of the matrix. Therefore, it is
+   * recommended to use the equivalent function with two local index vectors
+   * in such a case.
+   *
+   * By using this function to distribute local contributions to the global
+   * object, one saves the call to the condense function after the vectors and
+   * matrices are fully assembled.
    *
    * @note This function in itself is thread-safe, i.e., it works properly
    * also when several threads call it simultaneously. However, the function
-   * call is only thread-safe if the underlying global matrix allows
-   * for simultaneous access and the access is not to rows with the same
-   * global index at the same time. This needs to be made sure from the
-   * caller's site. There is no locking mechanism inside this method to
-   * prevent data races.
+   * call is only thread-safe if the underlying global matrix allows for
+   * simultaneous access and the access is not to rows with the same global
+   * index at the same time. This needs to be made sure from the caller's
+   * site. There is no locking mechanism inside this method to prevent data
+   * races.
    */
   template <typename MatrixType>
   void
@@ -913,16 +902,15 @@ public:
 
   /**
    * Does almost the same as the function above but can treat general
-   * rectangular matrices.  The main difference to achieve this is
-   * that the diagonal entries in constrained rows are left untouched
-   * instead of being filled with arbitrary values.
+   * rectangular matrices.  The main difference to achieve this is that the
+   * diagonal entries in constrained rows are left untouched instead of being
+   * filled with arbitrary values.
    *
-   * Since the diagonal entries corresponding to eliminated degrees of
-   * freedom are not set, the result may have a zero eigenvalue, if
-   * applied to a square matrix. This has to be considered when
-   * solving the resulting problems. For solving a source problem
-   * $Au=f$, it is possible to set the diagonal entry after building
-   * the matrix by a piece of code of the form
+   * Since the diagonal entries corresponding to eliminated degrees of freedom
+   * are not set, the result may have a zero eigenvalue, if applied to a
+   * square matrix. This has to be considered when solving the resulting
+   * problems. For solving a source problem $Au=f$, it is possible to set the
+   * diagonal entry after building the matrix by a piece of code of the form
    *
    * @code
    *   for (unsigned int i=0;i<matrix.m();++i)
@@ -930,15 +918,14 @@ public:
    *       matrix.diag_element(i) = 1.;
    * @endcode
    *
-   * The value of one which is used here is arbitrary, but in the
-   * context of Krylov space methods uncritical, since it corresponds
-   * to an invariant subspace. If the other matrix entries are smaller
-   * or larger by a factor close to machine accuracy, it may be
-   * advisable to adjust it.
+   * The value of one which is used here is arbitrary, but in the context of
+   * Krylov space methods uncritical, since it corresponds to an invariant
+   * subspace. If the other matrix entries are smaller or larger by a factor
+   * close to machine accuracy, it may be advisable to adjust it.
    *
-   * For solving eigenvalue problems, this will only add one spurious
-   * zero eigenvalue (with a multiplicity that is possibly greater
-   * than one). Taking this into account, nothing else has to be changed.
+   * For solving eigenvalue problems, this will only add one spurious zero
+   * eigenvalue (with a multiplicity that is possibly greater than one).
+   * Taking this into account, nothing else has to be changed.
    */
   template <typename MatrixType>
   void
@@ -949,10 +936,10 @@ public:
 
   /**
    * This function simultaneously writes elements into matrix and vector,
-   * according to the constraints specified by the calling
-   * ConstraintMatrix. This function can correctly handle inhomogeneous
-   * constraints as well. For the parameter use_inhomogeneities_for_rhs see
-   * the documentation in @ref constraints module.
+   * according to the constraints specified by the calling ConstraintMatrix.
+   * This function can correctly handle inhomogeneous constraints as well. For
+   * the parameter use_inhomogeneities_for_rhs see the documentation in @ref
+   * constraints module.
    *
    * @note This function in itself is thread-safe, i.e., it works properly
    * also when several threads call it simultaneously. However, the function
@@ -987,9 +974,9 @@ public:
    * that.
    *
    * Because the function only allocates entries in a sparsity pattern, all it
-   * needs to know are the degrees of freedom that couple to each
-   * other. Unlike the previous function, no actual values are written, so the
-   * second input argument is not necessary here.
+   * needs to know are the degrees of freedom that couple to each other.
+   * Unlike the previous function, no actual values are written, so the second
+   * input argument is not necessary here.
    *
    * The third argument to this function, keep_constrained_entries determines
    * whether the function shall allocate entries in the sparsity pattern at
@@ -1078,9 +1065,9 @@ public:
    */
 
   /**
-   * Re-distribute the elements of the vector @p condensed to @p
-   * uncondensed. It is the user's responsibility to guarantee that all
-   * entries of @p uncondensed be zero!
+   * Re-distribute the elements of the vector @p condensed to @p uncondensed.
+   * It is the user's responsibility to guarantee that all entries of @p
+   * uncondensed be zero!
    *
    * This function undoes the action of @p condense somehow, but it should be
    * noted that it is not the inverse of @p condense.
@@ -1293,9 +1280,9 @@ private:
    * To make things worse, traversing the list of existing constraints
    * requires reads from many different places in memory. Thus, in large 3d
    * applications, the add_line() function showed up very prominently in the
-   * overall compute time, mainly because it generated a lot of cache
-   * misses. This should also be fixed by using the O(1) algorithm to access
-   * the fields of this array.
+   * overall compute time, mainly because it generated a lot of cache misses.
+   * This should also be fixed by using the O(1) algorithm to access the
+   * fields of this array.
    *
    * The field is useful in a number of other contexts as well, e.g. when one
    * needs random access to the constraints as in all the functions that apply
index c218213e0fdc585c060da4e0a06477c28cdca363..c21c65d278a26f215e9ce220cb6b2c2be753a026 100644 (file)
@@ -1584,9 +1584,9 @@ namespace internals
    * Since each thread gets its private version of scratch data out of the
    * ThreadLocalStorage, no conflicting access can occur. For this to be
    * valid, we need to make sure that no call within
-   * distribute_local_to_global is made that by itself can spawn
-   * tasks. Otherwise, we might end up in a situation where several threads
-   * fight for the data.
+   * distribute_local_to_global is made that by itself can spawn tasks.
+   * Otherwise, we might end up in a situation where several threads fight for
+   * the data.
    *
    * Access to the scratch data is only through the accessor class which
    * handles the access as well as marking the data as used.
index aa03e5ad841ab1af6642ab83110f1226617b6ccd..b6489b0c3c4d06be9bfe4f3bfcd9f697e8837afc 100644 (file)
@@ -38,13 +38,13 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Power method (von Mises) for eigenvalue computations.
  *
- * This method determines the largest eigenvalue of a matrix by
- * applying increasing powers of this matrix to a vector. If there is
- * an eigenvalue $l$ with dominant absolute value, the iteration vectors
- * will become aligned to its eigenspace and $Ax = lx$.
+ * This method determines the largest eigenvalue of a matrix by applying
+ * increasing powers of this matrix to a vector. If there is an eigenvalue $l$
+ * with dominant absolute value, the iteration vectors will become aligned to
+ * its eigenspace and $Ax = lx$.
  *
- * A shift parameter allows to shift the spectrum, so it is possible
- * to compute the smallest eigenvalue, too.
+ * A shift parameter allows to shift the spectrum, so it is possible to
+ * compute the smallest eigenvalue, too.
  *
  * Convergence of this method is known to be slow.
  *
@@ -60,17 +60,13 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver.
+   * Standardized data struct to pipe additional data to the solver.
    */
   struct AdditionalData
   {
     /**
-     * Shift parameter. This
-     * parameter allows to shift
-     * the spectrum to compute a
-     * different eigenvalue.
+     * Shift parameter. This parameter allows to shift the spectrum to compute
+     * a different eigenvalue.
      */
     double shift;
     /**
@@ -96,15 +92,10 @@ public:
   virtual ~EigenPower ();
 
   /**
-   * Power method. @p x is the
-   * (not necessarily normalized,
-   * but nonzero) start vector for
-   * the power method. After the
-   * iteration, @p value is the
-   * approximated eigenvalue and
-   * @p x is the corresponding
-   * eigenvector, normalized with
-   * respect to the l2-norm.
+   * Power method. @p x is the (not necessarily normalized, but nonzero) start
+   * vector for the power method. After the iteration, @p value is the
+   * approximated eigenvalue and @p x is the corresponding eigenvector,
+   * normalized with respect to the l2-norm.
    */
   template <class MATRIX>
   void
@@ -122,25 +113,23 @@ protected:
 /**
  * Inverse iteration (Wieland) for eigenvalue computations.
  *
- * This class implements an adaptive version of the inverse iteration by Wieland.
+ * This class implements an adaptive version of the inverse iteration by
+ * Wieland.
  *
- * There are two choices for the stopping criterion: by default, the
- * norm of the residual $A x - l x$ is computed. Since this might not
- * converge to zero for non-symmetric matrices with non-trivial Jordan
- * blocks, it can be replaced by checking the difference of successive
- * eigenvalues. Use AdditionalData::use_residual for switching
- * this option.
+ * There are two choices for the stopping criterion: by default, the norm of
+ * the residual $A x - l x$ is computed. Since this might not converge to zero
+ * for non-symmetric matrices with non-trivial Jordan blocks, it can be
+ * replaced by checking the difference of successive eigenvalues. Use
+ * AdditionalData::use_residual for switching this option.
  *
- * Usually, the initial guess entering this method is updated after
- * each step, replacing it with the new approximation of the
- * eigenvalue. Using a parameter AdditionalData::relaxation
- * between 0 and 1, this update can be damped. With relaxation
- * parameter 0, no update is performed. This damping allows for slower
- * adaption of the shift value to make sure that the method converges
- * to the eigenvalue closest to the initial guess. This can be aided
- * by the parameter AdditionalData::start_adaption, which
- * indicates the first iteration step in which the shift value should
- * be adapted.
+ * Usually, the initial guess entering this method is updated after each step,
+ * replacing it with the new approximation of the eigenvalue. Using a
+ * parameter AdditionalData::relaxation between 0 and 1, this update can be
+ * damped. With relaxation parameter 0, no update is performed. This damping
+ * allows for slower adaption of the shift value to make sure that the method
+ * converges to the eigenvalue closest to the initial guess. This can be aided
+ * by the parameter AdditionalData::start_adaption, which indicates the first
+ * iteration step in which the shift value should be adapted.
  *
  * @author Guido Kanschat, 2000, 2003
  */
@@ -154,9 +143,7 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver.
+   * Standardized data struct to pipe additional data to the solver.
    */
   struct AdditionalData
   {
@@ -166,8 +153,7 @@ public:
     double relaxation;
 
     /**
-     * Start step of adaptive
-     * shift parameter.
+     * Start step of adaptive shift parameter.
      */
     unsigned int start_adaption;
     /**
@@ -202,16 +188,10 @@ public:
   virtual ~EigenInverse ();
 
   /**
-   * Inverse method. @p value is
-   * the start guess for the
-   * eigenvalue and @p x is the
-   * (not necessarily normalized,
-   * but nonzero) start vector for
-   * the power method. After the
-   * iteration, @p value is the
-   * approximated eigenvalue and
-   * @p x is the corresponding
-   * eigenvector, normalized with
+   * Inverse method. @p value is the start guess for the eigenvalue and @p x
+   * is the (not necessarily normalized, but nonzero) start vector for the
+   * power method. After the iteration, @p value is the approximated
+   * eigenvalue and @p x is the corresponding eigenvector, normalized with
    * respect to the l2-norm.
    */
   template <class MATRIX>
index 11b49faf85eb452ba9739bed775b7eb16c93f5f8..b5079229f9886e02fd66934605dd2c57ad346f49 100644 (file)
@@ -28,26 +28,22 @@ namespace LACExceptions
   //@{
 
   /**
-   * This function only works for
-   * quadratic matrices.
+   * This function only works for quadratic matrices.
    */
   DeclException0 (ExcNotQuadratic);
 
   /**
-   * The operation cannot be finished
-   * since the matrix is singular.
+   * The operation cannot be finished since the matrix is singular.
    */
   DeclException0 (ExcSingular);
 
   /**
-   * Block indices of two block
-   * objects are different.
+   * Block indices of two block objects are different.
    */
   DeclException0 (ExcDifferentBlockIndices);
 
   /**
-   * An error of a PETSc function was
-   * encountered. Check the PETSc
+   * An error of a PETSc function was encountered. Check the PETSc
    * documentation for details.
    */
   DeclException1 (ExcPETScError,
@@ -56,8 +52,7 @@ namespace LACExceptions
                   << " occurred while calling a PETSc function");
 
   /**
-   * An error of a Trilinos function was
-   * encountered. Check the Trilinos
+   * An error of a Trilinos function was encountered. Check the Trilinos
    * documentation for details.
    */
   DeclException1 (ExcTrilinosError,
index d40b7038b5d5d5f436dcd6d0f7cd8c60c2a2adc4..f55dd8676cecdcecd753b867ad657fc85156f0fb 100644 (file)
@@ -40,35 +40,30 @@ template <class VECTOR> class FilteredMatrixBlock;
 
 /**
  * This class is a wrapper for linear systems of equations with simple
- * equality constraints fixing individual degrees of freedom to a
- * certain value such as when using Dirichlet boundary
- * values.
+ * equality constraints fixing individual degrees of freedom to a certain
+ * value such as when using Dirichlet boundary values.
  *
  * In order to accomplish this, the vmult(), Tvmult(), vmult_add() and
- * Tvmult_add functions modify the same function of the original
- * matrix such as if all constrained entries of the source vector were
- * zero. Additionally, all constrained entries of the destination
- * vector are set to zero.
+ * Tvmult_add functions modify the same function of the original matrix such
+ * as if all constrained entries of the source vector were zero. Additionally,
+ * all constrained entries of the destination vector are set to zero.
  *
  * <h3>Usage</h3>
  *
- * Usage is simple: create an object of this type, point it to a
- * matrix that shall be used for $A$ above (either through the
- * constructor, the copy constructor, or the
- * set_referenced_matrix() function), specify the list of boundary
- * values or other constraints (through the add_constraints()
- * function), and then for each required solution modify the right
- * hand side vector (through apply_constraints()) and use this
- * object as matrix object in a linear solver. As linear solvers
- * should only use vmult() and residual() functions of a
- * matrix class, this class should be as good a matrix as any other
- * for that purpose.
+ * Usage is simple: create an object of this type, point it to a matrix that
+ * shall be used for $A$ above (either through the constructor, the copy
+ * constructor, or the set_referenced_matrix() function), specify the list of
+ * boundary values or other constraints (through the add_constraints()
+ * function), and then for each required solution modify the right hand side
+ * vector (through apply_constraints()) and use this object as matrix object
+ * in a linear solver. As linear solvers should only use vmult() and
+ * residual() functions of a matrix class, this class should be as good a
+ * matrix as any other for that purpose.
  *
- * Furthermore, also the precondition_Jacobi() function is
- * provided (since the computation of diagonal elements of the
- * filtered matrix $A_X$ is simple), so you can use this as a
- * preconditioner. Some other functions useful for matrices are also
- * available.
+ * Furthermore, also the precondition_Jacobi() function is provided (since the
+ * computation of diagonal elements of the filtered matrix $A_X$ is simple),
+ * so you can use this as a preconditioner. Some other functions useful for
+ * matrices are also available.
  *
  * A typical code snippet showing the above steps is as follows:
  * @code
@@ -100,100 +95,91 @@ template <class VECTOR> class FilteredMatrixBlock;
  *
  * <h3>Connection to other classes</h3>
  *
- * The function MatrixTools::apply_boundary_values() does exactly
- * the same that this class does, except for the fact that that
- * function actually modifies the matrix. Consequently, it is only
- * possible to solve with a matrix to which
- * MatrixTools::apply_boundary_values() was applied for one right
- * hand side and one set of boundary values since the modification of
+ * The function MatrixTools::apply_boundary_values() does exactly the same
+ * that this class does, except for the fact that that function actually
+ * modifies the matrix. Consequently, it is only possible to solve with a
+ * matrix to which MatrixTools::apply_boundary_values() was applied for one
+ * right hand side and one set of boundary values since the modification of
  * the right hand side depends on the original matrix.
  *
- * While this is a feasible method in cases where only
- * one solution of the linear system is required, for example in
- * solving linear stationary systems, one would often like to have the
- * ability to solve multiple times with the same matrix in nonlinear
- * problems (where one often does not want to update the Hessian
- * between Newton steps, despite having different right hand sides in
- * subsequent steps) or time dependent problems, without having to
- * re-assemble the matrix or copy it to temporary matrices with which
- * one then can work. For these cases, this class is meant.
+ * While this is a feasible method in cases where only one solution of the
+ * linear system is required, for example in solving linear stationary
+ * systems, one would often like to have the ability to solve multiple times
+ * with the same matrix in nonlinear problems (where one often does not want
+ * to update the Hessian between Newton steps, despite having different right
+ * hand sides in subsequent steps) or time dependent problems, without having
+ * to re-assemble the matrix or copy it to temporary matrices with which one
+ * then can work. For these cases, this class is meant.
  *
  *
- * <h3>Some background</h3>
- * Mathematically speaking, it is used to represent a system
- * of linear equations $Ax=b$ with the constraint that $B_D x = g_D$,
- * where $B_D$ is a rectangular matrix with exactly one $1$ in each
- * row, and these $1$s in those columns representing constrained
- * degrees of freedom (e.g. for Dirichlet boundary nodes, thus the
- * index $D$) and zeroes for all other diagonal entries, and $g_D$
- * having the requested nodal values for these constrained
- * nodes. Thus, the underdetermined equation $B_D x = g_D$ fixes only
- * the constrained nodes and does not impose any condition on the
- * others. We note that $B_D B_D^T = 1_D$, where $1_D$ is the identity
- * matrix with dimension as large as the number of constrained degrees
- * of freedom. Likewise, $B_D^T B_D$ is the diagonal matrix with
- * diagonal entries $0$ or $1$ that, when applied to a vector, leaves
- * all constrained nodes untouched and deletes all unconstrained ones.
+ * <h3>Some background</h3> Mathematically speaking, it is used to represent a
+ * system of linear equations $Ax=b$ with the constraint that $B_D x = g_D$,
+ * where $B_D$ is a rectangular matrix with exactly one $1$ in each row, and
+ * these $1$s in those columns representing constrained degrees of freedom
+ * (e.g. for Dirichlet boundary nodes, thus the index $D$) and zeroes for all
+ * other diagonal entries, and $g_D$ having the requested nodal values for
+ * these constrained nodes. Thus, the underdetermined equation $B_D x = g_D$
+ * fixes only the constrained nodes and does not impose any condition on the
+ * others. We note that $B_D B_D^T = 1_D$, where $1_D$ is the identity matrix
+ * with dimension as large as the number of constrained degrees of freedom.
+ * Likewise, $B_D^T B_D$ is the diagonal matrix with diagonal entries $0$ or
+ * $1$ that, when applied to a vector, leaves all constrained nodes untouched
+ * and deletes all unconstrained ones.
  *
- * For solving such a system of equations, we first write down the
- * Lagrangian $L=1/2 x^T A x - x^T b + l^T B_D x$, where $l$
- * is a Lagrange multiplier for the constraints. The stationarity
- * condition then reads
+ * For solving such a system of equations, we first write down the Lagrangian
+ * $L=1/2 x^T A x - x^T b + l^T B_D x$, where $l$ is a Lagrange multiplier for
+ * the constraints. The stationarity condition then reads
  * @code
  * [ A   B_D^T ] [x] = [b  ]
  * [ B_D 0     ] [l] = [g_D]
  * @endcode
  *
- * The first equation then reads $B_D^T l = b-Ax$. On the other hand,
- * if we left-multiply the first equation by $B_D^T B_D$, we obtain
- * $B_D^T B_D A x + B_D^T l = B_D^T B_D b$ after equating $B_D B_D^T$
- * to the identity matrix. Inserting the previous equality, this
- * yields $(A - B_D^T B_D A) x = (1 - B_D^T B_D)b$. Since
- * $x=(1 - B_D^T B_D) x + B_D^T B_D x = (1 - B_D^T B_D) x + B_D^T g_D$,
- * we can restate the linear system:
- * $A_D x = (1 - B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D$, where
- * $A_D = (1 - B_D^T B_D) A (1 - B_D^T B_D)$ is the matrix where all
- * rows and columns corresponding to constrained nodes have been deleted.
+ * The first equation then reads $B_D^T l = b-Ax$. On the other hand, if we
+ * left-multiply the first equation by $B_D^T B_D$, we obtain $B_D^T B_D A x +
+ * B_D^T l = B_D^T B_D b$ after equating $B_D B_D^T$ to the identity matrix.
+ * Inserting the previous equality, this yields $(A - B_D^T B_D A) x = (1 -
+ * B_D^T B_D)b$. Since $x=(1 - B_D^T B_D) x + B_D^T B_D x = (1 - B_D^T B_D) x
+ * + B_D^T g_D$, we can restate the linear system: $A_D x = (1 - B_D^T B_D)b -
+ * (1 - B_D^T B_D) A B^T g_D$, where $A_D = (1 - B_D^T B_D) A (1 - B_D^T B_D)$
+ * is the matrix where all rows and columns corresponding to constrained nodes
+ * have been deleted.
  *
- * The last system of equation only defines the value of the
- * unconstrained nodes, while the constrained ones are determined by
- * the equation $B_D x = g_D$. We can combine these two linear systems
- * by using the zeroed out rows of $A_D$: if we set the diagonal to
- * $1$ and the corresponding zeroed out element of the right hand side
- * to that of $g_D$, then this fixes the constrained elements as
- * well. We can write this as follows:
- * $A_X x = (1 - B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D + B_D^T g_D$,
- * where $A_X = A_D + B_D^T B_D$. Note that the two parts of the
- * latter matrix operate on disjoint subspaces (the first on the
- * unconstrained nodes, the latter on the constrained ones).
+ * The last system of equation only defines the value of the unconstrained
+ * nodes, while the constrained ones are determined by the equation $B_D x =
+ * g_D$. We can combine these two linear systems by using the zeroed out rows
+ * of $A_D$: if we set the diagonal to $1$ and the corresponding zeroed out
+ * element of the right hand side to that of $g_D$, then this fixes the
+ * constrained elements as well. We can write this as follows: $A_X x = (1 -
+ * B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D + B_D^T g_D$, where $A_X = A_D +
+ * B_D^T B_D$. Note that the two parts of the latter matrix operate on
+ * disjoint subspaces (the first on the unconstrained nodes, the latter on the
+ * constrained ones).
  *
  * In iterative solvers, it is not actually necessary to compute $A_X$
- * explicitly, since only matrix-vector operations need to be
- * performed. This can be done in a three-step procedure that first
- * clears all elements in the incoming vector that belong to
- * constrained nodes, then performs the product with the matrix $A$,
- * then clears again. This class is a wrapper to this procedure, it
- * takes a pointer to a matrix with which to perform matrix-vector
- * products, and does the cleaning of constrained elements itself.
- * This class therefore implements an overloaded @p vmult function
- * that does the matrix-vector product, as well as @p Tvmult for
- * transpose matrix-vector multiplication and @p residual for
- * residual computation, and can thus be used as a matrix replacement
- * in linear solvers.
+ * explicitly, since only matrix-vector operations need to be performed. This
+ * can be done in a three-step procedure that first clears all elements in the
+ * incoming vector that belong to constrained nodes, then performs the product
+ * with the matrix $A$, then clears again. This class is a wrapper to this
+ * procedure, it takes a pointer to a matrix with which to perform matrix-
+ * vector products, and does the cleaning of constrained elements itself. This
+ * class therefore implements an overloaded @p vmult function that does the
+ * matrix-vector product, as well as @p Tvmult for transpose matrix-vector
+ * multiplication and @p residual for residual computation, and can thus be
+ * used as a matrix replacement in linear solvers.
  *
- * It also has the ability to generate the modification of the right
- * hand side, through the apply_constraints() function.
+ * It also has the ability to generate the modification of the right hand
+ * side, through the apply_constraints() function.
  *
  *
  *
  * <h3>Template arguments</h3>
  *
- * This class takes as template arguments a matrix and a vector
- * class. The former must provide @p vmult, @p vmult_add,  @p Tvmult, and
- * @p residual member function that operate on the vector type (the
- * second template argument). The latter template parameter must
- * provide access to indivual elements through <tt>operator()</tt>,
- * assignment through <tt>operator=</tt>.
+ * This class takes as template arguments a matrix and a vector class. The
+ * former must provide @p vmult, @p vmult_add,  @p Tvmult, and @p residual
+ * member function that operate on the vector type (the second template
+ * argument). The latter template parameter must provide access to indivual
+ * elements through <tt>operator()</tt>, assignment through
+ * <tt>operator=</tt>.
  *
  *
  * <h3>Thread-safety</h3>
@@ -221,32 +207,25 @@ public:
   class Accessor
   {
     /**
-     * Constructor. Since we use
-     * accessors only for read
-     * access, a const matrix
-     * pointer is sufficient.
+     * Constructor. Since we use accessors only for read access, a const
+     * matrix pointer is sufficient.
      */
     Accessor (const FilteredMatrix<VECTOR> *matrix,
               const size_type               index);
 
   public:
     /**
-     * Row number of the element
-     * represented by this
-     * object.
+     * Row number of the element represented by this object.
      */
     size_type row() const;
 
     /**
-     * Column number of the
-     * element represented by
-     * this object.
+     * Column number of the element represented by this object.
      */
     size_type column() const;
 
     /**
-     * Value of the right hand
-     * side for this row.
+     * Value of the right hand side for this row.
      */
     double value() const;
 
@@ -305,10 +284,7 @@ public:
     const Accessor *operator-> () const;
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const const_iterator &) const;
     /**
@@ -317,34 +293,27 @@ public:
     bool operator != (const const_iterator &) const;
 
     /**
-     * Comparison operator. Result is
-     * true if either the first row
-     * number is smaller or if the row
-     * numbers are equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      */
     bool operator < (const const_iterator &) const;
 
     /**
-     * Comparison operator. Compares just
-     * the other way around than the
+     * Comparison operator. Compares just the other way around than the
      * operator above.
      */
     bool operator > (const const_iterator &) const;
 
   private:
     /**
-     * Store an object of the
-     * accessor class.
+     * Store an object of the accessor class.
      */
     Accessor accessor;
   };
 
   /**
-   * Typedef defining a type that
-   * represents a pair of degree of
-   * freedom index and the value it
-   * shall have.
+   * Typedef defining a type that represents a pair of degree of freedom index
+   * and the value it shall have.
    */
   typedef std::pair<size_type, double> IndexValuePair;
 
@@ -353,30 +322,23 @@ public:
    */
 //@{
   /**
-   * Default constructor. You will
-   * have to set the matrix to be
-   * used later using
-   * initialize().
+   * Default constructor. You will have to set the matrix to be used later
+   * using initialize().
    */
   FilteredMatrix ();
 
   /**
-   * Copy constructor. Use the
-   * matrix and the constraints set
-   * in the given object for the
-   * present one as well.
+   * Copy constructor. Use the matrix and the constraints set in the given
+   * object for the present one as well.
    */
   FilteredMatrix (const FilteredMatrix &fm);
 
   /**
-   * Constructor. Use the given
-   * matrix for future operations.
+   * Constructor. Use the given matrix for future operations.
    *
    * @arg @p m: The matrix being used in multiplications.
    *
-   * @arg @p
-   * expect_constrained_source: See
-   * documentation of
+   * @arg @p expect_constrained_source: See documentation of
    * #expect_constrained_source.
    */
   template <class MATRIX>
@@ -384,25 +346,17 @@ public:
                   bool expect_constrained_source = false);
 
   /**
-   * Copy operator. Take over
-   * matrix and constraints from
-   * the other object.
+   * Copy operator. Take over matrix and constraints from the other object.
    */
   FilteredMatrix &operator = (const FilteredMatrix &fm);
 
   /**
-   * Set the matrix to be used
-   * further on. You will probably
-   * also want to call the
-   * clear_constraints()
-   * function if constraits were
-   * previously added.
+   * Set the matrix to be used further on. You will probably also want to call
+   * the clear_constraints() function if constraits were previously added.
    *
    * @arg @p m: The matrix being used in multiplications.
    *
-   * @arg @p
-   * expect_constrained_source: See
-   * documentation of
+   * @arg @p expect_constrained_source: See documentation of
    * #expect_constrained_source.
    */
   template <class MATRIX>
@@ -410,8 +364,7 @@ public:
                    bool expect_constrained_source = false);
 
   /**
-   * Delete all constraints and the
-   * matrix pointer.
+   * Delete all constraints and the matrix pointer.
    */
   void clear ();
 //@}
@@ -420,49 +373,31 @@ public:
    */
 //@{
   /**
-   * Add the constraint that the
-   * value with index <tt>i</tt>
-   * should have the value
-   * <tt>v</tt>.
+   * Add the constraint that the value with index <tt>i</tt> should have the
+   * value <tt>v</tt>.
    */
   void add_constraint (const size_type i, const double v);
 
   /**
-   * Add a list of constraints to
-   * the ones already managed by
-   * this object. The actual data
-   * type of this list must be so
-   * that dereferenced iterators
-   * are pairs of indices and the
-   * corresponding values to be
-   * enforced on the respective
-   * solution vector's entry. Thus,
-   * the data type might be, for
-   * example, a @p std::list or
-   * @p std::vector of
-   * IndexValuePair objects,
-   * but also a
-   * <tt>std::map<unsigned, double></tt>.
+   * Add a list of constraints to the ones already managed by this object. The
+   * actual data type of this list must be so that dereferenced iterators are
+   * pairs of indices and the corresponding values to be enforced on the
+   * respective solution vector's entry. Thus, the data type might be, for
+   * example, a @p std::list or @p std::vector of IndexValuePair objects, but
+   * also a <tt>std::map<unsigned, double></tt>.
    *
-   * The second component of these
-   * pairs will only be used in
-   * apply_constraints(). The first
-   * is used to set values to zero
-   * in matrix vector
-   * multiplications.
+   * The second component of these pairs will only be used in
+   * apply_constraints(). The first is used to set values to zero in matrix
+   * vector multiplications.
    *
-   * It is an error if the argument
-   * contains an entry for a degree
-   * of freedom that has already
-   * been constrained
-   * previously.
+   * It is an error if the argument contains an entry for a degree of freedom
+   * that has already been constrained previously.
    */
   template <class ConstraintList>
   void add_constraints (const ConstraintList &new_constraints);
 
   /**
-   * Delete the list of constraints
-   * presently in use.
+   * Delete the list of constraints presently in use.
    */
   void clear_constraints ();
 //@}
@@ -471,36 +406,24 @@ public:
    */
 //@{
   /**
-   * Apply the constraints to a
-   * right hand side vector. This
-   * needs to be done before
-   * starting to solve with the
-   * filtered matrix. If the matrix
-   * is symmetric (i.e. the matrix
-   * itself, not only its sparsity
-   * pattern), set the second
-   * parameter to @p true to use a
-   * faster algorithm.
+   * Apply the constraints to a right hand side vector. This needs to be done
+   * before starting to solve with the filtered matrix. If the matrix is
+   * symmetric (i.e. the matrix itself, not only its sparsity pattern), set
+   * the second parameter to @p true to use a faster algorithm.
    */
   void apply_constraints (VECTOR     &v,
                           const bool  matrix_is_symmetric) const;
 
   /**
-   * Matrix-vector multiplication:
-   * this operation performs
-   * pre_filter(), multiplication
-   * with the stored matrix and
-   * post_filter() in that order.
+   * Matrix-vector multiplication: this operation performs pre_filter(),
+   * multiplication with the stored matrix and post_filter() in that order.
    */
   void vmult (VECTOR       &dst,
               const VECTOR &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * this operation performs
-   * pre_filter(), transposed
-   * multiplication with the stored
-   * matrix and post_filter() in
+   * Matrix-vector multiplication: this operation performs pre_filter(),
+   * transposed multiplication with the stored matrix and post_filter() in
    * that order.
    */
   void Tvmult (VECTOR       &dst,
@@ -509,14 +432,9 @@ public:
   /**
    * Adding matrix-vector multiplication.
    *
-   * @note The result vector of
-   * this multiplication will have
-   * the constraint entries set to
-   * zero, independent of the
-   * previous value of
-   * <tt>dst</tt>. We excpect that
-   * in most cases this is the
-   * required behavior.
+   * @note The result vector of this multiplication will have the constraint
+   * entries set to zero, independent of the previous value of <tt>dst</tt>.
+   * We excpect that in most cases this is the required behavior.
    */
   void vmult_add (VECTOR       &dst,
                   const VECTOR &src) const;
@@ -524,14 +442,9 @@ public:
   /**
    * Adding transpose matrix-vector multiplication:
    *
-   * @note The result vector of
-   * this multiplication will have
-   * the constraint entries set to
-   * zero, independent of the
-   * previous value of
-   * <tt>dst</tt>. We excpect that
-   * in most cases this is the
-   * required behavior.
+   * @note The result vector of this multiplication will have the constraint
+   * entries set to zero, independent of the previous value of <tt>dst</tt>.
+   * We excpect that in most cases this is the required behavior.
    */
   void Tvmult_add (VECTOR       &dst,
                    const VECTOR &src) const;
@@ -542,8 +455,7 @@ public:
    */
 //@{
   /**
-   * Iterator to the first
-   * constraint.
+   * Iterator to the first constraint.
    */
   const_iterator begin () const;
   /**
@@ -553,103 +465,74 @@ public:
 //@}
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object. Since we are
-   * not the owner of the matrix
-   * referenced, its memory
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. Since we are not the owner of the matrix referenced, its memory
    * consumption is not included.
    */
   std::size_t memory_consumption () const;
 
 private:
   /**
-   * Determine, whether
-   * multiplications can expect
-   * that the source vector has all
-   * constrained entries set to
-   * zero.
+   * Determine, whether multiplications can expect that the source vector has
+   * all constrained entries set to zero.
    *
-   * If so, the auxiliary vector
-   * can be avoided and memory as
-   * well as time can be saved.
+   * If so, the auxiliary vector can be avoided and memory as well as time can
+   * be saved.
    *
-   * We expect this for instance in
-   * Newton's method, where the
-   * residual already should be
-   * zero on constrained
-   * nodes. This is, because there
-   * is no testfunction in these
-   * nodes.
+   * We expect this for instance in Newton's method, where the residual
+   * already should be zero on constrained nodes. This is, because there is no
+   * testfunction in these nodes.
    */
   bool expect_constrained_source;
 
   /**
-   * Declare an abbreviation for an
-   * iterator into the array
-   * constraint pairs, since that
-   * data type is so often used and
-   * is rather awkward to write out
+   * Declare an abbreviation for an iterator into the array constraint pairs,
+   * since that data type is so often used and is rather awkward to write out
    * each time.
    */
   typedef typename std::vector<IndexValuePair>::const_iterator const_index_value_iterator;
 
   /**
-   * Helper class used to sort
-   * pairs of indices and
-   * values. Only the index is
+   * Helper class used to sort pairs of indices and values. Only the index is
    * considered as sort key.
    */
   struct PairComparison
   {
     /**
-     * Function comparing the
-     * pairs @p i1 and @p i2
-     * for their keys.
+     * Function comparing the pairs @p i1 and @p i2 for their keys.
      */
     bool operator () (const IndexValuePair &i1,
                       const IndexValuePair &i2) const;
   };
 
   /**
-   * Pointer to the sparsity
-   * pattern used for this
-   * matrix.
+   * Pointer to the sparsity pattern used for this matrix.
    */
   std_cxx11::shared_ptr<PointerMatrixBase<VECTOR> > matrix;
 
   /**
-   * Sorted list of pairs denoting
-   * the index of the variable and
-   * the value to which it shall be
-   * fixed.
+   * Sorted list of pairs denoting the index of the variable and the value to
+   * which it shall be fixed.
    */
   std::vector<IndexValuePair> constraints;
 
   /**
-   * Do the pre-filtering step,
-   * i.e. zero out those components
-   * that belong to constrained
-   * degrees of freedom.
+   * Do the pre-filtering step, i.e. zero out those components that belong to
+   * constrained degrees of freedom.
    */
   void pre_filter (VECTOR &v) const;
 
   /**
-   * Do the postfiltering step,
-   * i.e. set constrained degrees
-   * of freedom to the value of the
-   * input vector, as the matrix
-   * contains only ones on the
-   * diagonal for these degrees of
-   * freedom.
+   * Do the postfiltering step, i.e. set constrained degrees of freedom to the
+   * value of the input vector, as the matrix contains only ones on the
+   * diagonal for these degrees of freedom.
    */
   void post_filter (const VECTOR &in,
                     VECTOR       &out) const;
 
   friend class Accessor;
   /**
-   * FilteredMatrixBlock accesses
-   * pre_filter() and post_filter().
+   * FilteredMatrixBlock accesses pre_filter() and post_filter().
    */
   friend class FilteredMatrixBlock<VECTOR>;
 };
index dc852f740399faa1d34017abf6d60c4ad712e09c..7cd8a1e200008722b16a4374017e91ef0315362b 100644 (file)
@@ -42,21 +42,20 @@ template <typename number> class LAPACKFullMatrix;
 
 
 /**
- * Implementation of a classical rectangular scheme of numbers. The
- * data type of the entries is provided in the template argument
- * <tt>number</tt>.  The interface is quite fat and in fact has grown every
- * time a new feature was needed. So, a lot of functions are provided.
+ * Implementation of a classical rectangular scheme of numbers. The data type
+ * of the entries is provided in the template argument <tt>number</tt>.  The
+ * interface is quite fat and in fact has grown every time a new feature was
+ * needed. So, a lot of functions are provided.
  *
- * Internal calculations are usually done with the accuracy of the
- * vector argument to functions. If there is no argument with a number
- * type, the matrix number type is used.
+ * Internal calculations are usually done with the accuracy of the vector
+ * argument to functions. If there is no argument with a number type, the
+ * matrix number type is used.
  *
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
  *
  * @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth, 1993-2004
  */
@@ -65,10 +64,10 @@ class FullMatrix : public Table<2,number>
 {
 public:
   /**
-   * A type of used to index into this container. Because we can not
-   * expect to store matrices bigger than what can be indexed by a regular
-   * unsigned integer, <code>unsigned int</code> is completely sufficient
-   * as an index type.
+   * A type of used to index into this container. Because we can not expect to
+   * store matrices bigger than what can be indexed by a regular unsigned
+   * integer, <code>unsigned int</code> is completely sufficient as an index
+   * type.
    */
   typedef unsigned int size_type;
 
@@ -81,9 +80,9 @@ public:
   /**
    * Declare a type that has holds real-valued numbers with the same precision
    * as the template argument to this class. If the template argument of this
-   * class is a real data type, then real_type equals the template
-   * argument. If the template argument is a std::complex type then real_type
-   * equals the type underlying the complex numbers.
+   * class is a real data type, then real_type equals the template argument.
+   * If the template argument is a std::complex type then real_type equals the
+   * type underlying the complex numbers.
    *
    * This typedef is used to represent the return type of norms.
    */
@@ -226,14 +225,13 @@ public:
               const size_type cols);
 
   /**
-   * Copy constructor. This constructor does a deep copy of the
-   * matrix. Therefore, it poses a possible efficiency problem, if for
-   * example, function arguments are passed by value rather than by
-   * reference. Unfortunately, we can't mark this copy constructor
-   * <tt>explicit</tt>, since that prevents the use of this class in
-   * containers, such as <tt>std::vector</tt>. The responsibility to check
-   * performance of programs must therefore remain with the user of this
-   * class.
+   * Copy constructor. This constructor does a deep copy of the matrix.
+   * Therefore, it poses a possible efficiency problem, if for example,
+   * function arguments are passed by value rather than by reference.
+   * Unfortunately, we can't mark this copy constructor <tt>explicit</tt>,
+   * since that prevents the use of this class in containers, such as
+   * <tt>std::vector</tt>. The responsibility to check performance of programs
+   * must therefore remain with the user of this class.
    */
   FullMatrix (const FullMatrix &);
 
@@ -361,16 +359,16 @@ public:
           const size_type dst_c=0) const;
 
   /**
-   * Copy a subset of the rows and columns of another matrix into the
-   * current object.
+   * Copy a subset of the rows and columns of another matrix into the current
+   * object.
    *
    * @param matrix The matrix from which a subset is to be taken from.
    * @param row_index_set The set of rows of @p matrix from which to extract.
-   * @param column_index_set The set of columns of @p matrix from which to extract.
-   * @pre The number of elements in @p row_index_set and
-   *      @p column_index_set shall be equal to the number of
-   *      rows and columns in the current object. In other words,
-   *      the current object is not resized for this operation.
+   * @param column_index_set The set of columns of @p matrix from which to
+   * extract. @pre The number of elements in @p row_index_set and @p
+   * column_index_set shall be equal to the number of rows and columns in the
+   * current object. In other words, the current object is not resized for
+   * this operation.
    */
   template <typename MatrixType, typename index_type>
   void extract_submatrix_from (const MatrixType &matrix,
@@ -378,16 +376,16 @@ public:
                                const std::vector<index_type> &column_index_set);
 
   /**
-   * Copy the elements of the current matrix object into a specified
-   * set of rows and columns of another matrix. Thus, this is a scatter operation.
+   * Copy the elements of the current matrix object into a specified set of
+   * rows and columns of another matrix. Thus, this is a scatter operation.
    *
    * @param row_index_set The rows of @p matrix into which to write.
    * @param column_index_set The columns of @p matrix into which to write.
-   * @param matrix The matrix within which certain elements are to be replaced.
-   * @pre The number of elements in @p row_index_set and
-   *      @p column_index_set shall be equal to the number of
-   *      rows and columns in the current object. In other words,
-   *      the current object is not resized for this operation.
+   * @param matrix The matrix within which certain elements are to be
+   * replaced. @pre The number of elements in @p row_index_set and @p
+   * column_index_set shall be equal to the number of rows and columns in the
+   * current object. In other words, the current object is not resized for
+   * this operation.
    */
   template <typename MatrixType, typename index_type>
   void
@@ -438,8 +436,8 @@ public:
   /**
    * Set a particular entry of the matrix to a value. Thus, calling
    * <code>A.set(1,2,3.141);</code> is entirely equivalent to the operation
-   * <code>A(1,2) = 3.141;</code>. This function exists for compatibility
-   * with the various sparse matrix objects.
+   * <code>A(1,2) = 3.141;</code>. This function exists for compatibility with
+   * the various sparse matrix objects.
    *
    * @param i The row index of the element to be set.
    * @param j The columns index of the element to be set.
@@ -592,7 +590,7 @@ public:
    *
    * @arg <tt>threshold</tt>: all entries with absolute value smaller than
    * this are considered zero.
-  */
+   */
   void print_formatted (std::ostream       &out,
                         const unsigned int  precision=3,
                         const bool          scientific  = true,
@@ -688,8 +686,8 @@ public:
   /**
    * Add rectangular block.
    *
-   * A rectangular block of the matrix <tt>src</tt> is added to
-   * <tt>this</tt>. The upper left corner of the block being copied is
+   * A rectangular block of the matrix <tt>src</tt> is added to <tt>this</tt>.
+   * The upper left corner of the block being copied is
    * <tt>(src_offset_i,src_offset_j)</tt>.  The upper left corner of the
    * copied block is <tt>(dst_offset_i,dst_offset_j)</tt>.  The size of the
    * rectangular block being copied is the maximum size possible, determined
@@ -793,7 +791,7 @@ public:
                  const size_type j);
 
   /**
-   *  Swap <i>A(1...n,i) <-> A(1...n,j)</i>.  Swap columns i and j of this
+   * Swap <i>A(1...n,i) <-> A(1...n,j)</i>.  Swap columns i and j of this
    */
   void swap_col (const size_type i,
                  const size_type j);
@@ -841,9 +839,9 @@ public:
 
   /**
    * A=Inverse(A). A must be a square matrix.  Inversion of this matrix by
-   * Gauss-Jordan algorithm with partial pivoting.  This process is
-   * well-behaved for positive definite matrices, but be aware of round-off
-   * errors in the indefinite case.
+   * Gauss-Jordan algorithm with partial pivoting.  This process is well-
+   * behaved for positive definite matrices, but be aware of round-off errors
+   * in the indefinite case.
    *
    * In case deal.II was configured with LAPACK, the functions Xgetrf and
    * Xgetri build an LU factorization and invert the matrix upon that
@@ -908,11 +906,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A*B</i>
+   * if (adding) <i>C += A*B</i>
    *
-   * if (!adding)
-   *  <i>C = A*B</i>
+   * if (!adding) <i>C = A*B</i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -933,11 +929,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A<sup>T</sup>*B</i>
+   * if (adding) <i>C += A<sup>T</sup>*B</i>
    *
-   * if (!adding)
-   *  <i>C = A<sup>T</sup>*B</i>
+   * if (!adding) <i>C = A<sup>T</sup>*B</i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -958,11 +952,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A*B<sup>T</sup></i>
+   * if (adding) <i>C += A*B<sup>T</sup></i>
    *
-   * if (!adding)
-   *  <i>C = A*B<sup>T</sup></i>
+   * if (!adding) <i>C = A*B<sup>T</sup></i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -984,11 +976,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A<sup>T</sup>*B<sup>T</sup></i>
+   * if (adding) <i>C += A<sup>T</sup>*B<sup>T</sup></i>
    *
-   * if (!adding)
-   *  <i>C = A<sup>T</sup>*B<sup>T</sup></i>
+   * if (!adding) <i>C = A<sup>T</sup>*B<sup>T</sup></i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -1026,11 +1016,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>w</tt> or added to <tt>w</tt>.
    *
-   * if (adding)
-   *  <i>w += A*v</i>
+   * if (adding) <i>w += A*v</i>
    *
-   * if (!adding)
-   *  <i>w = A*v</i>
+   * if (!adding) <i>w = A*v</i>
    *
    * Source and destination must not be the same vector.
    */
@@ -1054,11 +1042,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>w</tt> or added to <tt>w</tt>.
    *
-   * if (adding)
-   *  <i>w += A<sup>T</sup>*v</i>
+   * if (adding) <i>w += A<sup>T</sup>*v</i>
    *
-   * if (!adding)
-   *  <i>w = A<sup>T</sup>*v</i>
+   * if (!adding) <i>w = A<sup>T</sup>*v</i>
    *
    *
    * Source and destination must not be the same vector.
@@ -1126,8 +1112,10 @@ public:
 
   //@}
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
index 13db0505de9a04ef950a119cb500d0803195f8b8..19824b263ebd1866e198013a24d5b2687a997822 100644 (file)
@@ -75,8 +75,8 @@ namespace LinearAlgebraPETSc
     typedef PETScWrappers::MPI::Vector Vector;
 
     /**
-     * Typedef for the type used to describe vectors that
-     * consist of multiple blocks.
+     * Typedef for the type used to describe vectors that consist of multiple
+     * blocks.
      */
     typedef PETScWrappers::MPI::BlockVector BlockVector;
 
@@ -86,8 +86,8 @@ namespace LinearAlgebraPETSc
     typedef PETScWrappers::MPI::SparseMatrix SparseMatrix;
 
     /**
-     * Typedef for the type used to describe sparse matrices that
-     * consist of multiple blocks.
+     * Typedef for the type used to describe sparse matrices that consist of
+     * multiple blocks.
      */
     typedef PETScWrappers::MPI::BlockSparseMatrix BlockSparseMatrix;
 
@@ -156,8 +156,8 @@ namespace LinearAlgebraTrilinos
     typedef TrilinosWrappers::MPI::Vector Vector;
 
     /**
-     * Typedef for the type used to describe vectors that
-     * consist of multiple blocks.
+     * Typedef for the type used to describe vectors that consist of multiple
+     * blocks.
      */
     typedef TrilinosWrappers::MPI::BlockVector BlockVector;
 
@@ -167,8 +167,8 @@ namespace LinearAlgebraTrilinos
     typedef TrilinosWrappers::SparseMatrix SparseMatrix;
 
     /**
-     * Typedef for the type used to describe sparse matrices that
-     * consist of multiple blocks.
+     * Typedef for the type used to describe sparse matrices that consist of
+     * multiple blocks.
      */
     typedef TrilinosWrappers::BlockSparseMatrix BlockSparseMatrix;
 
index b5d40197f96925c12b55c8bdea9237d19acdcd2e..d9cdcf313453633ddb869d76f4a15c905b2a347e 100644 (file)
@@ -39,11 +39,10 @@ template<typename number> class Vector;
 /**
  * QR-decomposition of a full matrix.
  *
- * Whenever an object of this class is created, it copies the matrix
- * given and computes its QR-decomposition by Householder
- * algorithm. Then, the function least_squares() can be used to
- * compute the vector <i>x</i> minimizing <i>||Ax-b||</i> for a given
- * vector <i>b</i>.
+ * Whenever an object of this class is created, it copies the matrix given and
+ * computes its QR-decomposition by Householder algorithm. Then, the function
+ * least_squares() can be used to compute the vector <i>x</i> minimizing
+ * <i>||Ax-b||</i> for a given vector <i>b</i>.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -66,53 +65,41 @@ public:
   Householder ();
 
   /**
-   * Create an object holding the
-   * QR-decomposition of a matrix.
+   * Create an object holding the QR-decomposition of a matrix.
    */
   template<typename number2>
   Householder (const FullMatrix<number2> &);
 
   /**
-   * Compute the QR-decomposition
-   * of another matrix.
+   * Compute the QR-decomposition of another matrix.
    */
   template<typename number2>
   void
   initialize (const FullMatrix<number2> &);
 
   /**
-   * Solve the least-squares
-   * problem for the right hand
-   * side <tt>src</tt>. The return
-   * value is the Euclidean norm of
-   * the approximation error.
+   * Solve the least-squares problem for the right hand side <tt>src</tt>. The
+   * return value is the Euclidean norm of the approximation error.
    *
-   * @arg @c dst contains the
-   * solution of the least squares
-   * problem on return.
+   * @arg @c dst contains the solution of the least squares problem on return.
    *
-   * @arg @c src contains the right
-   * hand side <i>b</i> of the
-   * least squares problem. It will
-   * be changed during the algorithm
-   * and is unusable on return.
+   * @arg @c src contains the right hand side <i>b</i> of the least squares
+   * problem. It will be changed during the algorithm and is unusable on
+   * return.
    */
   template<typename number2>
   double least_squares (Vector<number2> &dst,
                         const Vector<number2> &src) const;
 
   /**
-   * This function does the same as
-   * the one for BlockVectors.
+   * This function does the same as the one for BlockVectors.
    */
   template<typename number2>
   double least_squares (BlockVector<number2> &dst,
                         const BlockVector<number2> &src) const;
 
   /**
-   * A wrapper to least_squares(),
-   * implementing the standard
-   * MATRIX interface.
+   * A wrapper to least_squares(), implementing the standard MATRIX interface.
    */
   template<class VECTOR>
   void vmult (VECTOR &dst, const VECTOR &src) const;
@@ -123,9 +110,7 @@ public:
 
 private:
   /**
-   * Storage for the diagonal
-   * elements of the orthogonal
-   * transformation.
+   * Storage for the diagonal elements of the orthogonal transformation.
    */
   std::vector<number> diagonal;
 };
index e85f73a01da176ca83b586cdd2bbbd7b4ab3c4ab..dee5615de2d8d763e3aef5c7ae714fdd3332b815 100644 (file)
@@ -28,44 +28,41 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Implementation of a simple class representing the identity matrix
- * of a given size, i.e. a matrix with entries
- * $A_{ij}=\delta_{ij}$. While it has the most important ingredients
- * of a matrix, in particular that one can ask for its size and
- * perform matrix-vector products with it, a matrix of this type is
- * really only useful in two contexts: preconditioning and
+ * Implementation of a simple class representing the identity matrix of a
+ * given size, i.e. a matrix with entries $A_{ij}=\delta_{ij}$. While it has
+ * the most important ingredients of a matrix, in particular that one can ask
+ * for its size and perform matrix-vector products with it, a matrix of this
+ * type is really only useful in two contexts: preconditioning and
  * initializing other matrices.
  *
-
- * <h4>Initialization</h4>
+ *  <h4>Initialization</h4>
  *
- * The main usefulness of this class lies in its ability to initialize
- * other matrix, like this:
- @code
  FullMatrix<double> identity (IdentityMatrix(10));
- @endcode
+ * The main usefulness of this class lies in its ability to initialize other
+ * matrix, like this:
@code
* FullMatrix<double> identity (IdentityMatrix(10));
@endcode
  *
- * This creates a $10\times 10$ matrix with ones on the diagonal and
- * zeros everywhere else. Most matrix types, in particular FullMatrix
- * and SparseMatrix, have conversion constructors and assignment
- * operators for IdentityMatrix, and can therefore be filled rather
- * easily with identity matrices.
+ * This creates a $10\times 10$ matrix with ones on the diagonal and zeros
+ * everywhere else. Most matrix types, in particular FullMatrix and
+ * SparseMatrix, have conversion constructors and assignment operators for
+ * IdentityMatrix, and can therefore be filled rather easily with identity
+ * matrices.
  *
  *
  * <h4>Preconditioning</h4>
  *
  * No preconditioning at all is equivalent to preconditioning with
- * preconditioning with the identity matrix. deal.II has a specialized
- * class for this purpose, PreconditionIdentity, than can be used in a
- * context as shown in the documentation of that class. The present
- * class can be used in much the same way, although without any
- * additional benefit:
- @code
-  SolverControl           solver_control (1000, 1e-12);
-  SolverCG<>              cg (solver_control);
-  cg.solve (system_matrix, solution, system_rhs,
-            IdentityMatrix(solution.size()));
- @endcode
+ * preconditioning with the identity matrix. deal.II has a specialized class
+ * for this purpose, PreconditionIdentity, than can be used in a context as
+ * shown in the documentation of that class. The present class can be used in
+ * much the same way, although without any additional benefit:
+ * @code
+ * SolverControl           solver_control (1000, 1e-12);
+ * SolverCG<>              cg (solver_control);
+ * cg.solve (system_matrix, solution, system_rhs,
+ *          IdentityMatrix(solution.size()));
+ * @endcode
  *
  *
  * @author Wolfgang Bangerth, 2006
@@ -79,72 +76,54 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Default constructor. Creates a
-   * zero-sized matrix that should
-   * be resized later on using the
-   * reinit() function.
+   * Default constructor. Creates a zero-sized matrix that should be resized
+   * later on using the reinit() function.
    */
   IdentityMatrix ();
 
   /**
-   * Constructor. Creates a
-   * identity matrix of size #n.
+   * Constructor. Creates a identity matrix of size #n.
    */
   IdentityMatrix (const size_type n);
 
   /**
-   * Resize the matrix to be of
-   * size #n by #n.
+   * Resize the matrix to be of size #n by #n.
    */
   void reinit (const size_type n);
 
   /**
-   * Number of rows of this
-   * matrix. For the present
-   * matrix, the number of rows and
-   * columns are equal, of course.
+   * Number of rows of this matrix. For the present matrix, the number of rows
+   * and columns are equal, of course.
    */
   size_type m () const;
 
   /**
-   * Number of columns of this
-   * matrix. For the present
-   * matrix, the number of rows and
-   * columns are equal, of course.
+   * Number of columns of this matrix. For the present matrix, the number of
+   * rows and columns are equal, of course.
    */
   size_type n () const;
 
   /**
-   * Matrix-vector
-   * multiplication. For the
-   * present case, this of course
-   * amounts to simply copying the
-   * input vector to the output
-   * vector.
+   * Matrix-vector multiplication. For the present case, this of course
+   * amounts to simply copying the input vector to the output vector.
    */
   template <class VECTOR1, class VECTOR2>
   void vmult (VECTOR1       &out,
               const VECTOR2 &in) const;
 
   /**
-   * Matrix-vector multiplication
-   * with addition to the output
-   * vector. For the present case,
-   * this of course amounts to
-   * simply adding the input
-   * vector to the output vector.
+   * Matrix-vector multiplication with addition to the output vector. For the
+   * present case, this of course amounts to simply adding the input vector to
+   * the output vector.
    */
   template <class VECTOR1, class VECTOR2>
   void vmult_add (VECTOR1       &out,
                   const VECTOR2 &in) const;
 
   /**
-   * Matrix-vector multiplication
-   * with the transpose matrix. For
-   * the present case, this of
-   * course amounts to simply
-   * copying the input vector to
-   * the output vector.
+   * Matrix-vector multiplication with the transpose matrix. For the present
+   * case, this of course amounts to simply copying the input vector to the
+   * output vector.
    */
   template <class VECTOR1, class VECTOR2>
   void Tvmult (VECTOR1       &out,
@@ -152,13 +131,9 @@ public:
 
 
   /**
-   * Matrix-vector multiplication
-   * with the transpose matrix,
-   * with addition to the output
-   * vector. For the present case,
-   * this of course amounts to
-   * simply adding the input vector
-   * to the output vector.
+   * Matrix-vector multiplication with the transpose matrix, with addition to
+   * the output vector. For the present case, this of course amounts to simply
+   * adding the input vector to the output vector.
    */
   template <class VECTOR1, class VECTOR2>
   void Tvmult_add (VECTOR1       &out,
@@ -166,8 +141,7 @@ public:
 private:
 
   /**
-   * Number of rows and columns of
-   * this matrix.
+   * Number of rows and columns of this matrix.
    */
   size_type size;
 };
index f061f815861991c47f2075889279e2fc472b04a4..a8d6a87e98df5363427901deaab7f379580c8ace 100644 (file)
@@ -26,20 +26,17 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Implementation of the inverse of a matrix, using an iterative
- * method.
+ * Implementation of the inverse of a matrix, using an iterative method.
  *
- * The function vmult() of this class starts an iterative solver in
- * order to approximate the action of the inverse matrix.
+ * The function vmult() of this class starts an iterative solver in order to
+ * approximate the action of the inverse matrix.
  *
- * Krylov space methods like SolverCG or SolverBicgstab
- * become inefficient if solution down to machine accuracy is
- * needed. This is due to the fact, that round-off errors spoil the
- * orthogonality of the vector sequences. Therefore, a nested
- * iteration of two methods is proposed: The outer method is
- * SolverRichardson, since it is robust with respect to round-of
- * errors. The inner loop is an appropriate Krylov space method, since
- * it is fast.
+ * Krylov space methods like SolverCG or SolverBicgstab become inefficient if
+ * solution down to machine accuracy is needed. This is due to the fact, that
+ * round-off errors spoil the orthogonality of the vector sequences.
+ * Therefore, a nested iteration of two methods is proposed: The outer method
+ * is SolverRichardson, since it is robust with respect to round-of errors.
+ * The inner loop is an appropriate Krylov space method, since it is fast.
  *
  * @code
  * // Declare related objects
@@ -63,11 +60,11 @@ DEAL_II_NAMESPACE_OPEN
  * outer_iteration.solve (A, x, b, precondition);
  * @endcode
  *
- * Each time we call the inner loop, reduction of the residual by a
- * factor <tt>1.e-2</tt> is attempted. Since the right hand side vector of
- * the inner iteration is the residual of the outer loop, the relative
- * errors are far from machine accuracy, even if the errors of the
- * outer loop are in the range of machine accuracy.
+ * Each time we call the inner loop, reduction of the residual by a factor
+ * <tt>1.e-2</tt> is attempted. Since the right hand side vector of the inner
+ * iteration is the residual of the outer loop, the relative errors are far
+ * from machine accuracy, even if the errors of the outer loop are in the
+ * range of machine accuracy.
  *
  * @ingroup Matrix2
  * @author Guido Kanschat
@@ -78,17 +75,14 @@ class IterativeInverse : public Subscriptor
 {
 public:
   /**
-   * Initialization
-   * function. Provide a matrix and
-   * preconditioner for the solve in
-   * vmult().
+   * Initialization function. Provide a matrix and preconditioner for the
+   * solve in vmult().
    */
   template <class MATRIX, class PRECONDITION>
   void initialize (const MATRIX &, const PRECONDITION &);
 
   /**
-   * Delete the pointers to matrix
-   * and preconditioner.
+   * Delete the pointers to matrix and preconditioner.
    */
   void clear();
 
@@ -98,18 +92,16 @@ public:
   void vmult (VECTOR &dst, const VECTOR &src) const;
 
   /**
-   * Solve for right hand side <tt>src</tt>, but allow for the fact
-   * that the vectors given to this function have different type from
-   * the vectors used by the inner solver.
+   * Solve for right hand side <tt>src</tt>, but allow for the fact that the
+   * vectors given to this function have different type from the vectors used
+   * by the inner solver.
    */
   template <class VECTOR2>
   void vmult (VECTOR2 &dst, const VECTOR2 &src) const;
 
   /**
-   * The solver, which allows
-   * selection of the actual solver
-   * as well as adjuxtment of
-   * parameters.
+   * The solver, which allows selection of the actual solver as well as
+   * adjuxtment of parameters.
    */
   SolverSelector<VECTOR> solver;
 
index b34f6f1a6d148848f9d732aad9e46436c2bb0477..fea33a56f75abfea1889c88c17378e47c0068522 100644 (file)
@@ -37,15 +37,13 @@ template<typename number> class SparseMatrix;
 
 
 /**
- * A variant of FullMatrix using LAPACK functions wherever
- * possible. In order to do this, the matrix is stored in transposed
- * order. The element access functions hide this fact by reverting the
- * transposition.
+ * A variant of FullMatrix using LAPACK functions wherever possible. In order
+ * to do this, the matrix is stored in transposed order. The element access
+ * functions hide this fact by reverting the transposition.
  *
  * @note In order to perform LAPACK functions, the class contains a lot of
- * auxiliary data in the private section. The names of these data
- * vectors are usually the names chosen for the arguments in the
- * LAPACK documentation.
+ * auxiliary data in the private section. The names of these data vectors are
+ * usually the names chosen for the arguments in the LAPACK documentation.
  *
  * @ingroup Matrix1
  * @author Guido Kanschat, 2005
@@ -80,14 +78,13 @@ public:
 
 
   /**
-   * Copy constructor. This constructor does a deep copy of the
-   * matrix. Therefore, it poses a possible efficiency problem, if for
-   * example, function arguments are passed by value rather than by
-   * reference. Unfortunately, we can't mark this copy constructor
-   * <tt>explicit</tt>, since that prevents the use of this class in
-   * containers, such as <tt>std::vector</tt>. The responsibility to check
-   * performance of programs must therefore remain with the user of this
-   * class.
+   * Copy constructor. This constructor does a deep copy of the matrix.
+   * Therefore, it poses a possible efficiency problem, if for example,
+   * function arguments are passed by value rather than by reference.
+   * Unfortunately, we can't mark this copy constructor <tt>explicit</tt>,
+   * since that prevents the use of this class in containers, such as
+   * <tt>std::vector</tt>. The responsibility to check performance of programs
+   * must therefore remain with the user of this class.
    */
   LAPACKFullMatrix (const LAPACKFullMatrix &);
 
@@ -98,18 +95,17 @@ public:
   operator = (const LAPACKFullMatrix<number> &);
 
   /**
-   * Assignment operator from a regular FullMatrix. @note Since LAPACK
-   * expects matrices in transposed order, this transposition is
-   * included here.
+   * Assignment operator from a regular FullMatrix. @note Since LAPACK expects
+   * matrices in transposed order, this transposition is included here.
    */
   template <typename number2>
   LAPACKFullMatrix<number> &
   operator = (const FullMatrix<number2> &);
 
   /**
-   * Assignment operator from a regular SparseMatrix. @note Since
-   * LAPACK expects matrices in transposed order, this transposition
-   * is included here.
+   * Assignment operator from a regular SparseMatrix. @note Since LAPACK
+   * expects matrices in transposed order, this transposition is included
+   * here.
    */
   template <typename number2>
   LAPACKFullMatrix<number> &
@@ -132,29 +128,29 @@ public:
   void copy_from (const MATRIX &);
 
   /**
-   * Regenerate the current matrix by one that has the same properties
-   * as if it were created by the constructor of this class with the
-   * same argument list as this present function.
+   * Regenerate the current matrix by one that has the same properties as if
+   * it were created by the constructor of this class with the same argument
+   * list as this present function.
    */
   void reinit (const size_type size);
 
   /**
-   * Regenerate the current matrix by one that has the same properties
-   * as if it were created by the constructor of this class with the
-   * same argument list as this present function.
+   * Regenerate the current matrix by one that has the same properties as if
+   * it were created by the constructor of this class with the same argument
+   * list as this present function.
    */
   void reinit (const size_type rows,
                const size_type cols);
 
   /**
-   * Return the dimension of the range space. @note The matrix is of
-   * dimension $m \times n$.
+   * Return the dimension of the range space. @note The matrix is of dimension
+   * $m \times n$.
    */
   unsigned int m () const;
 
   /**
-   * Return the number of the range space. @note The matrix is of
-   * dimension $m \times n$.
+   * Return the number of the range space. @note The matrix is of dimension $m
+   * \times n$.
    */
   unsigned int n () const;
 
@@ -198,11 +194,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>w</tt> or added to <tt>w</tt>.
    *
-   * if (adding)
-   *  <i>w += A*v</i>
+   * if (adding) <i>w += A*v</i>
    *
-   * if (!adding)
-   *  <i>w = A*v</i>
+   * if (!adding) <i>w = A*v</i>
    *
    * @note Source and destination must not be the same vector.
    *
@@ -227,13 +221,11 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>w</tt> or added to <tt>w</tt>.
    *
-   * if (adding)
-   *  <i>w += A<sup>T</sup>*v</i>
+   * if (adding) <i>w += A<sup>T</sup>*v</i>
    *
-   * if (!adding)
-   *  <i>w = A<sup>T</sup>*v</i>
+   * if (!adding) <i>w = A<sup>T</sup>*v</i>
    *
-  * See the documentation of vmult() for details on the implementation.
+   * See the documentation of vmult() for details on the implementation.
    */
   template <class VECTOR>
   void Tvmult (VECTOR &w, const VECTOR &v,
@@ -266,11 +258,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A*B</i>
+   * if (adding) <i>C += A*B</i>
    *
-   * if (!adding)
-   *  <i>C = A*B</i>
+   * if (!adding) <i>C = A*B</i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -295,11 +285,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A<sup>T</sup>*B</i>
+   * if (adding) <i>C += A<sup>T</sup>*B</i>
    *
-   * if (!adding)
-   *  <i>C = A<sup>T</sup>*B</i>
+   * if (!adding) <i>C = A<sup>T</sup>*B</i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -324,11 +312,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A*B<sup>T</sup></i>
+   * if (adding) <i>C += A*B<sup>T</sup></i>
    *
-   * if (!adding)
-   *  <i>C = A*B<sup>T</sup></i>
+   * if (!adding) <i>C = A*B<sup>T</sup></i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -354,11 +340,9 @@ public:
    * The optional parameter <tt>adding</tt> determines, whether the result is
    * stored in <tt>C</tt> or added to <tt>C</tt>.
    *
-   * if (adding)
-   *  <i>C += A<sup>T</sup>*B<sup>T</sup></i>
+   * if (adding) <i>C += A<sup>T</sup>*B<sup>T</sup></i>
    *
-   * if (!adding)
-   *  <i>C = A<sup>T</sup>*B<sup>T</sup></i>
+   * if (!adding) <i>C = A<sup>T</sup>*B<sup>T</sup></i>
    *
    * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
    * <tt>C</tt> already has the right size.
@@ -519,8 +503,8 @@ public:
    * Compute the inverse of the matrix by singular value decomposition.
    *
    * Requires that #state is either LAPACKSupport::matrix or
-   * LAPACKSupport::svd. In the first case, this function calls
-   * compute_svd(). After this function, the object will have the #state
+   * LAPACKSupport::svd. In the first case, this function calls compute_svd().
+   * After this function, the object will have the #state
    * LAPACKSupport::inverse_svd.
    *
    * For a singular value decomposition, the inverse is simply computed by
@@ -570,7 +554,7 @@ public:
    *
    * @arg <tt>threshold</tt>: all entries with absolute value smaller than
    * this are considered zero.
-  */
+   */
   void print_formatted (std::ostream       &out,
                         const unsigned int  presicion=3,
                         const bool          scientific  = true,
@@ -582,9 +566,8 @@ public:
 private:
 
   /**
-   * Since LAPACK operations notoriously change the meaning of the
-   * matrix entries, we record the current state after the last
-   * operation here.
+   * Since LAPACK operations notoriously change the meaning of the matrix
+   * entries, we record the current state after the last operation here.
    */
   LAPACKSupport::State state;
 
@@ -600,8 +583,8 @@ private:
   mutable std::vector<number> work;
 
   /**
-   * The vector storing the permutations applied for pivoting in the
-   * LU-factorization.
+   * The vector storing the permutations applied for pivoting in the LU-
+   * factorization.
    *
    * Also used as the scratch array IWORK for LAPACK functions needing it.
    */
index 497f0ec14cb37996ef39aa42e7b9d6a84db09a0e..83f899e7134826c926a2de5b3e6441b3243da9a1 100644 (file)
@@ -26,10 +26,9 @@ DEAL_II_NAMESPACE_OPEN
 namespace LAPACKSupport
 {
   /**
-   * Most LAPACK functions change the contents of the matrix applied to
-   * to something which is not a matrix anymore. Therefore, LAPACK
-   * matrix classes in <tt>deal.II</tt> have a state flag indicating
-   * what happened to them.
+   * Most LAPACK functions change the contents of the matrix applied to to
+   * something which is not a matrix anymore. Therefore, LAPACK matrix classes
+   * in <tt>deal.II</tt> have a state flag indicating what happened to them.
    *
    * @author Guido Kanschat, 2005
    */
@@ -79,8 +78,8 @@ namespace LAPACKSupport
   }
 
   /**
-   * A matrix can have certain features allowing for optimization, but
-   * hard to test. These are listed here.
+   * A matrix can have certain features allowing for optimization, but hard to
+   * test. These are listed here.
    */
   enum Properties
   {
@@ -128,30 +127,23 @@ namespace LAPACKSupport
   static const int one = 1;
 
   /**
-   * A LAPACK function returned an
-   * error code.
+   * A LAPACK function returned an error code.
    */
   DeclException2(ExcErrorCode, char *, int,
                  << "The function " << arg1 << " returned with an error code " << arg2);
 
   /**
-   * Exception thrown when a matrix
-   * is not in a suitable state for
-   * an operation. For instance, a
-   * LAPACK routine may have left the
-   * matrix in an unusable state,
-   * then vmult does not make sense
-   * anymore.
+   * Exception thrown when a matrix is not in a suitable state for an
+   * operation. For instance, a LAPACK routine may have left the matrix in an
+   * unusable state, then vmult does not make sense anymore.
    */
   DeclException1(ExcState, State,
                  << "The function cannot be called while the matrix is in state "
                  << state_name(arg1));
 
   /**
-   * This exception is thrown if a
-   * certain function is not
-   * implemented in your LAPACK
-   * version.
+   * This exception is thrown if a certain function is not implemented in your
+   * LAPACK version.
    */
   DeclException1(ExcMissing, char *,
                  << "The function "
index 9a94e3e5a26b525de40242e6f13ccc6ac36dea14..049b59f82f630099919591f32a1dde71a440d184 100644 (file)
@@ -46,36 +46,32 @@ namespace internal
 }
 
 /**
- * A wrapper around a matrix object, storing the coordinates in a
- * block matrix as well.
+ * A wrapper around a matrix object, storing the coordinates in a block matrix
+ * as well.
  *
- * This class is an alternative to BlockMatrixBase, if you only want
- * to generate a single block of the system, not the whole
- * system. Using the add() functions of this class, it is possible to
- * use the standard assembling functions used for block matrices, but
- * only enter in one of the blocks and still avoiding the index
- * computations involved.
-
- * The reason for this class is, that we may need a different number
- * of matrices for different blocks in a block system. For example, a
- * preconditioner for the Oseen system can be built as a block system,
- * where the pressure block is of the form
- * <b>M</b><sup>-1</sup><b>FA</b><sup>-1</sup> with <b>M</b> the
- * pressure mass matrix, <b>A</b> the pressure Laplacian and <b>F</b>
- * the advection diffusion operator applied to the pressure
- * space. Since only a single matrix is needed for the other blocks,
- * using BlockSparseMatrix or similar would be a waste of memory.
+ * This class is an alternative to BlockMatrixBase, if you only want to
+ * generate a single block of the system, not the whole system. Using the
+ * add() functions of this class, it is possible to use the standard
+ * assembling functions used for block matrices, but only enter in one of the
+ * blocks and still avoiding the index computations involved.  The reason for
+ * this class is, that we may need a different number of matrices for
+ * different blocks in a block system. For example, a preconditioner for the
+ * Oseen system can be built as a block system, where the pressure block is of
+ * the form <b>M</b><sup>-1</sup><b>FA</b><sup>-1</sup> with <b>M</b> the
+ * pressure mass matrix, <b>A</b> the pressure Laplacian and <b>F</b> the
+ * advection diffusion operator applied to the pressure space. Since only a
+ * single matrix is needed for the other blocks, using BlockSparseMatrix or
+ * similar would be a waste of memory.
  *
- * While the add() functions make a MatrixBlock appear like a block
- * matrix for assembling, the functions vmult(), Tvmult(),
- * vmult_add(), and Tvmult_add() make it behave like a MATRIX, when it
- * comes to applying it to a vector. This behavior allows us to store
- * MatrixBlock objects in vectors, for instance in MGLevelObject
- * without extracting the #matrix first.
+ * While the add() functions make a MatrixBlock appear like a block matrix for
+ * assembling, the functions vmult(), Tvmult(), vmult_add(), and Tvmult_add()
+ * make it behave like a MATRIX, when it comes to applying it to a vector.
+ * This behavior allows us to store MatrixBlock objects in vectors, for
+ * instance in MGLevelObject without extracting the #matrix first.
  *
- * MatrixBlock comes handy when using BlockMatrixArray. Once the
- * MatrixBlock has been properly initalized and filled, it can be used
- * in the simplest case as:
+ * MatrixBlock comes handy when using BlockMatrixArray. Once the MatrixBlock
+ * has been properly initalized and filled, it can be used in the simplest
+ * case as:
  * @code
  * MatrixBlockVector<SparseMatrix<double> > > blocks;
  *
@@ -87,19 +83,18 @@ namespace internal
  *   matrix.enter(blocks.block(i).row, blocks.block(i).column, blocks.matrix(i));
  * @endcode
  *
- * Here, we have not gained very much, except that we do not need to
- * set up empty blocks in the block system.
+ * Here, we have not gained very much, except that we do not need to set up
+ * empty blocks in the block system.
  *
- * @note This class expects, that the row and column BlockIndices
- * objects for the system are equal. If they are not, some functions
- * will throw ExcNotImplemented.
+ * @note This class expects, that the row and column BlockIndices objects for
+ * the system are equal. If they are not, some functions will throw
+ * ExcNotImplemented.
  *
  * @todo Example for the product preconditioner of the pressure Schur
  * complement.
  *
  * @ingroup Matrix2
- * @ingroup vector_valued
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup vector_valued @see @ref GlossBlockLA "Block (linear algebra)"
  * @author Guido Kanschat, 2006
  */
 template <class MATRIX>
@@ -113,8 +108,7 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Constructor rendering an
-   * uninitialized object.
+   * Constructor rendering an uninitialized object.
    */
   MatrixBlock();
 
@@ -124,23 +118,17 @@ public:
   MatrixBlock(const MatrixBlock<MATRIX> &M);
 
   /**
-   * Constructor setting block
-   * coordinates, but not
-   * initializing the matrix.
+   * Constructor setting block coordinates, but not initializing the matrix.
    */
 
   MatrixBlock(size_type i, size_type j);
 
   /**
-   * Reinitialize the matrix for a
-   * new BlockSparsityPattern. This
-   * adjusts the #matrix as well
-   * as the #row_indices and
-   * #column_indices.
+   * Reinitialize the matrix for a new BlockSparsityPattern. This adjusts the
+   * #matrix as well as the #row_indices and #column_indices.
    *
-   * @note The row and column block
-   * structure of the sparsity
-   * pattern must be equal.
+   * @note The row and column block structure of the sparsity pattern must be
+   * equal.
    */
   void reinit(const BlockSparsityPattern &sparsity);
 
@@ -148,45 +136,27 @@ public:
   operator const MATRIX &() const;
 
   /**
-   * Add <tt>value</tt> to the
-   * element (<i>i,j</i>). Throws
-   * an error if the entry does not
-   * exist or if it is in a
-   * different block.
+   * Add <tt>value</tt> to the element (<i>i,j</i>). Throws an error if the
+   * entry does not exist or if it is in a different block.
    */
   void add (const size_type i,
             const size_type j,
             const typename MATRIX::value_type value);
 
   /**
-   * Add all elements in a
-   * FullMatrix into sparse
-   * matrix locations given by
-   * <tt>indices</tt>. This function
-   * assumes a quadratic sparse
-   * matrix and a quadratic
-   * full_matrix.  The global
-   * locations are translated
-   * into locations in this block
-   * and ExcBlockIndexMismatch is
-   * thrown, if the global index
-   * does not point into the
-   * block referred to by #row and
+   * Add all elements in a FullMatrix into sparse matrix locations given by
+   * <tt>indices</tt>. This function assumes a quadratic sparse matrix and a
+   * quadratic full_matrix.  The global locations are translated into
+   * locations in this block and ExcBlockIndexMismatch is thrown, if the
+   * global index does not point into the block referred to by #row and
    * #column.
    *
-   * @todo
-   * <tt>elide_zero_values</tt> is
-   * currently ignored.
+   * @todo <tt>elide_zero_values</tt> is currently ignored.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const std::vector<size_type> &indices,
@@ -194,33 +164,18 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Add all elements in a
-   * FullMatrix into global
-   * locations given by
-   * <tt>row_indices</tt> and
-   * <tt>col_indices</tt>,
-   * respectively. The global
-   * locations are translated
-   * into locations in this block
-   * and ExcBlockIndexMismatch is
-   * thrown, if the global index
-   * does not point into the
-   * block referred to by #row and
-   * #column.
+   * Add all elements in a FullMatrix into global locations given by
+   * <tt>row_indices</tt> and <tt>col_indices</tt>, respectively. The global
+   * locations are translated into locations in this block and
+   * ExcBlockIndexMismatch is thrown, if the global index does not point into
+   * the block referred to by #row and #column.
    *
-   * @todo
-   * <tt>elide_zero_values</tt> is
-   * currently ignored.
+   * @todo <tt>elide_zero_values</tt> is currently ignored.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const std::vector<size_type> &row_indices,
@@ -229,38 +184,20 @@ public:
             const bool                       elide_zero_values = true);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix
-   * with column indices as given
-   * by <tt>col_indices</tt> to
-   * the respective value. This
-   * is the function doing thye
-   * actual work for the ones
-   * adding full matrices. The
-   * global locations
-   * <tt>row_index</tt> and
-   * <tt>col_indices</tt> are
-   * translated into locations in
-   * this block and
-   * ExcBlockIndexMismatch is
-   * thrown, if the global index
-   * does not point into the
-   * block referred to by #row and
-   * #column.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value. This is
+   * the function doing thye actual work for the ones adding full matrices.
+   * The global locations <tt>row_index</tt> and <tt>col_indices</tt> are
+   * translated into locations in this block and ExcBlockIndexMismatch is
+   * thrown, if the global index does not point into the block referred to by
+   * #row and #column.
    *
-   * @todo
-   * <tt>elide_zero_values</tt> is
-   * currently ignored.
+   * @todo <tt>elide_zero_values</tt> is currently ignored.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const size_type               row_index,
@@ -269,21 +206,13 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Add an array of values given by
-   * <tt>values</tt> in the given
-   * global matrix row at columns
-   * specified by col_indices in the
-   * sparse matrix.
+   * Add an array of values given by <tt>values</tt> in the given global
+   * matrix row at columns specified by col_indices in the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number>
   void add (const size_type  row,
@@ -294,44 +223,32 @@ public:
             const bool       col_indices_are_sorted = false);
 
   /**
-   * Matrix-vector-multiplication,
-   * forwarding to the same
-   * function in MATRIX. No index
-   * computations are done, thus,
-   * the vectors need to have sizes
+   * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+   * No index computations are done, thus, the vectors need to have sizes
    * matching #matrix.
    */
   template<class VECTOR>
   void vmult (VECTOR &w, const VECTOR &v) const;
 
   /**
-   * Matrix-vector-multiplication,
-   * forwarding to the same
-   * function in MATRIX. No index
-   * computations are done, thus,
-   * the vectors need to have sizes
+   * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+   * No index computations are done, thus, the vectors need to have sizes
    * matching #matrix.
    */
   template<class VECTOR>
   void vmult_add (VECTOR &w, const VECTOR &v) const;
 
   /**
-   * Matrix-vector-multiplication,
-   * forwarding to the same
-   * function in MATRIX. No index
-   * computations are done, thus,
-   * the vectors need to have sizes
+   * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+   * No index computations are done, thus, the vectors need to have sizes
    * matching #matrix.
    */
   template<class VECTOR>
   void Tvmult (VECTOR &w, const VECTOR &v) const;
 
   /**
-   * Matrix-vector-multiplication,
-   * forwarding to the same
-   * function in MATRIX. No index
-   * computations are done, thus,
-   * the vectors need to have sizes
+   * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+   * No index computations are done, thus, the vectors need to have sizes
    * matching #matrix.
    */
   template<class VECTOR>
@@ -343,26 +260,20 @@ public:
   std::size_t memory_consumption () const;
 
   /**
-   * The block number computed from
-   * an index by using
-   * BlockIndices does not match
-   * the block coordinates stored
-   * in this object.
+   * The block number computed from an index by using BlockIndices does not
+   * match the block coordinates stored in this object.
    */
   DeclException2(ExcBlockIndexMismatch, size_type, size_type,
                  << "Block index " << arg1 << " does not match " << arg2);
 
   /**
-   * Row coordinate.  This is the
-   * position of the data member
-   * matrix on the global matrix.
+   * Row coordinate.  This is the position of the data member matrix on the
+   * global matrix.
    */
   size_type row;
   /**
-   * Column coordinate.  This is
-   * the position of the data
-   * member matrix on the global
-   * matrix.
+   * Column coordinate.  This is the position of the data member matrix on the
+   * global matrix.
    */
   size_type column;
 
@@ -373,19 +284,13 @@ public:
 
 private:
   /**
-   * The rwo BlockIndices of the
-   * whole system. Using row(),
-   * this allows us to find the
-   * index of the first row degree
-   * of freedom for this block.
+   * The rwo BlockIndices of the whole system. Using row(), this allows us to
+   * find the index of the first row degree of freedom for this block.
    */
   BlockIndices row_indices;
   /**
-   * The column BlockIndices of the
-   * whole system. Using column(),
-   * this allows us to find the
-   * index of the first column
-   * degree of freedom for this
+   * The column BlockIndices of the whole system. Using column(), this allows
+   * us to find the index of the first column degree of freedom for this
    * block.
    */
   BlockIndices column_indices;
@@ -403,9 +308,9 @@ private:
 
 
 /**
- * A vector of MatrixBlock, which is implemented using shared
- * pointers, in order to allow for copying and rearranging. Each
- * matrix block can be identified by name.
+ * A vector of MatrixBlock, which is implemented using shared pointers, in
+ * order to allow for copying and rearranging. Each matrix block can be
+ * identified by name.
  *
  * @relates MatrixBlock
  * @ingroup vector_valued
@@ -428,37 +333,26 @@ public:
   typedef MatrixBlock<MATRIX> value_type;
 
   /**
-   * Add a new matrix block at the
-   * position <tt>(row,column)</tt>
-   * in the block system.
+   * Add a new matrix block at the position <tt>(row,column)</tt> in the block
+   * system.
    */
   void add(size_type row, size_type column, const std::string &name);
 
   /**
-   * For matrices using a
-   * SparsityPattern, this function
-   * reinitializes each matrix in
-   * the vector with the correct
-   * pattern from the block system.
+   * For matrices using a SparsityPattern, this function reinitializes each
+   * matrix in the vector with the correct pattern from the block system.
    */
   void reinit(const BlockSparsityPattern &sparsity);
 
   /**
    * Clears the object.
    *
-   * Since often only clearing of
-   * the individual matrices is
-   * desired, but not removing the
-   * blocks themselves, there is an
-   * optional argument. If the
-   * argument is missing or @p
-   * false, all matrices will be
-   * mepty, but the size of this
-   * object and the block positions
-   * will not change. If @p
-   * really_clean is @p true, then
-   * the object will contain no
-   * blocks at the end.
+   * Since often only clearing of the individual matrices is desired, but not
+   * removing the blocks themselves, there is an optional argument. If the
+   * argument is missing or @p false, all matrices will be mepty, but the size
+   * of this object and the block positions will not change. If @p
+   * really_clean is @p true, then the object will contain no blocks at the
+   * end.
    */
   void clear (bool really_clean = false);
 
@@ -468,21 +362,17 @@ public:
   std::size_t memory_consumption () const;
 
   /**
-   * Access a constant reference to
-   * the block at position <i>i</i>.
+   * Access a constant reference to the block at position <i>i</i>.
    */
   const value_type &block(size_type i) const;
 
   /**
-   * Access a reference to
-   * the block at position <i>i</i>.
+   * Access a reference to the block at position <i>i</i>.
    */
   value_type &block(size_type i);
 
   /**
-   * Access the matrix at position
-   * <i>i</i> for read and write
-   * access.
+   * Access the matrix at position <i>i</i> for read and write access.
    */
   MATRIX &matrix(size_type i);
 
@@ -498,8 +388,8 @@ public:
 
 /**
  * A vector of MGLevelObject<MatrixBlock>, which is implemented using shared
- * pointers, in order to allow for copying and rearranging. Each
- * matrix block can be identified by name.
+ * pointers, in order to allow for copying and rearranging. Each matrix block
+ * can be identified by name.
  *
  * @relates MatrixBlock
  * @ingroup vector_valued
@@ -520,19 +410,13 @@ public:
    */
   typedef MGLevelObject<MatrixBlock<MATRIX> > value_type;
   /**
-   * Constructor, determining which
-   * matrices should be stored.
+   * Constructor, determining which matrices should be stored.
    *
-   * If <tt>edge_matrices</tt> is
-   * true, then objects for edge
-   * matrices for discretizations
-   * with degrees of freedom on
-   * faces are allocated.
+   * If <tt>edge_matrices</tt> is true, then objects for edge matrices for
+   * discretizations with degrees of freedom on faces are allocated.
    *
-   * If <tt>edge_flux_matrices</tt>
-   * is true, then objects for DG
-   * fluxes on the refinement edge
-   * are allocated.
+   * If <tt>edge_flux_matrices</tt> is true, then objects for DG fluxes on the
+   * refinement edge are allocated.
    */
   MGMatrixBlockVector(const bool edge_matrices = false,
                       const bool edge_flux_matrices = false);
@@ -543,127 +427,98 @@ public:
   unsigned int size () const;
 
   /**
-   * Add a new matrix block at the
-   * position <tt>(row,column)</tt>
-   * in the block system. The third
-   * argument allows to give the
-   * matrix a name for later
+   * Add a new matrix block at the position <tt>(row,column)</tt> in the block
+   * system. The third argument allows to give the matrix a name for later
    * identification.
    */
   void add(size_type row, size_type column, const std::string &name);
 
   /**
-   * For matrices using a
-   * SparsityPattern, this function
-   * reinitializes each matrix in
-   * the vector with the correct
-   * pattern from the block system.
+   * For matrices using a SparsityPattern, this function reinitializes each
+   * matrix in the vector with the correct pattern from the block system.
    *
-   * This function reinitializes
-   * the level matrices.
+   * This function reinitializes the level matrices.
    */
   void reinit_matrix(const MGLevelObject<BlockSparsityPattern> &sparsity);
   /**
-   * For matrices using a
-   * SparsityPattern, this function
-   * reinitializes each matrix in
-   * the vector with the correct
-   * pattern from the block system.
+   * For matrices using a SparsityPattern, this function reinitializes each
+   * matrix in the vector with the correct pattern from the block system.
    *
-   * This function reinitializes
-   * the matrices for degrees of
-   * freedom on the refinement edge.
+   * This function reinitializes the matrices for degrees of freedom on the
+   * refinement edge.
    */
   void reinit_edge(const MGLevelObject<BlockSparsityPattern> &sparsity);
   /**
-   * For matrices using a
-   * SparsityPattern, this function
-   * reinitializes each matrix in
-   * the vector with the correct
-   * pattern from the block system.
+   * For matrices using a SparsityPattern, this function reinitializes each
+   * matrix in the vector with the correct pattern from the block system.
    *
-   * This function reinitializes
-   * the flux matrices over the
-   * refinement edge.
+   * This function reinitializes the flux matrices over the refinement edge.
    */
   void reinit_edge_flux(const MGLevelObject<BlockSparsityPattern> &sparsity);
 
   /**
    * Clears the object.
    *
-   * Since often only clearing of
-   * the individual matrices is
-   * desired, but not removing the
-   * blocks themselves, there is an
-   * optional argument. If the
-   * argument is missing or @p
-   * false, all matrices will be
-   * mepty, but the size of this
-   * object and the block positions
-   * will not change. If @p
-   * really_clean is @p true, then
-   * the object will contain no
-   * blocks at the end.
+   * Since often only clearing of the individual matrices is desired, but not
+   * removing the blocks themselves, there is an optional argument. If the
+   * argument is missing or @p false, all matrices will be mepty, but the size
+   * of this object and the block positions will not change. If @p
+   * really_clean is @p true, then the object will contain no blocks at the
+   * end.
    */
   void clear (bool really_clean = false);
 
   /**
-   * Access a constant reference to
-   * the matrix block at position <i>i</i>.
+   * Access a constant reference to the matrix block at position <i>i</i>.
    */
   const value_type &block(size_type i) const;
 
   /**
-   * Access a reference to
-   * the matrix block at position <i>i</i>.
+   * Access a reference to the matrix block at position <i>i</i>.
    */
   value_type &block(size_type i);
 
   /**
-   * Access a constant reference to
-   * the edge matrix block at position <i>i</i>.
+   * Access a constant reference to the edge matrix block at position
+   * <i>i</i>.
    */
   const value_type &block_in(size_type i) const;
 
   /**
-   * Access a reference to
-   * the edge matrix block at position <i>i</i>.
+   * Access a reference to the edge matrix block at position <i>i</i>.
    */
   value_type &block_in(size_type i);
 
   /**
-   * Access a constant reference to
-   * the edge matrix block at position <i>i</i>.
+   * Access a constant reference to the edge matrix block at position
+   * <i>i</i>.
    */
   const value_type &block_out(size_type i) const;
 
   /**
-   * Access a reference to
-   * the edge matrix block at position <i>i</i>.
+   * Access a reference to the edge matrix block at position <i>i</i>.
    */
   value_type &block_out(size_type i);
 
   /**
-   * Access a constant reference to
-   * the  edge flux matrix block at position <i>i</i>.
+   * Access a constant reference to the  edge flux matrix block at position
+   * <i>i</i>.
    */
   const value_type &block_up(size_type i) const;
 
   /**
-   * Access a reference to
-   * the  edge flux matrix block at position <i>i</i>.
+   * Access a reference to the  edge flux matrix block at position <i>i</i>.
    */
   value_type &block_up(size_type i);
 
   /**
-   * Access a constant reference to
-   * the  edge flux matrix block at position <i>i</i>.
+   * Access a constant reference to the  edge flux matrix block at position
+   * <i>i</i>.
    */
   const value_type &block_down(size_type i) const;
 
   /**
-   * Access a reference to
-   * the edge flux matrix block at position <i>i</i>.
+   * Access a reference to the edge flux matrix block at position <i>i</i>.
    */
   value_type &block_down(size_type i);
 
index ff9c89bc1d465d6c1c8e72d843f0ad2f3280de9c..eed67a2e556cd978bd7c8d3f7a8a1e22becb5663 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * STL conforming iterator for constant
- * and non-constant matrices.
+ * STL conforming iterator for constant and non-constant matrices.
  *
- * This iterator is abstracted from
- * the actual matrix type and can be
- * used for any matrix having the
- * required ACCESSOR type.
+ * This iterator is abstracted from the actual matrix type and can be used for
+ * any matrix having the required ACCESSOR type.
  *
  * @author Guido Kanschat, 2006, based on previous a implementation
  */
@@ -43,33 +40,23 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Typedef for the matrix type
-   * (including constness) we are to
-   * operate on.
+   * Typedef for the matrix type (including constness) we are to operate on.
    */
   typedef typename ACCESSOR::MatrixType MatrixType;
 
   /**
-   * Constructor. Create an
-   * iterator into the matrix
-   * <tt>matrix</tt> for the given
-   * <tt>row</tt> and the
-   * <tt>index</tt> within it.
+   * Constructor. Create an iterator into the matrix <tt>matrix</tt> for the
+   * given <tt>row</tt> and the <tt>index</tt> within it.
    */
   MatrixIterator (MatrixType      *matrix,
                   const size_type  row = 0,
                   const size_type  index = 0);
 
   /**
-   * Copy from another matrix
-   * iterator. Mostly implemented
-   * to allow initialization of a
-   * constant iterator from a non
-   * constant, this function only
-   * requires that a conversion
-   * from the other iterator's
-   * accessor to this accessor
-   * object is possible.
+   * Copy from another matrix iterator. Mostly implemented to allow
+   * initialization of a constant iterator from a non constant, this function
+   * only requires that a conversion from the other iterator's accessor to
+   * this accessor object is possible.
    */
   template <class OtherAccessor>
   MatrixIterator(const MatrixIterator<OtherAccessor> &other);
@@ -95,8 +82,7 @@ public:
   const ACCESSOR *operator-> () const;
 
   /**
-   * Comparison. True, if
-   * both accessors are equal.
+   * Comparison. True, if both accessors are equal.
    */
   bool operator == (const MatrixIterator &) const;
 
@@ -106,35 +92,27 @@ public:
   bool operator != (const MatrixIterator &) const;
 
   /**
-   * Comparison operator. Result is
-   * true if either the first row
-   * number is smaller or if the row
-   * numbers are equal and the first
-   * index is smaller.
+   * Comparison operator. Result is true if either the first row number is
+   * smaller or if the row numbers are equal and the first index is smaller.
    *
-   * This function is only valid if
-   * both iterators point into the same
-   * matrix.
+   * This function is only valid if both iterators point into the same matrix.
    */
   bool operator < (const MatrixIterator &) const;
 
   /**
-   * Comparison operator. Works in the
-   * same way as above operator, just
-   * the other way round.
+   * Comparison operator. Works in the same way as above operator, just the
+   * other way round.
    */
   bool operator > (const MatrixIterator &) const;
 
 private:
   /**
-   * Store an object of the
-   * accessor class.
+   * Store an object of the accessor class.
    */
   ACCESSOR accessor;
 
   /**
-   * Allow other iterators access
-   * to private data.
+   * Allow other iterators access to private data.
    */
   template <class OtherAccessor> friend class MatrixIterator;
 };
index 294231f90dfff8e4b262055079aef1eae6a70651..69880bdb1cb74560754c85626c15469a9a401d4f 100644 (file)
@@ -33,17 +33,16 @@ template<typename number> class SparseMatrix;
 
 
 /**
- * Poor man's matrix product of two quadratic matrices. Stores two
- * quadratic matrices #m1 and #m2 of arbitrary types and implements
- * matrix-vector multiplications for the product
- * <i>M<sub>1</sub>M<sub>2</sub></i> by performing multiplication with
- * both factors consecutively. Because the types of the matrices are
- * opaque (i.e., they can be arbitrary), you can stack products of three
- * or more matrices by making one of the two matrices an object of the
- * current type handles be a ProductMatrix itself.
+ * Poor man's matrix product of two quadratic matrices. Stores two quadratic
+ * matrices #m1 and #m2 of arbitrary types and implements matrix-vector
+ * multiplications for the product <i>M<sub>1</sub>M<sub>2</sub></i> by
+ * performing multiplication with both factors consecutively. Because the
+ * types of the matrices are opaque (i.e., they can be arbitrary), you can
+ * stack products of three or more matrices by making one of the two matrices
+ * an object of the current type handles be a ProductMatrix itself.
  *
- * Here is an example multiplying two different FullMatrix objects:
- * @include product_matrix.cc
+ * Here is an example multiplying two different FullMatrix objects: @include
+ * product_matrix.cc
  *
  * @author Guido Kanschat, 2000, 2001, 2002, 2005
  */
@@ -52,25 +51,20 @@ class ProductMatrix : public PointerMatrixBase<VECTOR>
 {
 public:
   /**
-   * Standard constructor. Matrices
-   * and the memory pool must be
-   * added later using
-   * initialize().
+   * Standard constructor. Matrices and the memory pool must be added later
+   * using initialize().
    */
   ProductMatrix();
 
   /**
-   * Constructor only assigning the
-   * memory pool. Matrices must be
-   * added by reinit() later.
+   * Constructor only assigning the memory pool. Matrices must be added by
+   * reinit() later.
    */
   ProductMatrix(VectorMemory<VECTOR> &mem);
 
   /**
-   * Constructor.  Additionally to
-   * the two constituting matrices, a
-   * memory pool for the auxiliary
-   * vector must be provided.
+   * Constructor.  Additionally to the two constituting matrices, a memory
+   * pool for the auxiliary vector must be provided.
    */
   template <class MATRIX1, class MATRIX2>
   ProductMatrix(const MATRIX1 &m1,
@@ -99,31 +93,26 @@ public:
   void clear();
 
   /**
-   * Matrix-vector product <i>w =
-   * m1 * m2 * v</i>.
+   * Matrix-vector product <i>w = m1 * m2 * v</i>.
    */
   virtual void vmult (VECTOR       &w,
                       const VECTOR &v) const;
 
   /**
-   * Transposed matrix-vector
-   * product <i>w = m2<sup>T</sup> *
-   * m1<sup>T</sup> * v</i>.
+   * Transposed matrix-vector product <i>w = m2<sup>T</sup> * m1<sup>T</sup> *
+   * v</i>.
    */
   virtual void Tvmult (VECTOR       &w,
                        const VECTOR &v) const;
 
   /**
-   * Adding matrix-vector product
-   * <i>w += m1 * m2 * v</i>
+   * Adding matrix-vector product <i>w += m1 * m2 * v</i>
    */
   virtual void vmult_add (VECTOR       &w,
                           const VECTOR &v) const;
 
   /**
-   * Adding, transposed
-   * matrix-vector product <i>w +=
-   * m2<sup>T</sup> *
+   * Adding, transposed matrix-vector product <i>w += m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
    */
   virtual void Tvmult_add (VECTOR       &w,
@@ -150,9 +139,8 @@ private:
 /**
  * A matrix that is the multiple of another matrix.
  *
- * Matrix-vector products of this matrix are composed of those of the
- * original matrix with the vector and then scaling of the result by
- * a constant factor.
+ * Matrix-vector products of this matrix are composed of those of the original
+ * matrix with the vector and then scaling of the result by a constant factor.
  *
  * @author Guido Kanschat, 2007
  */
@@ -161,8 +149,7 @@ class ScaledMatrix : public Subscriptor
 {
 public:
   /**
-   * Constructor leaving an
-   * uninitialized object.
+   * Constructor leaving an uninitialized object.
    */
   ScaledMatrix ();
   /**
@@ -176,8 +163,7 @@ public:
    */
   ~ScaledMatrix ();
   /**
-   * Initialize for use with a new
-   * matrix and factor.
+   * Initialize for use with a new matrix and factor.
    */
   template <class MATRIX>
   void initialize (const MATRIX &M, const double factor);
@@ -193,8 +179,7 @@ public:
   void vmult (VECTOR &w, const VECTOR &v) const;
 
   /**
-   * Tranposed matrix-vector
-   * product.
+   * Tranposed matrix-vector product.
    */
   void Tvmult (VECTOR &w, const VECTOR &v) const;
 
@@ -212,14 +197,13 @@ private:
 
 
 /**
- * Poor man's matrix product of two sparse matrices. Stores two
- * matrices #m1 and #m2 of arbitrary type SparseMatrix and implements
- * matrix-vector multiplications for the product
- * <i>M<sub>1</sub>M<sub>2</sub></i> by performing multiplication with
- * both factors consecutively.
+ * Poor man's matrix product of two sparse matrices. Stores two matrices #m1
+ * and #m2 of arbitrary type SparseMatrix and implements matrix-vector
+ * multiplications for the product <i>M<sub>1</sub>M<sub>2</sub></i> by
+ * performing multiplication with both factors consecutively.
  *
- * The documentation of ProductMatrix applies with exception that
- * these matrices here may be rectangular.
+ * The documentation of ProductMatrix applies with exception that these
+ * matrices here may be rectangular.
  *
  * @author Guido Kanschat, 2000, 2001, 2002, 2005
  */
@@ -233,27 +217,21 @@ public:
   typedef SparseMatrix<number> MatrixType;
 
   /**
-   * Define the type of vectors we
-   * plly this matrix to.
+   * Define the type of vectors we plly this matrix to.
    */
   typedef Vector<vector_number> VectorType;
 
   /**
-   * Constructor.  Additionally to
-   * the two constituting matrices, a
-   * memory pool for the auxiliary
-   * vector must be provided.
+   * Constructor.  Additionally to the two constituting matrices, a memory
+   * pool for the auxiliary vector must be provided.
    */
   ProductSparseMatrix(const MatrixType &m1,
                       const MatrixType &m2,
                       VectorMemory<VectorType> &mem);
 
   /**
-   * Constructor leaving an
-   * uninitialized
-   * matrix. initialize() must be
-   * called, before the matrix can
-   * be used.
+   * Constructor leaving an uninitialized matrix. initialize() must be called,
+   * before the matrix can be used.
    */
   ProductSparseMatrix();
 
@@ -265,31 +243,26 @@ public:
   void clear();
 
   /**
-   * Matrix-vector product <i>w =
-   * m1 * m2 * v</i>.
+   * Matrix-vector product <i>w = m1 * m2 * v</i>.
    */
   virtual void vmult (VectorType       &w,
                       const VectorType &v) const;
 
   /**
-   * Transposed matrix-vector
-   * product <i>w = m2<sup>T</sup> *
-   * m1<sup>T</sup> * v</i>.
+   * Transposed matrix-vector product <i>w = m2<sup>T</sup> * m1<sup>T</sup> *
+   * v</i>.
    */
   virtual void Tvmult (VectorType       &w,
                        const VectorType &v) const;
 
   /**
-   * Adding matrix-vector product
-   * <i>w += m1 * m2 * v</i>
+   * Adding matrix-vector product <i>w += m1 * m2 * v</i>
    */
   virtual void vmult_add (VectorType       &w,
                           const VectorType &v) const;
 
   /**
-   * Adding, transposed
-   * matrix-vector product <i>w +=
-   * m2<sup>T</sup> *
+   * Adding, transposed matrix-vector product <i>w += m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
    */
   virtual void Tvmult_add (VectorType       &w,
@@ -314,20 +287,18 @@ private:
 
 
 /**
- * Mean value filter.  The vmult() functions of this matrix filter
- * out mean values of the vector.  If the vector is of type
- * BlockVector, then an additional parameter selects a single
- * component for this operation.
+ * Mean value filter.  The vmult() functions of this matrix filter out mean
+ * values of the vector.  If the vector is of type BlockVector, then an
+ * additional parameter selects a single component for this operation.
  *
- * In mathematical terms, this class acts as if it was the matrix
- * $I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is
- * a vector of size $n$ that has only ones as its entries. Thus,
- * taking the dot product between a vector $\mathbf v$ and
- * $\frac 1n {\mathbf 1}_n$ yields the <i>mean value</i> of the entries
- * of ${\mathbf v}$. Consequently,
- * $ \left[I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v
- * = \mathbf v - \left[\frac 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$
- * subtracts from every vector element the mean value of all elements.
+ * In mathematical terms, this class acts as if it was the matrix $I-\frac
+ * 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is a vector of size
+ * $n$ that has only ones as its entries. Thus, taking the dot product between
+ * a vector $\mathbf v$ and $\frac 1n {\mathbf 1}_n$ yields the <i>mean
+ * value</i> of the entries of ${\mathbf v}$. Consequently, $ \left[I-\frac
+ * 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v = \mathbf v - \left[\frac
+ * 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$ subtracts from every
+ * vector element the mean value of all elements.
  *
  * @author Guido Kanschat, 2002, 2003
  */
@@ -340,8 +311,7 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Constructor, optionally
-   * selecting a component.
+   * Constructor, optionally selecting a component.
    */
   MeanValueFilter(const size_type component = numbers::invalid_size_type);
 
@@ -358,34 +328,30 @@ public:
   void filter (BlockVector<number> &v) const;
 
   /**
-   * Return the source vector with
-   * subtracted mean value.
+   * Return the source vector with subtracted mean value.
    */
   template <typename number>
   void vmult (Vector<number> &dst,
               const Vector<number> &src) const;
 
   /**
-   * Add source vector with
-   * subtracted mean value to dest.
+   * Add source vector with subtracted mean value to dest.
    */
   template <typename number>
   void vmult_add (Vector<number> &dst,
                   const Vector<number> &src) const;
 
   /**
-   * Return the source vector with
-   * subtracted mean value in
-   * selected component.
+   * Return the source vector with subtracted mean value in selected
+   * component.
    */
   template <typename number>
   void vmult (BlockVector<number> &dst,
               const BlockVector<number> &src) const;
 
   /**
-   * Add a soruce to dest, where
-   * the mean value in the selected
-   * component is subtracted.
+   * Add a soruce to dest, where the mean value in the selected component is
+   * subtracted.
    */
   template <typename number>
   void vmult_add (BlockVector<number> &dst,
@@ -414,26 +380,23 @@ private:
 
 
 /**
- * Objects of this type represent the inverse of a matrix as
- * computed approximately by using the SolverRichardson
- * iterative solver. In other words, if you set up an object
- * of the current type for a matrix $A$, then calling the
- * vmult() function with arguments $v,w$ amounts to setting
- * $w=A^{-1}v$ by solving the linear system $Aw=v$ using the
- * Richardson solver with a preconditioner that can be chosen. Similarly,
- * this class allows to also multiple with the transpose of the
- * inverse (i.e., the inverse of the transpose) using the function
- * SolverRichardson::Tsolve().
+ * Objects of this type represent the inverse of a matrix as computed
+ * approximately by using the SolverRichardson iterative solver. In other
+ * words, if you set up an object of the current type for a matrix $A$, then
+ * calling the vmult() function with arguments $v,w$ amounts to setting
+ * $w=A^{-1}v$ by solving the linear system $Aw=v$ using the Richardson solver
+ * with a preconditioner that can be chosen. Similarly, this class allows to
+ * also multiple with the transpose of the inverse (i.e., the inverse of the
+ * transpose) using the function SolverRichardson::Tsolve().
  *
- * The functions vmult() and Tvmult() approximate the inverse
- * iteratively starting with the vector <tt>dst</tt>. Functions
- * vmult_add() and Tvmult_add() start the iteration with a zero
- * vector. All of the matrix-vector multiplication functions
- * expect that the Richardson solver with the given preconditioner
- * actually converge. If the Richardson solver does not converge
- * within the specified number of iterations, the exception that will
- * result in the solver will simply be propagated to the caller of
- * the member function of the current class.
+ * The functions vmult() and Tvmult() approximate the inverse iteratively
+ * starting with the vector <tt>dst</tt>. Functions vmult_add() and
+ * Tvmult_add() start the iteration with a zero vector. All of the matrix-
+ * vector multiplication functions expect that the Richardson solver with the
+ * given preconditioner actually converge. If the Richardson solver does not
+ * converge within the specified number of iterations, the exception that will
+ * result in the solver will simply be propagated to the caller of the member
+ * function of the current class.
  *
  * @note A more powerful version of this class is provided by the
  * IterativeInverse class.
@@ -449,24 +412,18 @@ class InverseMatrixRichardson : public Subscriptor
 {
 public:
   /**
-   * Constructor, initializing the
-   * solver with a control and
-   * memory object. The inverted
-   * matrix and the preconditioner
-   * are added in initialize().
+   * Constructor, initializing the solver with a control and memory object.
+   * The inverted matrix and the preconditioner are added in initialize().
    */
   InverseMatrixRichardson (SolverControl &control,
                            VectorMemory<VECTOR> &mem);
   /**
-   * Since we use two pointers, we
-   * must implement a destructor.
+   * Since we use two pointers, we must implement a destructor.
    */
   ~InverseMatrixRichardson();
 
   /**
-   * Initialization
-   * function. Provide a solver
-   * object, a matrix, and another
+   * Initialization function. Provide a solver object, a matrix, and another
    * preconditioner for this.
    */
   template <class MATRIX, class PRECONDITION>
@@ -474,8 +431,7 @@ public:
                    const PRECONDITION &);
 
   /**
-   * Access to the SolverControl
-   * object used by the solver.
+   * Access to the SolverControl object used by the solver.
    */
   SolverControl &control() const;
   /**
@@ -500,8 +456,7 @@ public:
 
 private:
   /**
-   * A reference to the provided
-   * VectorMemory object.
+   * A reference to the provided VectorMemory object.
    */
   VectorMemory<VECTOR> &mem;
 
index 65e2bd111ce1eab90ee8177389e6c0be39f1f083..9f5f5ff34959f9516c90f74e2208b5bed9e66d0e 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Output a matrix in graphical form using the generic format
- * independent output routines of the base class. The matrix is
- * converted into a list of patches on a 2d domain where the height is
- * given by the elements of the matrix. The functions of the base
- * class can then write this "mountain representation" of the matrix
- * in a variety of graphical output formats. The coordinates of the
- * matrix output are that the columns run with increasing x-axis, as
- * usual, starting from zero, while the rows run into the negative
+ * Output a matrix in graphical form using the generic format independent
+ * output routines of the base class. The matrix is converted into a list of
+ * patches on a 2d domain where the height is given by the elements of the
+ * matrix. The functions of the base class can then write this "mountain
+ * representation" of the matrix in a variety of graphical output formats. The
+ * coordinates of the matrix output are that the columns run with increasing
+ * x-axis, as usual, starting from zero, while the rows run into the negative
  * y-axis, also starting from zero. Note that due to some internal
- * restrictions, this class can only output one matrix at a time,
- * i.e. it can not take advantage of the multiple dataset capabilities
- * of the base class.
+ * restrictions, this class can only output one matrix at a time, i.e. it can
+ * not take advantage of the multiple dataset capabilities of the base class.
  *
  * A typical usage of this class would be as follows:
  * @code
@@ -48,24 +46,23 @@ DEAL_II_NAMESPACE_OPEN
  *    matrix_out.build_patches (M, "M");
  *    matrix_out.write_gnuplot (out);
  * @endcode
- * Of course, you can as well choose a different graphical output
- * format. Also, this class supports any matrix, not only of type
- * FullMatrix, as long as it satisfies a number of requirements,
- * stated with the member functions of this class.
+ * Of course, you can as well choose a different graphical output format.
+ * Also, this class supports any matrix, not only of type FullMatrix, as long
+ * as it satisfies a number of requirements, stated with the member functions
+ * of this class.
  *
- * The generation of patches through the build_patches() function
- * can be modified by giving it an object holding certain flags. See
- * the documentation of the members of the Options class for a
- * description of these flags.
+ * The generation of patches through the build_patches() function can be
+ * modified by giving it an object holding certain flags. See the
+ * documentation of the members of the Options class for a description of
+ * these flags.
  *
  *
  * <h3>Internals</h3>
  *
- * To avoid a compiler error in Sun's Forte compiler, we derive
- * privately from DataOutBase. Since the base class
- * DataOutInterface does so as well, this does no harm, but
- * calms the compiler which is suspecting an access control conflict
- * otherwise. Testcase here:
+ * To avoid a compiler error in Sun's Forte compiler, we derive privately from
+ * DataOutBase. Since the base class DataOutInterface does so as well, this
+ * does no harm, but calms the compiler which is suspecting an access control
+ * conflict otherwise. Testcase here:
  * @code
  *    template <typename T> class V {};
  *
@@ -98,55 +95,36 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Class holding various
-   * variables which are used to
-   * modify the output of the
-   * MatrixOut class.
+   * Class holding various variables which are used to modify the output of
+   * the MatrixOut class.
    */
   struct Options
   {
     /**
-     * If @p true, only show the
-     * absolute values of the
-     * matrix entries, rather
-     * than their true values
-     * including the
-     * sign. Default value is
-     * @p false.
+     * If @p true, only show the absolute values of the matrix entries, rather
+     * than their true values including the sign. Default value is @p false.
      */
     bool         show_absolute_values;
 
     /**
-     * If larger than one, do not
-     * show each element of the
-     * matrix, but rather an
-     * average over a number of
-     * entries. The number of
-     * output patches is
-     * accordingly smaller. This
-     * flag determines how large
-     * each shown block shall be
-     * (in rows/columns). For
-     * example, if it is two,
-     * then always four entries
-     * are collated into one.
+     * If larger than one, do not show each element of the matrix, but rather
+     * an average over a number of entries. The number of output patches is
+     * accordingly smaller. This flag determines how large each shown block
+     * shall be (in rows/columns). For example, if it is two, then always four
+     * entries are collated into one.
      *
      * Default value is one.
      */
     unsigned int block_size;
 
     /**
-     * If true, plot
-     * discontinuous patches, one
-     * for each entry.
+     * If true, plot discontinuous patches, one for each entry.
      */
     bool discontinuous;
 
     /**
-     * Default constructor. Set
-     * all elements of this
-     * structure to their default
-     * values.
+     * Default constructor. Set all elements of this structure to their
+     * default values.
      */
     Options (const bool         show_absolute_values = false,
              const unsigned int block_size           = 1,
@@ -154,47 +132,26 @@ public:
   };
 
   /**
-   * Destructor. Declared in order
-   * to make it virtual.
+   * Destructor. Declared in order to make it virtual.
    */
   virtual ~MatrixOut ();
 
   /**
-   * Generate a list of patches
-   * from the given matrix and use
-   * the given string as the name
-   * of the data set upon writing
-   * to a file. Once patches have
-   * been built, you can use the
-   * functions of the base class to
-   * write the data into a files,
-   * using one of the supported
-   * output formats.
+   * Generate a list of patches from the given matrix and use the given string
+   * as the name of the data set upon writing to a file. Once patches have
+   * been built, you can use the functions of the base class to write the data
+   * into a files, using one of the supported output formats.
    *
-   * You may give a structure
-   * holding various options. See
-   * the description of the fields
-   * of this structure for more
-   * information.
+   * You may give a structure holding various options. See the description of
+   * the fields of this structure for more information.
    *
-   * Note that this function
-   * requires that we can extract
-   * elements of the matrix, which
-   * is done using the
-   * get_element() function
-   * declared below. By adding
-   * specializations, you can
-   * extend this class to other
-   * matrix classes which are not
-   * presently
-   * supported. Furthermore, we
-   * need to be able to extract the
-   * size of the matrix, for which
-   * we assume that the matrix type
-   * offers member functions
-   * <tt>m()</tt> and <tt>n()</tt>, which
-   * return the number of rows and
-   * columns, respectively.
+   * Note that this function requires that we can extract elements of the
+   * matrix, which is done using the get_element() function declared below. By
+   * adding specializations, you can extend this class to other matrix classes
+   * which are not presently supported. Furthermore, we need to be able to
+   * extract the size of the matrix, for which we assume that the matrix type
+   * offers member functions <tt>m()</tt> and <tt>n()</tt>, which return the
+   * number of rows and columns, respectively.
    */
   template <class Matrix>
   void build_patches (const Matrix      &matrix,
@@ -204,58 +161,44 @@ public:
 private:
 
   /**
-   * Abbreviate the somewhat
-   * lengthy name for the dealii::DataOutBase::Patch
+   * Abbreviate the somewhat lengthy name for the dealii::DataOutBase::Patch
    * class.
    *
-   * Note that we have to indicate the
-   * global scope in front of DataOutBase,
-   * since otherwise the C++ rules specify
-   * that this here indicates the
-   * DataOutBase base class of this
-   * class. Since that is a private base
-   * class, we cannot access its members,
-   * and so access to the local Patch type
-   * would be forbidden.
+   * Note that we have to indicate the global scope in front of DataOutBase,
+   * since otherwise the C++ rules specify that this here indicates the
+   * DataOutBase base class of this class. Since that is a private base class,
+   * we cannot access its members, and so access to the local Patch type would
+   * be forbidden.
    */
   typedef dealii::DataOutBase::Patch<2,2> Patch;
 
   /**
-   * This is a list of patches that
-   * is created each time
-   * build_patches() is
-   * called. These patches are used
-   * in the output routines of the
-   * base classes.
+   * This is a list of patches that is created each time build_patches() is
+   * called. These patches are used in the output routines of the base
+   * classes.
    */
   std::vector<Patch> patches;
 
   /**
-   * Name of the matrix to be
-   * written.
+   * Name of the matrix to be written.
    */
   std::string name;
 
   /**
-   * Function by which the base
-   * class's functions get to know
-   * what patches they shall write
-   * to a file.
+   * Function by which the base class's functions get to know what patches
+   * they shall write to a file.
    */
   virtual const std::vector<Patch> &
   get_patches () const;
 
   /**
-   * Virtual function through which
-   * the names of data sets are
-   * obtained by the output
-   * functions of the base class.
+   * Virtual function through which the names of data sets are obtained by the
+   * output functions of the base class.
    */
   virtual std::vector<std::string> get_dataset_names () const;
 
   /**
-   * Return the element with given
-   * indices of a sparse matrix.
+   * Return the element with given indices of a sparse matrix.
    */
   template <typename number>
   static double get_element (const SparseMatrix<number> &matrix,
@@ -263,9 +206,7 @@ private:
                              const size_type             j);
 
   /**
-   * Return the element with given
-   * indices of a block sparse
-   * matrix.
+   * Return the element with given indices of a block sparse matrix.
    */
   template <typename number>
   static double get_element (const BlockSparseMatrix<number> &matrix,
@@ -273,11 +214,8 @@ private:
                              const size_type                  j);
 
   /**
-   * Return the element with given
-   * indices from any matrix type
-   * for which no specialization of
-   * this function was declared
-   * above. This will call
+   * Return the element with given indices from any matrix type for which no
+   * specialization of this function was declared above. This will call
    * <tt>operator()</tt> on the matrix.
    */
   template <class Matrix>
@@ -286,17 +224,11 @@ private:
                              const size_type     j);
 
   /**
-   * Get the value of the matrix at
-   * gridpoint <tt>(i,j)</tt>. Depending
-   * on the given flags, this can
-   * mean different things, for
-   * example if only absolute
-   * values shall be shown then the
-   * absolute value of the matrix
-   * entry is taken. If the block
-   * size is larger than one, then
-   * an average of several matrix
-   * entries is taken.
+   * Get the value of the matrix at gridpoint <tt>(i,j)</tt>. Depending on the
+   * given flags, this can mean different things, for example if only absolute
+   * values shall be shown then the absolute value of the matrix entry is
+   * taken. If the block size is larger than one, then an average of several
+   * matrix entries is taken.
    */
   template <class Matrix>
   static double get_gridpoint_value (const Matrix       &matrix,
index 2ca70988143b73c8ce06aa6d11138b8baf9ffb94..7ae703425128e1c84b0eb23fab3acb15f1990d09 100644 (file)
@@ -44,14 +44,14 @@ namespace parallel
 
 
     /**
-     * An implementation of block vectors based on distribued deal.II
-     * vectors. While the base class provides for most of the interface, this
-     * class handles the actual allocation of vectors and provides functions that
+     * An implementation of block vectors based on distribued deal.II vectors.
+     * While the base class provides for most of the interface, this class
+     * handles the actual allocation of vectors and provides functions that
      * are specific to the underlying vector type.
      *
-     * @note Instantiations for this template are provided for <tt>@<float@> and
-     * @<double@></tt>; others can be generated in application programs (see the
-     * section on @ref Instantiations in the manual).
+     * @note Instantiations for this template are provided for <tt>@<float@>
+     * and @<double@></tt>; others can be generated in application programs
+     * (see the section on @ref Instantiations in the manual).
      *
      * @see @ref GlossBlockLA "Block (linear algebra)"
      * @author Katharina Kormann, Martin Kronbichler, 2011
@@ -84,14 +84,14 @@ namespace parallel
       typedef typename BaseClass::const_iterator  const_iterator;
 
       /**
-       *  Constructor. There are three ways to use this constructor. First,
-       *  without any arguments, it generates an object with no blocks. Given
-       *  one argument, it initializes <tt>num_blocks</tt> blocks, but these
-       *  blocks have size zero. The third variant finally initializes all
-       *  blocks to the same size <tt>block_size</tt>.
+       * Constructor. There are three ways to use this constructor. First,
+       * without any arguments, it generates an object with no blocks. Given
+       * one argument, it initializes <tt>num_blocks</tt> blocks, but these
+       * blocks have size zero. The third variant finally initializes all
+       * blocks to the same size <tt>block_size</tt>.
        *
-       *  Confer the other constructor further down if you intend to use
-       *  blocks of different sizes.
+       * Confer the other constructor further down if you intend to use blocks
+       * of different sizes.
        */
       explicit BlockVector (const size_type num_blocks = 0,
                             const size_type block_size = 0);
@@ -128,8 +128,8 @@ namespace parallel
       BlockVector (const std::vector<size_type> &block_sizes);
 
       /**
-       * Construct a block vector with an IndexSet for the local range
-       * and ghost entries for each block.
+       * Construct a block vector with an IndexSet for the local range and
+       * ghost entries for each block.
        */
       BlockVector (const std::vector<IndexSet> &local_ranges,
                    const std::vector<IndexSet> &ghost_indices,
@@ -304,10 +304,9 @@ namespace parallel
       bool has_ghost_elements() const;
 
       /**
-       * Return whether the vector contains only elements with value
-       * zero. This function is mainly for internal consistency checks and
-       * should seldom be used when not in debug mode since it uses quite some
-       * time.
+       * Return whether the vector contains only elements with value zero.
+       * This function is mainly for internal consistency checks and should
+       * seldom be used when not in debug mode since it uses quite some time.
        */
       bool all_zero () const;
 
@@ -400,8 +399,8 @@ namespace parallel
       /**
        * Scale each element of the vector by the given factor.
        *
-       * This function is deprecated and will be removed in a future
-       * version. Use <tt>operator *=</tt> and <tt>operator /=</tt> instead.
+       * This function is deprecated and will be removed in a future version.
+       * Use <tt>operator *=</tt> and <tt>operator /=</tt> instead.
        *
        * @deprecated Use <tt>operator*=</tt> instead.
        */
@@ -433,8 +432,10 @@ namespace parallel
        */
       void swap (BlockVector<Number> &v);
 
-      /** @addtogroup Exceptions
-       * @{ */
+      /**
+       * @addtogroup Exceptions
+       * @{
+       */
 
       /**
        * Exception
@@ -1007,9 +1008,9 @@ namespace parallel
 } // end of namespace parallel
 
 /**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
  *
  * @relates BlockVector
  * @author Katharina Kormann, Martin Kronbichler, 2011
index 8c4ab5c581be6ade515ca6fae6bd2ffe4e61ff61..4e1ed76f197235f6eda1bb1a52c80f15795c83a0 100644 (file)
@@ -70,59 +70,55 @@ namespace parallel
      * similar to the standard ::dealii::Vector class in deal.II, with the
      * exception that storage is distributed with MPI.
      *
-     * The vector is designed for the following scheme of parallel partitioning:
-     * - The indices held by individual processes (locally owned part) in the
-     *   MPI parallelization form a contiguous range
-     *   <code>[my_first_index,my_last_index)</code>.
-     * - Ghost indices residing on arbitrary positions of other processors are
-     *   allowed. It is in general more efficient if ghost indices are
-     *   clustered, since they are stored as a set of intervals. The
-     *   communication pattern of the ghost indices is determined when calling
-     *   the function <code>reinit (locally_owned, ghost_indices,
-     *   communicator)</code>, and retained until the partitioning is changed
-     *   again. This allows for efficient parallel communication of indices. In
-     *   particular, it stores the communication pattern, rather than having
-     *   to compute it again for every communication. (For more information on
-     *   ghost vectors, see also the
-     *   @ref GlossGhostedVector "glossary entry on vectors with ghost elements".)
-     * - Besides the usual global access operator () it is also possible to
-     *   access vector entries in the local index space with the function @p
-     *   local_element(). Locally owned indices are placed first, [0,
-     *   local_size()), and then all ghost indices follow after them
-     *   contiguously, [local_size(), local_size()+n_ghost_entries()).
+     * The vector is designed for the following scheme of parallel
+     * partitioning: - The indices held by individual processes (locally owned
+     * part) in the MPI parallelization form a contiguous range
+     * <code>[my_first_index,my_last_index)</code>. - Ghost indices residing
+     * on arbitrary positions of other processors are allowed. It is in
+     * general more efficient if ghost indices are clustered, since they are
+     * stored as a set of intervals. The communication pattern of the ghost
+     * indices is determined when calling the function <code>reinit
+     * (locally_owned, ghost_indices, communicator)</code>, and retained until
+     * the partitioning is changed again. This allows for efficient parallel
+     * communication of indices. In particular, it stores the communication
+     * pattern, rather than having to compute it again for every
+     * communication. (For more information on ghost vectors, see also the
+     * @ref GlossGhostedVector "glossary entry on vectors with ghost
+     * elements".) - Besides the usual global access operator () it is also
+     * possible to access vector entries in the local index space with the
+     * function @p local_element(). Locally owned indices are placed first,
+     * [0, local_size()), and then all ghost indices follow after them
+     * contiguously, [local_size(), local_size()+n_ghost_entries()).
      *
-     * Functions related to parallel functionality:
-     * - The function <code>compress()</code> goes through the data associated
-     *   with ghost indices and communicates it to the owner process, which can
-     *   then add it to the correct position. This can be used e.g. after
-     *   having run an assembly routine involving ghosts that fill this vector.
-     *   Note that the @p insert mode of @p compress() does not set the
-     *   elements included in ghost entries but simply discards them, assuming
-     *   that the owning processor has set them to the desired value already.
-     *   (See also the @ref GlossCompress "glossary entry on compress".)
-     * - The <code>update_ghost_values()</code> function imports the data from
-     *   the owning processor to the ghost indices in order to provide read
-     *   access to the data associated with ghosts.
-     * - It is possible to split the above functions into two phases, where
-     *   the first initiates the communication and the second one finishes
-     *   it. These functions can be used to overlap communication with
-     *   computations in other parts of the code.
-     * - Of course, reduction operations (like norms) make use of collective
-     *   all-to-all MPI communications.
+     * Functions related to parallel functionality: - The function
+     * <code>compress()</code> goes through the data associated with ghost
+     * indices and communicates it to the owner process, which can then add it
+     * to the correct position. This can be used e.g. after having run an
+     * assembly routine involving ghosts that fill this vector. Note that the
+     * @p insert mode of @p compress() does not set the elements included in
+     * ghost entries but simply discards them, assuming that the owning
+     * processor has set them to the desired value already. (See also the @ref
+     * GlossCompress "glossary entry on compress".) - The
+     * <code>update_ghost_values()</code> function imports the data from the
+     * owning processor to the ghost indices in order to provide read access
+     * to the data associated with ghosts. - It is possible to split the above
+     * functions into two phases, where the first initiates the communication
+     * and the second one finishes it. These functions can be used to overlap
+     * communication with computations in other parts of the code. - Of
+     * course, reduction operations (like norms) make use of collective all-
+     * to-all MPI communications.
      *
      * This vector can take two different states with respect to ghost
-     * elements:
-     * - After creation and whenever zero_out_ghosts() is called (or
-     *   <code>operator = (0.)</code>), the vector does only allow writing
-     *   into ghost elements but not reading from ghost elements.
-     * - After a call to update_ghost_values(), the vector does not allow
-     *   writing into ghost elements but only reading from them. This is in
-     *   order to avoid undesired ghost data artifacts when calling compress()
-     *   after modifying some vector entries.
-     * The current status of the ghost entries (read mode or write mode) can
-     * be queried by the method has_ghost_elements(), which returns
-     * <code>true</code> exactly when ghost elements have been updated and
-     * <code>false</code> otherwise, irrespective of the actual number of
+     * elements: - After creation and whenever zero_out_ghosts() is called (or
+     * <code>operator = (0.)</code>), the vector does only allow writing into
+     * ghost elements but not reading from ghost elements. - After a call to
+     * update_ghost_values(), the vector does not allow writing into ghost
+     * elements but only reading from them. This is in order to avoid
+     * undesired ghost data artifacts when calling compress() after modifying
+     * some vector entries. The current status of the ghost entries (read mode
+     * or write mode) can be queried by the method has_ghost_elements(), which
+     * returns <code>true</code> exactly when ghost elements have been updated
+     * and <code>false</code> otherwise, irrespective of the actual number of
      * ghost entries in the vector layout (for that information, use
      * n_ghost_entries() instead).
      *
@@ -155,15 +151,14 @@ namespace parallel
       typedef typename numbers::NumberTraits<Number>::real_type real_type;
 
       /**
-       * A variable that indicates whether this vector
-       * supports distributed data storage. If true, then
-       * this vector also needs an appropriate compress()
-       * function that allows communicating recent set or
-       * add operations to individual elements to be communicated
-       * to other processors.
+       * A variable that indicates whether this vector supports distributed
+       * data storage. If true, then this vector also needs an appropriate
+       * compress() function that allows communicating recent set or add
+       * operations to individual elements to be communicated to other
+       * processors.
        *
-       * For the current class, the variable equals
-       * true, since it does support parallel data storage.
+       * For the current class, the variable equals true, since it does
+       * support parallel data storage.
        */
       static const bool supports_distributed_data = true;
 
@@ -364,12 +359,11 @@ namespace parallel
        * both the element on the ghost site as well as the owning site), this
        * operation makes the assumption that all data is set correctly on the
        * owning processor. Upon call of compress(VectorOperation::insert), all
-       * ghost entries are thus simply zeroed out (using
-       * zero_ghost_values()). In debug mode, a check is performed for whether
-       * the data set is actually consistent between processors,
-       * i.e., whenever a non-zero ghost element is found, it is compared to
-       * the value on the owning processor and an exception is thrown if these
-       * elements do not agree.
+       * ghost entries are thus simply zeroed out (using zero_ghost_values()).
+       * In debug mode, a check is performed for whether the data set is
+       * actually consistent between processors, i.e., whenever a non-zero
+       * ghost element is found, it is compared to the value on the owning
+       * processor and an exception is thrown if these elements do not agree.
        */
       void compress (::dealii::VectorOperation::values operation);
 
@@ -401,10 +395,10 @@ namespace parallel
       void update_ghost_values () const;
 
       /**
-       * Initiates communication for the @p compress() function with
-       * non-blocking communication. This function does not wait for the
-       * transfer to finish, in order to allow for other computations during
-       * the time it takes until all data arrives.
+       * Initiates communication for the @p compress() function with non-
+       * blocking communication. This function does not wait for the transfer
+       * to finish, in order to allow for other computations during the time
+       * it takes until all data arrives.
        *
        * Before the data is actually exchanged, the function must be followed
        * by a call to @p compress_finish().
@@ -421,9 +415,8 @@ namespace parallel
        * For all requests that have been initiated in compress_start, wait for
        * the communication to finish. Once it is finished, add or set the data
        * (depending on the flag operation) to the respective positions in the
-       * owning processor, and clear the contents in the ghost data
-       * fields. The meaning of this argument is the same as in
-       * compress().
+       * owning processor, and clear the contents in the ghost data fields.
+       * The meaning of this argument is the same as in compress().
        *
        * This function should be called exactly once per vector after calling
        * compress_start, otherwise the result is undefined. In particular, it
@@ -489,8 +482,8 @@ namespace parallel
       bool has_ghost_elements() const;
 
       /**
-       * Return whether the vector contains only elements with value
-       * zero. This is a collective operation. This function is expensive, because
+       * Return whether the vector contains only elements with value zero.
+       * This is a collective operation. This function is expensive, because
        * potentially all elements have to be checked.
        */
       bool all_zero () const;
@@ -607,15 +600,14 @@ namespace parallel
       bool in_local_range (const size_type global_index) const;
 
       /**
-       * Return an index set that describes which elements of this vector
-       * are owned by the current processor. Note that this index set does
-       * not include elements this vector may store locally as ghost
-       * elements but that are in fact owned by another processor.
-       * As a consequence, the index sets returned on different
-       * processors if this is a distributed vector will form disjoint
-       * sets that add up to the complete index set.
-       * Obviously, if a vector is created on only one processor, then
-       * the result would satisfy
+       * Return an index set that describes which elements of this vector are
+       * owned by the current processor. Note that this index set does not
+       * include elements this vector may store locally as ghost elements but
+       * that are in fact owned by another processor. As a consequence, the
+       * index sets returned on different processors if this is a distributed
+       * vector will form disjoint sets that add up to the complete index set.
+       * Obviously, if a vector is created on only one processor, then the
+       * result would satisfy
        * @code
        *   vec.locally_owned_elements() == complete_index_set (vec.size())
        * @endcode
@@ -716,22 +708,18 @@ namespace parallel
       Number &operator [] (const size_type global_index);
 
       /**
-       * A collective get operation: instead
-       * of getting individual elements of a
-       * vector, this function allows to get
-       * a whole set of elements at once. The
-       * indices of the elements to be read
-       * are stated in the first argument,
-       * the corresponding values are returned in the
-       * second.
+       * A collective get operation: instead of getting individual elements of
+       * a vector, this function allows to get a whole set of elements at
+       * once. The indices of the elements to be read are stated in the first
+       * argument, the corresponding values are returned in the second.
        */
       template <typename OtherNumber>
       void extract_subvector_to (const std::vector<size_type> &indices,
                                  std::vector<OtherNumber> &values) const;
 
       /**
-       * Just as the above, but with pointers.
-       * Useful in minimizing copying of data around.
+       * Just as the above, but with pointers. Useful in minimizing copying of
+       * data around.
        */
       template <typename ForwardIterator, typename OutputIterator>
       void extract_subvector_to (ForwardIterator          indices_begin,
@@ -749,8 +737,8 @@ namespace parallel
       Number local_element (const size_type local_index) const;
 
       /**
-       * Read and write access to the data field specified by @p
-       * local_index. Locally owned indices can be accessed with indices
+       * Read and write access to the data field specified by @p local_index.
+       * Locally owned indices can be accessed with indices
        * <code>[0,local_size)</code>, and ghost indices with indices
        * <code>[local_size,local_size+n_ghosts]</code>.
        *
@@ -1090,12 +1078,12 @@ namespace parallel
 
 #ifdef DEAL_II_WITH_MPI
       /**
-       * A vector that collects all requests from @p compress()
-       * operations. This class uses persistent MPI communicators, i.e., the
-       * communication channels are stored during successive calls to a given
-       * function. This reduces the overhead involved with setting up the MPI
-       * machinery, but it does not remove the need for a receive operation to
-       * be posted before the data can actually be sent.
+       * A vector that collects all requests from @p compress() operations.
+       * This class uses persistent MPI communicators, i.e., the communication
+       * channels are stored during successive calls to a given function. This
+       * reduces the overhead involved with setting up the MPI machinery, but
+       * it does not remove the need for a receive operation to be posted
+       * before the data can actually be sent.
        */
       std::vector<MPI_Request>   compress_requests;
 
@@ -2384,9 +2372,9 @@ namespace parallel
 
 
 /**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
  *
  * @relates Vector
  * @author Katharina Kormann, Martin Kronbichler, 2011
index e8f737bf421a1283e8df5846ac6532f449ae40b2..51c9e4c8ca6dd80299ca418c5bde7dbe0165f01d 100644 (file)
@@ -41,45 +41,42 @@ namespace PETScWrappers
    */
 
   /**
-   * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class. This
-   * class implements the functions that are specific to the PETSc SparseMatrix
-   * base objects for a blocked sparse matrix, and leaves the actual work
-   * relaying most of the calls to the individual blocks to the functions
-   * implemented in the base class. See there also for a description of when
-   * this class is useful.
+   * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class.
+   * This class implements the functions that are specific to the PETSc
+   * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+   * actual work relaying most of the calls to the individual blocks to the
+   * functions implemented in the base class. See there also for a description
+   * of when this class is useful.
    *
    * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices do
    * not have external objects for the sparsity patterns. Thus, one does not
-   * determine the size of the individual blocks of a block matrix of this type
-   * by attaching a block sparsity pattern, but by calling reinit() to set the
-   * number of blocks and then by setting the size of each block separately. In
-   * order to fix the data structures of the block matrix, it is then necessary
-   * to let it know that we have changed the sizes of the underlying
-   * matrices. For this, one has to call the collect_sizes() function, for much
-   * the same reason as is documented with the BlockSparsityPattern class.
+   * determine the size of the individual blocks of a block matrix of this
+   * type by attaching a block sparsity pattern, but by calling reinit() to
+   * set the number of blocks and then by setting the size of each block
+   * separately. In order to fix the data structures of the block matrix, it
+   * is then necessary to let it know that we have changed the sizes of the
+   * underlying matrices. For this, one has to call the collect_sizes()
+   * function, for much the same reason as is documented with the
+   * BlockSparsityPattern class.
    *
-   * @ingroup Matrix1
-   * @see @ref GlossBlockLA "Block (linear algebra)"
+   * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
    * @author Wolfgang Bangerth, 2004
    */
   class BlockSparseMatrix : public BlockMatrixBase<PETScWrappers::SparseMatrix>
   {
   public:
     /**
-     * Typedef the base class for simpler
-     * access to its own typedefs.
+     * Typedef the base class for simpler access to its own typedefs.
      */
     typedef BlockMatrixBase<SparseMatrix> BaseClass;
 
     /**
-     * Typedef the type of the underlying
-     * matrix.
+     * Typedef the type of the underlying matrix.
      */
     typedef BaseClass::BlockType  BlockType;
 
     /**
-     * Import the typedefs from the base
-     * class.
+     * Import the typedefs from the base class.
      */
     typedef BaseClass::value_type      value_type;
     typedef BaseClass::pointer         pointer;
@@ -91,25 +88,15 @@ namespace PETScWrappers
     typedef BaseClass::const_iterator  const_iterator;
 
     /**
-     * Constructor; initializes the
-     * matrix to be empty, without
-     * any structure, i.e.  the
-     * matrix is not usable at
-     * all. This constructor is
-     * therefore only useful for
-     * matrices which are members of
-     * a class. All other matrices
-     * should be created at a point
-     * in the data flow where all
-     * necessary information is
-     * available.
+     * Constructor; initializes the matrix to be empty, without any structure,
+     * i.e.  the matrix is not usable at all. This constructor is therefore
+     * only useful for matrices which are members of a class. All other
+     * matrices should be created at a point in the data flow where all
+     * necessary information is available.
      *
-     * You have to initialize the
-     * matrix before usage with
-     * reinit(BlockSparsityPattern). The
-     * number of blocks per row and
-     * column are then determined by
-     * that function.
+     * You have to initialize the matrix before usage with
+     * reinit(BlockSparsityPattern). The number of blocks per row and column
+     * are then determined by that function.
      */
     BlockSparseMatrix ();
 
@@ -119,161 +106,113 @@ namespace PETScWrappers
     ~BlockSparseMatrix ();
 
     /**
-     * Pseudo copy operator only copying
-     * empty objects. The sizes of the block
+     * Pseudo copy operator only copying empty objects. The sizes of the block
      * matrices need to be the same.
      */
     BlockSparseMatrix &
     operator = (const BlockSparseMatrix &);
 
     /**
-     * This operator assigns a scalar to a
-     * matrix. Since this does usually not
-     * make much sense (should we set all
-     * matrix entries to this value? Only
-     * the nonzero entries of the sparsity
-     * pattern?), this operation is only
-     * allowed if the actual value to be
-     * assigned is zero. This operator only
-     * exists to allow for the obvious
-     * notation <tt>matrix=0</tt>, which
-     * sets all elements of the matrix to
-     * zero, but keep the sparsity pattern
+     * This operator assigns a scalar to a matrix. Since this does usually not
+     * make much sense (should we set all matrix entries to this value? Only
+     * the nonzero entries of the sparsity pattern?), this operation is only
+     * allowed if the actual value to be assigned is zero. This operator only
+     * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+     * all elements of the matrix to zero, but keep the sparsity pattern
      * previously used.
      */
     BlockSparseMatrix &
     operator = (const double d);
 
     /**
-     * Resize the matrix, by setting
-     * the number of block rows and
-     * columns. This deletes all
-     * blocks and replaces them by
-     * unitialized ones, i.e. ones
-     * for which also the sizes are
-     * not yet set. You have to do
-     * that by calling the @p reinit
-     * functions of the blocks
-     * themselves. Do not forget to
-     * call collect_sizes() after
-     * that on this object.
+     * Resize the matrix, by setting the number of block rows and columns.
+     * This deletes all blocks and replaces them by unitialized ones, i.e.
+     * ones for which also the sizes are not yet set. You have to do that by
+     * calling the @p reinit functions of the blocks themselves. Do not forget
+     * to call collect_sizes() after that on this object.
      *
-     * The reason that you have to
-     * set sizes of the blocks
-     * yourself is that the sizes may
-     * be varying, the maximum number
-     * of elements per row may be
-     * varying, etc. It is simpler
-     * not to reproduce the interface
-     * of the @p SparsityPattern
-     * class here but rather let the
-     * user call whatever function
-     * she desires.
+     * The reason that you have to set sizes of the blocks yourself is that
+     * the sizes may be varying, the maximum number of elements per row may be
+     * varying, etc. It is simpler not to reproduce the interface of the @p
+     * SparsityPattern class here but rather let the user call whatever
+     * function she desires.
      */
     void reinit (const size_type n_block_rows,
                  const size_type n_block_columns);
 
     /**
-     * This function collects the
-     * sizes of the sub-objects and
-     * stores them in internal
-     * arrays, in order to be able to
-     * relay global indices into the
-     * matrix to indices into the
-     * subobjects. You *must* call
-     * this function each time after
-     * you have changed the size of
-     * the sub-objects.
+     * This function collects the sizes of the sub-objects and stores them in
+     * internal arrays, in order to be able to relay global indices into the
+     * matrix to indices into the subobjects. You *must* call this function
+     * each time after you have changed the size of the sub-objects.
      */
     void collect_sizes ();
 
     /**
-     * Matrix-vector multiplication:
-     * let $dst = M*src$ with $M$
-     * being this matrix.
+     * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+     * matrix.
      */
     void vmult (BlockVector       &dst,
                 const BlockVector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block column.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block column.
      */
     void vmult (BlockVector          &dst,
                 const Vector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block row.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block row.
      */
     void vmult (Vector    &dst,
                 const BlockVector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block.
      */
     void vmult (Vector       &dst,
                 const Vector &src) const;
 
     /**
-     * Matrix-vector multiplication:
-     * let $dst = M^T*src$ with $M$
-     * being this matrix. This
-     * function does the same as
-     * vmult() but takes the
-     * transposed matrix.
+     * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+     * matrix. This function does the same as vmult() but takes the transposed
+     * matrix.
      */
     void Tvmult (BlockVector       &dst,
                  const BlockVector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block row.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block row.
      */
     void Tvmult (BlockVector  &dst,
                  const Vector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block column.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block column.
      */
     void Tvmult (Vector    &dst,
                  const BlockVector &src) const;
 
     /**
-     * Matrix-vector
-     * multiplication. Just like the
-     * previous function, but only
-     * applicable if the matrix has
-     * only one block.
+     * Matrix-vector multiplication. Just like the previous function, but only
+     * applicable if the matrix has only one block.
      */
     void Tvmult (Vector       &dst,
                  const Vector &src) const;
 
     /**
-     * Make the clear() function in the
-     * base class visible, though it is
+     * Make the clear() function in the base class visible, though it is
      * protected.
      */
     using BlockMatrixBase<SparseMatrix>::clear;
 
-    /** @addtogroup Exceptions
+    /**
+     * @addtogroup Exceptions
      * @{
      */
 
index 7a080e660be77a89ba5a63d02e07b7fdc2a7fc53..759e1976bd8c87eb9f05d405632e19a1599a5103 100644 (file)
@@ -38,33 +38,29 @@ namespace PETScWrappers
    */
 
   /**
-   * An implementation of block vectors based on the vector class implemented in
-   * PETScWrappers. While the base class provides for most of the interface,
-   * this class handles the actual allocation of vectors and provides functions
-   * that are specific to the underlying vector type.
+   * An implementation of block vectors based on the vector class implemented
+   * in PETScWrappers. While the base class provides for most of the
+   * interface, this class handles the actual allocation of vectors and
+   * provides functions that are specific to the underlying vector type.
    *
-   * @ingroup Vectors
-   * @see @ref GlossBlockLA "Block (linear algebra)"
+   * @ingroup Vectors @see @ref GlossBlockLA "Block (linear algebra)"
    * @author Wolfgang Bangerth, 2004
    */
   class BlockVector : public BlockVectorBase<Vector>
   {
   public:
     /**
-     * Typedef the base class for simpler
-     * access to its own typedefs.
+     * Typedef the base class for simpler access to its own typedefs.
      */
     typedef BlockVectorBase<Vector> BaseClass;
 
     /**
-     * Typedef the type of the underlying
-     * vector.
+     * Typedef the type of the underlying vector.
      */
     typedef BaseClass::BlockType  BlockType;
 
     /**
-     * Import the typedefs from the base
-     * class.
+     * Import the typedefs from the base class.
      */
     typedef BaseClass::value_type      value_type;
     typedef BaseClass::pointer         pointer;
@@ -76,76 +72,49 @@ namespace PETScWrappers
     typedef BaseClass::const_iterator  const_iterator;
 
     /**
-     *  Constructor. There are three
-     *  ways to use this
-     *  constructor. First, without
-     *  any arguments, it generates
-     *  an object with no
-     *  blocks. Given one argument,
-     *  it initializes <tt>num_blocks</tt>
-     *  blocks, but these blocks have
-     *  size zero. The third variant
-     *  finally initializes all
-     *  blocks to the same size
-     *  <tt>block_size</tt>.
+     * Constructor. There are three ways to use this constructor. First,
+     * without any arguments, it generates an object with no blocks. Given one
+     * argument, it initializes <tt>num_blocks</tt> blocks, but these blocks
+     * have size zero. The third variant finally initializes all blocks to the
+     * same size <tt>block_size</tt>.
      *
-     *  Confer the other constructor
-     *  further down if you intend to
-     *  use blocks of different
-     *  sizes.
+     * Confer the other constructor further down if you intend to use blocks
+     * of different sizes.
      */
     explicit BlockVector (const unsigned int num_blocks = 0,
                           const size_type    block_size = 0);
 
     /**
-     * Copy-Constructor. Dimension set to
-     * that of V, all components are copied
+     * Copy-Constructor. Dimension set to that of V, all components are copied
      * from V
      */
     BlockVector (const BlockVector  &V);
 
     /**
-     * Copy-constructor: copy the values
-     * from a PETSc wrapper parallel block
+     * Copy-constructor: copy the values from a PETSc wrapper parallel block
      * vector class.
      *
      *
-     * Note that due to the communication
-     * model of MPI, @em all processes have
-     * to actually perform this operation,
-     * even if they do not use the
-     * result. It is not sufficient if only
-     * one processor tries to copy the
-     * elements from the other processors
-     * over to its own process space.
+     * Note that due to the communication model of MPI, @em all processes have
+     * to actually perform this operation, even if they do not use the result.
+     * It is not sufficient if only one processor tries to copy the elements
+     * from the other processors over to its own process space.
      */
     explicit BlockVector (const MPI::BlockVector &v);
 
     /**
-     * Constructor. Set the number of
-     * blocks to <tt>n.size()</tt> and
-     * initialize each block with
-     * <tt>n[i]</tt> zero elements.
+     * Constructor. Set the number of blocks to <tt>n.size()</tt> and
+     * initialize each block with <tt>n[i]</tt> zero elements.
      */
     BlockVector (const std::vector<size_type> &n);
 
     /**
-     * Constructor. Set the number of
-     * blocks to
-     * <tt>n.size()</tt>. Initialize the
-     * vector with the elements
-     * pointed to by the range of
-     * iterators given as second and
-     * third argument. Apart from the
-     * first argument, this
-     * constructor is in complete
-     * analogy to the respective
-     * constructor of the
-     * <tt>std::vector</tt> class, but the
-     * first argument is needed in
-     * order to know how to subdivide
-     * the block vector into
-     * different blocks.
+     * Constructor. Set the number of blocks to <tt>n.size()</tt>. Initialize
+     * the vector with the elements pointed to by the range of iterators given
+     * as second and third argument. Apart from the first argument, this
+     * constructor is in complete analogy to the respective constructor of the
+     * <tt>std::vector</tt> class, but the first argument is needed in order
+     * to know how to subdivide the block vector into different blocks.
      */
     template <typename InputIterator>
     BlockVector (const std::vector<size_type> &n,
@@ -158,153 +127,97 @@ namespace PETScWrappers
     ~BlockVector ();
 
     /**
-     * Copy operator: fill all components of
-     * the vector with the given scalar
+     * Copy operator: fill all components of the vector with the given scalar
      * value.
      */
     BlockVector &operator = (const value_type s);
 
     /**
-     * Copy operator for arguments of the
-     * same type.
+     * Copy operator for arguments of the same type.
      */
     BlockVector &
     operator= (const BlockVector &V);
 
     /**
-     * Copy all the elements of the
-     * parallel block vector @p v into this
-     * local vector. Note that due to the
-     * communication model of MPI, @em all
-     * processes have to actually perform
-     * this operation, even if they do not
-     * use the result. It is not sufficient
-     * if only one processor tries to copy
-     * the elements from the other
-     * processors over to its own process
+     * Copy all the elements of the parallel block vector @p v into this local
+     * vector. Note that due to the communication model of MPI, @em all
+     * processes have to actually perform this operation, even if they do not
+     * use the result. It is not sufficient if only one processor tries to
+     * copy the elements from the other processors over to its own process
      * space.
      */
     BlockVector &
     operator = (const MPI::BlockVector &v);
 
     /**
-     * Reinitialize the BlockVector to
-     * contain <tt>num_blocks</tt> blocks of
+     * Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
      * size <tt>block_size</tt> each.
      *
-     * If <tt>fast==false</tt>, the vector
-     * is filled with zeros.
+     * If <tt>fast==false</tt>, the vector is filled with zeros.
      */
     void reinit (const unsigned int num_blocks,
                  const size_type    block_size,
                  const bool fast = false);
 
     /**
-     * Reinitialize the BlockVector such
-     * that it contains
-     * <tt>block_sizes.size()</tt>
-     * blocks. Each block is reinitialized
-     * to dimension
-     * <tt>block_sizes[i]</tt>.
+     * Reinitialize the BlockVector such that it contains
+     * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
+     * dimension <tt>block_sizes[i]</tt>.
      *
-     * If the number of blocks is the
-     * same as before this function
-     * was called, all vectors remain
-     * the same and reinit() is
-     * called for each vector.
+     * If the number of blocks is the same as before this function was called,
+     * all vectors remain the same and reinit() is called for each vector.
      *
-     * If <tt>fast==false</tt>, the vector
-     * is filled with zeros.
+     * If <tt>fast==false</tt>, the vector is filled with zeros.
      *
-     * Note that you must call this
-     * (or the other reinit()
-     * functions) function, rather
-     * than calling the reinit()
-     * functions of an individual
-     * block, to allow the block
-     * vector to update its caches of
-     * vector sizes. If you call
-     * reinit() on one of the
-     * blocks, then subsequent
-     * actions on this object may
-     * yield unpredictable results
-     * since they may be routed to
+     * Note that you must call this (or the other reinit() functions)
+     * function, rather than calling the reinit() functions of an individual
+     * block, to allow the block vector to update its caches of vector sizes.
+     * If you call reinit() on one of the blocks, then subsequent actions on
+     * this object may yield unpredictable results since they may be routed to
      * the wrong block.
      */
     void reinit (const std::vector<size_type> &N,
                  const bool                   fast=false);
 
     /**
-     * Change the dimension to that
-     * of the vector <tt>V</tt>. The same
-     * applies as for the other
-     * reinit() function.
+     * Change the dimension to that of the vector <tt>V</tt>. The same applies
+     * as for the other reinit() function.
      *
-     * The elements of <tt>V</tt> are not
-     * copied, i.e.  this function is
-     * the same as calling <tt>reinit
-     * (V.size(), fast)</tt>.
+     * The elements of <tt>V</tt> are not copied, i.e.  this function is the
+     * same as calling <tt>reinit (V.size(), fast)</tt>.
      *
-     * Note that you must call this
-     * (or the other reinit()
-     * functions) function, rather
-     * than calling the reinit()
-     * functions of an individual
-     * block, to allow the block
-     * vector to update its caches of
-     * vector sizes. If you call
-     * reinit() of one of the
-     * blocks, then subsequent
-     * actions of this object may
-     * yield unpredictable results
-     * since they may be routed to
+     * Note that you must call this (or the other reinit() functions)
+     * function, rather than calling the reinit() functions of an individual
+     * block, to allow the block vector to update its caches of vector sizes.
+     * If you call reinit() of one of the blocks, then subsequent actions of
+     * this object may yield unpredictable results since they may be routed to
      * the wrong block.
      */
     void reinit (const BlockVector &V,
                  const bool         fast=false);
 
     /**
-     * Change the number of blocks to
-     * <tt>num_blocks</tt>. The individual
-     * blocks will get initialized with
-     * zero size, so it is assumed that
-     * the user resizes the
-     * individual blocks by herself
-     * in an appropriate way, and
-     * calls <tt>collect_sizes</tt>
-     * afterwards.
+     * Change the number of blocks to <tt>num_blocks</tt>. The individual
+     * blocks will get initialized with zero size, so it is assumed that the
+     * user resizes the individual blocks by herself in an appropriate way,
+     * and calls <tt>collect_sizes</tt> afterwards.
      */
     void reinit (const unsigned int num_blocks);
 
     /**
-     * Swap the contents of this
-     * vector and the other vector
-     * <tt>v</tt>. One could do this
-     * operation with a temporary
-     * variable and copying over the
-     * data elements, but this
-     * function is significantly more
-     * efficient since it only swaps
-     * the pointers to the data of
-     * the two vectors and therefore
-     * does not need to allocate
-     * temporary storage and move
-     * data around.
+     * Swap the contents of this vector and the other vector <tt>v</tt>. One
+     * could do this operation with a temporary variable and copying over the
+     * data elements, but this function is significantly more efficient since
+     * it only swaps the pointers to the data of the two vectors and therefore
+     * does not need to allocate temporary storage and move data around.
      *
-     * Limitation: right now this
-     * function only works if both
-     * vectors have the same number
-     * of blocks. If needed, the
-     * numbers of blocks should be
+     * Limitation: right now this function only works if both vectors have the
+     * same number of blocks. If needed, the numbers of blocks should be
      * exchanged, too.
      *
-     * This function is analog to the
-     * the swap() function of all C++
-     * standard containers. Also,
-     * there is a global function
-     * swap(u,v) that simply calls
-     * <tt>u.swap(v)</tt>, again in analogy
-     * to standard functions.
+     * This function is analog to the the swap() function of all C++ standard
+     * containers. Also, there is a global function swap(u,v) that simply
+     * calls <tt>u.swap(v)</tt>, again in analogy to standard functions.
      */
     void swap (BlockVector &v);
 
@@ -316,8 +229,10 @@ namespace PETScWrappers
                 const bool          scientific = true,
                 const bool          across = true) const;
 
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
 
     /**
      * Exception
@@ -519,9 +434,9 @@ namespace PETScWrappers
 
 
   /**
-   * Global function which overloads the default implementation
-   * of the C++ standard library which uses a temporary object. The
-   * function simply exchanges the data of the two vectors.
+   * Global function which overloads the default implementation of the C++
+   * standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates PETScWrappers::BlockVector
    * @author Wolfgang Bangerth, 2000
index 12d6240c2f038ea65f27f4576d7bcf56ed16279c..8d9dead68cd44e73e83cf99a809724ba739bccd0 100644 (file)
@@ -37,11 +37,11 @@ namespace PETScWrappers
   /**
    * Implementation of a sequential dense matrix class based on PETSC. All the
    * functionality is actually in the base class, except for the calls to
-   * generate a sequential dense matrix. This is possible since PETSc only works
-   * on an abstract matrix type and internally distributes to functions that do
-   * the actual work depending on the actual matrix type (much like using
-   * virtual functions). Only the functions creating a matrix of specific type
-   * differ, and are implemented in this particular class.
+   * generate a sequential dense matrix. This is possible since PETSc only
+   * works on an abstract matrix type and internally distributes to functions
+   * that do the actual work depending on the actual matrix type (much like
+   * using virtual functions). Only the functions creating a matrix of
+   * specific type differ, and are implemented in this particular class.
    *
    * @ingroup Matrix1
    * @author Wolfgang Bangerth, 2004
@@ -70,18 +70,18 @@ namespace PETScWrappers
 
 
     /**
-     * Throw away the present matrix and generate one that has the
-     * same properties as if it were created by the constructor of
-     * this class with the same argument list as the present function.
+     * Throw away the present matrix and generate one that has the same
+     * properties as if it were created by the constructor of this class with
+     * the same argument list as the present function.
      */
     void reinit (const size_type m,
                  const size_type n);
 
 
     /**
-     * Return a reference to the MPI communicator object in use with
-     * this matrix. Since this is a sequential matrix, it returns the
-     * MPI_COMM_SELF communicator.
+     * Return a reference to the MPI communicator object in use with this
+     * matrix. Since this is a sequential matrix, it returns the MPI_COMM_SELF
+     * communicator.
      */
     virtual const MPI_Comm &get_mpi_communicator () const;
 
@@ -89,8 +89,8 @@ namespace PETScWrappers
 
     /**
      * Do the actual work for the respective reinit() function and the
-     * matching constructor, i.e. create a matrix. Getting rid of the
-     * previous matrix is left to the caller.
+     * matching constructor, i.e. create a matrix. Getting rid of the previous
+     * matrix is left to the caller.
      */
     void do_reinit (const size_type m,
                     const size_type n);
index 5ea356c8c3965048b5423b97e8f1d0b12d3e9420..0b46f8945820b9ca7241c1bd1497327db31e8b67 100644 (file)
@@ -46,15 +46,15 @@ namespace PETScWrappers
   namespace MatrixIterators
   {
     /**
-     * STL conforming iterator. This class acts as an iterator walking over the
-     * elements of PETSc matrices. Since PETSc offers a uniform interface for all
-     * types of matrices, this iterator can be used to access both sparse and full
-     * matrices.
+     * STL conforming iterator. This class acts as an iterator walking over
+     * the elements of PETSc matrices. Since PETSc offers a uniform interface
+     * for all types of matrices, this iterator can be used to access both
+     * sparse and full matrices.
      *
-     * Note that PETSc does not give any guarantees as to the order of elements
-     * within each row. Note also that accessing the elements of a full matrix
-     * surprisingly only shows the nonzero elements of the matrix, not all
-     * elements.
+     * Note that PETSc does not give any guarantees as to the order of
+     * elements within each row. Note also that accessing the elements of a
+     * full matrix surprisingly only shows the nonzero elements of the matrix,
+     * not all elements.
      *
      * @ingroup PETScWrappers
      * @author Guido Kanschat, Roy Stogner, Wolfgang Bangerth, 2004
@@ -74,10 +74,8 @@ namespace PETScWrappers
         typedef types::global_dof_index size_type;
 
         /**
-         * Constructor. Since we use
-         * accessors only for read
-         * access, a const matrix
-         * pointer is sufficient.
+         * Constructor. Since we use accessors only for read access, a const
+         * matrix pointer is sufficient.
          */
         Accessor (const MatrixBase *matrix,
                   const size_type   row,
@@ -89,23 +87,17 @@ namespace PETScWrappers
         Accessor (const Accessor &a);
 
         /**
-         * Row number of the element
-         * represented by this
-         * object.
+         * Row number of the element represented by this object.
          */
         size_type row() const;
 
         /**
-         * Index in row of the element
-         * represented by this
-         * object.
+         * Index in row of the element represented by this object.
          */
         size_type index() const;
 
         /**
-         * Column number of the
-         * element represented by
-         * this object.
+         * Column number of the element represented by this object.
          */
         size_type column() const;
 
@@ -145,49 +137,33 @@ namespace PETScWrappers
         size_type a_index;
 
         /**
-         * Cache where we store the
-         * column indices of the present
-         * row. This is necessary, since
-         * PETSc makes access to the
-         * elements of its matrices
-         * rather hard, and it is much
-         * more efficient to copy all
-         * column entries of a row once
-         * when we enter it than
-         * repeatedly asking PETSc for
-         * individual ones. This also
-         * makes some sense since it is
-         * likely that we will access
-         * them sequentially anyway.
+         * Cache where we store the column indices of the present row. This is
+         * necessary, since PETSc makes access to the elements of its matrices
+         * rather hard, and it is much more efficient to copy all column
+         * entries of a row once when we enter it than repeatedly asking PETSc
+         * for individual ones. This also makes some sense since it is likely
+         * that we will access them sequentially anyway.
          *
-         * In order to make copying of
-         * iterators/accessor of
-         * acceptable performance, we
-         * keep a shared pointer to these
-         * entries so that more than one
-         * accessor can access this data
-         * if necessary.
+         * In order to make copying of iterators/accessor of acceptable
+         * performance, we keep a shared pointer to these entries so that more
+         * than one accessor can access this data if necessary.
          */
         std_cxx11::shared_ptr<const std::vector<size_type> > colnum_cache;
 
         /**
-         * Similar cache for the values
-         * of this row.
+         * Similar cache for the values of this row.
          */
         std_cxx11::shared_ptr<const std::vector<PetscScalar> > value_cache;
 
         /**
-         * Discard the old row caches
-         * (they may still be used by
-         * other accessors) and generate
-         * new ones for the row pointed
-         * to presently by this accessor.
+         * Discard the old row caches (they may still be used by other
+         * accessors) and generate new ones for the row pointed to presently
+         * by this accessor.
          */
         void visit_present_row ();
 
         /**
-         * Make enclosing class a
-         * friend.
+         * Make enclosing class a friend.
          */
         friend class const_iterator;
       };
@@ -199,8 +175,7 @@ namespace PETScWrappers
       typedef types::global_dof_index size_type;
 
       /**
-       * Constructor. Create an iterator
-       * into the matrix @p matrix for the
+       * Constructor. Create an iterator into the matrix @p matrix for the
        * given row and the index within it.
        */
       const_iterator (const MatrixBase *matrix,
@@ -228,9 +203,7 @@ namespace PETScWrappers
       const Accessor *operator-> () const;
 
       /**
-       * Comparison. True, if
-       * both iterators point to
-       * the same matrix
+       * Comparison. True, if both iterators point to the same matrix
        * position.
        */
       bool operator == (const const_iterator &) const;
@@ -240,13 +213,9 @@ namespace PETScWrappers
       bool operator != (const const_iterator &) const;
 
       /**
-       * Comparison
-       * operator. Result is true
-       * if either the first row
-       * number is smaller or if
-       * the row numbers are
-       * equal and the first
-       * index is smaller.
+       * Comparison operator. Result is true if either the first row number is
+       * smaller or if the row numbers are equal and the first index is
+       * smaller.
        */
       bool operator < (const const_iterator &) const;
 
@@ -261,8 +230,7 @@ namespace PETScWrappers
 
     private:
       /**
-       * Store an object of the
-       * accessor class.
+       * Store an object of the accessor class.
        */
       Accessor accessor;
     };
@@ -271,21 +239,21 @@ namespace PETScWrappers
 
 
   /**
-   * Base class for all matrix classes that are implemented on top of the PETSc
-   * matrix types. Since in PETSc all matrix types (i.e. sequential and
+   * Base class for all matrix classes that are implemented on top of the
+   * PETSc matrix types. Since in PETSc all matrix types (i.e. sequential and
    * parallel, sparse, blocked, etc.)  are built by filling the contents of an
-   * abstract object that is only referenced through a pointer of a type that is
-   * independent of the actual matrix type, we can implement almost all
-   * functionality of matrices in this base class. Derived classes will then only
-   * have to provide the functionality to create one or the other kind of
+   * abstract object that is only referenced through a pointer of a type that
+   * is independent of the actual matrix type, we can implement almost all
+   * functionality of matrices in this base class. Derived classes will then
+   * only have to provide the functionality to create one or the other kind of
    * matrix.
    *
-   * The interface of this class is modeled after the existing
-   * SparseMatrix class in deal.II. It has almost the same member
-   * functions, and is often exchangable. However, since PETSc only supports a
-   * single scalar type (either double, float, or a complex data type), it is
-   * not templated, and only works with whatever your PETSc installation has
-   * defined the data type PetscScalar to.
+   * The interface of this class is modeled after the existing SparseMatrix
+   * class in deal.II. It has almost the same member functions, and is often
+   * exchangable. However, since PETSc only supports a single scalar type
+   * (either double, float, or a complex data type), it is not templated, and
+   * only works with whatever your PETSc installation has defined the data
+   * type PetscScalar to.
    *
    * Note that PETSc only guarantees that operations do what you expect if the
    * functions @p MatAssemblyBegin and @p MatAssemblyEnd have been called
@@ -306,8 +274,7 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Declare a typedef for the iterator
-     * class.
+     * Declare a typedef for the iterator class.
      */
     typedef MatrixIterators::const_iterator const_iterator;
 
@@ -317,8 +284,7 @@ namespace PETScWrappers
     typedef types::global_dof_index size_type;
 
     /**
-     * Declare a typedef in analogy to all
-     * the other container classes.
+     * Declare a typedef in analogy to all the other container classes.
      */
     typedef PetscScalar value_type;
 
@@ -328,88 +294,57 @@ namespace PETScWrappers
     MatrixBase ();
 
     /**
-     * Destructor. Made virtual so that one
-     * can use pointers to this class.
+     * Destructor. Made virtual so that one can use pointers to this class.
      */
     virtual ~MatrixBase ();
 
     /**
-     * This operator assigns a scalar to a
-     * matrix. Since this does usually not
-     * make much sense (should we set all
-     * matrix entries to this value? Only
-     * the nonzero entries of the sparsity
-     * pattern?), this operation is only
-     * allowed if the actual value to be
-     * assigned is zero. This operator only
-     * exists to allow for the obvious
-     * notation <tt>matrix=0</tt>, which
-     * sets all elements of the matrix to
-     * zero, but keeps the sparsity pattern
+     * This operator assigns a scalar to a matrix. Since this does usually not
+     * make much sense (should we set all matrix entries to this value? Only
+     * the nonzero entries of the sparsity pattern?), this operation is only
+     * allowed if the actual value to be assigned is zero. This operator only
+     * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+     * all elements of the matrix to zero, but keeps the sparsity pattern
      * previously used.
      */
     MatrixBase &
     operator = (const value_type d);
     /**
-     * Release all memory and return
-     * to a state just like after
-     * having called the default
-     * constructor.
+     * Release all memory and return to a state just like after having called
+     * the default constructor.
      */
     void clear ();
 
     /**
-     * Set the element (<i>i,j</i>) to @p
-     * value.
+     * Set the element (<i>i,j</i>) to @p value.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds a new entry to the
-     * matrix if it didn't exist before,
-     * very much in contrast to the
-     * SparseMatrix class which throws an
-     * error if the entry does not exist.
-     * If <tt>value</tt> is not a finite
-     * number an exception is thrown.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds a new entry to the matrix if
+     * it didn't exist before, very much in contrast to the SparseMatrix class
+     * which throws an error if the entry does not exist. If <tt>value</tt> is
+     * not a finite number an exception is thrown.
      */
     void set (const size_type   i,
               const size_type   j,
               const PetscScalar value);
 
     /**
-     * Set all elements given in a
-     * FullMatrix<double> into the sparse
-     * matrix locations given by
-     * <tt>indices</tt>. In other words,
-     * this function writes the elements
-     * in <tt>full_matrix</tt> into the
-     * calling matrix, using the
-     * local-to-global indexing specified
-     * by <tt>indices</tt> for both the
-     * rows and the columns of the
-     * matrix. This function assumes a
-     * quadratic sparse matrix and a
-     * quadratic full_matrix, the usual
+     * Set all elements given in a FullMatrix<double> into the sparse matrix
+     * locations given by <tt>indices</tt>. In other words, this function
+     * writes the elements in <tt>full_matrix</tt> into the calling matrix,
+     * using the local-to-global indexing specified by <tt>indices</tt> for
+     * both the rows and the columns of the matrix. This function assumes a
+     * quadratic sparse matrix and a quadratic full_matrix, the usual
      * situation in FE calculations.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be inserted anyway
-     * or they should be filtered
-     * away. The default value is
-     * <tt>false</tt>, i.e., even zero
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be inserted anyway or they should be
+     * filtered away. The default value is <tt>false</tt>, i.e., even zero
      * values are inserted/replaced.
      */
     void set (const std::vector<size_type>  &indices,
@@ -417,11 +352,9 @@ namespace PETScWrappers
               const bool                     elide_zero_values = false);
 
     /**
-     * Same function as before, but now
-     * including the possibility to use
-     * rectangular full_matrices and
-     * different local-to-global indexing
-     * on rows and columns, respectively.
+     * Same function as before, but now including the possibility to use
+     * rectangular full_matrices and different local-to-global indexing on
+     * rows and columns, respectively.
      */
     void set (const std::vector<size_type>  &row_indices,
               const std::vector<size_type>  &col_indices,
@@ -429,29 +362,17 @@ namespace PETScWrappers
               const bool                     elide_zero_values = false);
 
     /**
-     * Set several elements in the
-     * specified row of the matrix with
-     * column indices as given by
-     * <tt>col_indices</tt> to the
-     * respective value.
+     * Set several elements in the specified row of the matrix with column
+     * indices as given by <tt>col_indices</tt> to the respective value.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be inserted anyway
-     * or they should be filtered
-     * away. The default value is
-     * <tt>false</tt>, i.e., even zero
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be inserted anyway or they should be
+     * filtered away. The default value is <tt>false</tt>, i.e., even zero
      * values are inserted/replaced.
      */
     void set (const size_type                 row,
@@ -460,29 +381,17 @@ namespace PETScWrappers
               const bool                      elide_zero_values = false);
 
     /**
-     * Set several elements to values
-     * given by <tt>values</tt> in a
-     * given row in columns given by
-     * col_indices into the sparse
-     * matrix.
+     * Set several elements to values given by <tt>values</tt> in a given row
+     * in columns given by col_indices into the sparse matrix.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be inserted anyway
-     * or they should be filtered
-     * away. The default value is
-     * <tt>false</tt>, i.e., even zero
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be inserted anyway or they should be
+     * filtered away. The default value is <tt>false</tt>, i.e., even zero
      * values are inserted/replaced.
      */
     void set (const size_type    row,
@@ -492,71 +401,45 @@ namespace PETScWrappers
               const bool         elide_zero_values = false);
 
     /**
-     * Add @p value to the element
-     * (<i>i,j</i>).
+     * Add @p value to the element (<i>i,j</i>).
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds a new entry to the
-     * matrix if it didn't exist before,
-     * very much in contrast to the
-     * SparseMatrix class which throws an
-     * error if the entry does not exist.
-     * If <tt>value</tt> is not a finite
-     * number an exception is thrown.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds a new entry to the matrix if
+     * it didn't exist before, very much in contrast to the SparseMatrix class
+     * which throws an error if the entry does not exist. If <tt>value</tt> is
+     * not a finite number an exception is thrown.
      */
     void add (const size_type   i,
               const size_type   j,
               const PetscScalar value);
 
     /**
-     * Add all elements given in a
-     * FullMatrix<double> into sparse
-     * matrix locations given by
-     * <tt>indices</tt>. In other words,
-     * this function adds the elements in
-     * <tt>full_matrix</tt> to the
-     * respective entries in calling
-     * matrix, using the local-to-global
-     * indexing specified by
-     * <tt>indices</tt> for both the rows
-     * and the columns of the
-     * matrix. This function assumes a
-     * quadratic sparse matrix and a
-     * quadratic full_matrix, the usual
-     * situation in FE calculations.
+     * Add all elements given in a FullMatrix<double> into sparse matrix
+     * locations given by <tt>indices</tt>. In other words, this function adds
+     * the elements in <tt>full_matrix</tt> to the respective entries in
+     * calling matrix, using the local-to-global indexing specified by
+     * <tt>indices</tt> for both the rows and the columns of the matrix. This
+     * function assumes a quadratic sparse matrix and a quadratic full_matrix,
+     * the usual situation in FE calculations.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be added anyway or
-     * these should be filtered away and
-     * only non-zero data is added. The
-     * default value is <tt>true</tt>,
-     * i.e., zero values won't be added
-     * into the matrix.
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be added anyway or these should be
+     * filtered away and only non-zero data is added. The default value is
+     * <tt>true</tt>, i.e., zero values won't be added into the matrix.
      */
     void add (const std::vector<size_type>  &indices,
               const FullMatrix<PetscScalar> &full_matrix,
               const bool                     elide_zero_values = true);
 
     /**
-     * Same function as before, but now
-     * including the possibility to use
-     * rectangular full_matrices and
-     * different local-to-global indexing
-     * on rows and columns, respectively.
+     * Same function as before, but now including the possibility to use
+     * rectangular full_matrices and different local-to-global indexing on
+     * rows and columns, respectively.
      */
     void add (const std::vector<size_type>  &row_indices,
               const std::vector<size_type>  &col_indices,
@@ -564,31 +447,18 @@ namespace PETScWrappers
               const bool                     elide_zero_values = true);
 
     /**
-     * Set several elements in the
-     * specified row of the matrix with
-     * column indices as given by
-     * <tt>col_indices</tt> to the
-     * respective value.
+     * Set several elements in the specified row of the matrix with column
+     * indices as given by <tt>col_indices</tt> to the respective value.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be added anyway or
-     * these should be filtered away and
-     * only non-zero data is added. The
-     * default value is <tt>true</tt>,
-     * i.e., zero values won't be added
-     * into the matrix.
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be added anyway or these should be
+     * filtered away and only non-zero data is added. The default value is
+     * <tt>true</tt>, i.e., zero values won't be added into the matrix.
      */
     void add (const size_type                 row,
               const std::vector<size_type>   &col_indices,
@@ -596,31 +466,18 @@ namespace PETScWrappers
               const bool                      elide_zero_values = true);
 
     /**
-     * Add an array of values given by
-     * <tt>values</tt> in the given
-     * global matrix row at columns
-     * specified by col_indices in the
-     * sparse matrix.
+     * Add an array of values given by <tt>values</tt> in the given global
+     * matrix row at columns specified by col_indices in the sparse matrix.
      *
-     * If the present object (from a
-     * derived class of this one) happens
-     * to be a sparse matrix, then this
-     * function adds some new entries to
-     * the matrix if they didn't exist
-     * before, very much in contrast to
-     * the SparseMatrix class which
-     * throws an error if the entry does
-     * not exist.
+     * If the present object (from a derived class of this one) happens to be
+     * a sparse matrix, then this function adds some new entries to the matrix
+     * if they didn't exist before, very much in contrast to the SparseMatrix
+     * class which throws an error if the entry does not exist.
      *
-     * The optional parameter
-     * <tt>elide_zero_values</tt> can be
-     * used to specify whether zero
-     * values should be added anyway or
-     * these should be filtered away and
-     * only non-zero data is added. The
-     * default value is <tt>true</tt>,
-     * i.e., zero values won't be added
-     * into the matrix.
+     * The optional parameter <tt>elide_zero_values</tt> can be used to
+     * specify whether zero values should be added anyway or these should be
+     * filtered away and only non-zero data is added. The default value is
+     * <tt>true</tt>, i.e., zero values won't be added into the matrix.
      */
     void add (const size_type    row,
               const size_type    n_cols,
@@ -630,70 +487,44 @@ namespace PETScWrappers
               const bool         col_indices_are_sorted = false);
 
     /**
-     * Remove all elements from
-     * this <tt>row</tt> by setting
-     * them to zero. The function
-     * does not modify the number
-     * of allocated nonzero
-     * entries, it only sets some
-     * entries to zero. It may drop
-     * them from the sparsity
-     * pattern, though (but retains
-     * the allocated memory in case
-     * new entries are again added
-     * later).
+     * Remove all elements from this <tt>row</tt> by setting them to zero. The
+     * function does not modify the number of allocated nonzero entries, it
+     * only sets some entries to zero. It may drop them from the sparsity
+     * pattern, though (but retains the allocated memory in case new entries
+     * are again added later).
      *
-     * This operation is used in
-     * eliminating constraints (e.g. due to
-     * hanging nodes) and makes sure that
-     * we can write this modification to
-     * the matrix without having to read
-     * entries (such as the locations of
-     * non-zero elements) from it --
-     * without this operation, removing
-     * constraints on parallel matrices is
-     * a rather complicated procedure.
+     * This operation is used in eliminating constraints (e.g. due to hanging
+     * nodes) and makes sure that we can write this modification to the matrix
+     * without having to read entries (such as the locations of non-zero
+     * elements) from it -- without this operation, removing constraints on
+     * parallel matrices is a rather complicated procedure.
      *
-     * The second parameter can be used to
-     * set the diagonal entry of this row
-     * to a value different from zero. The
-     * default is to set it to zero.
+     * The second parameter can be used to set the diagonal entry of this row
+     * to a value different from zero. The default is to set it to zero.
      */
     void clear_row (const size_type   row,
                     const PetscScalar new_diag_value = 0);
 
     /**
-     * Same as clear_row(), except that it
-     * works on a number of rows at once.
+     * Same as clear_row(), except that it works on a number of rows at once.
      *
-     * The second parameter can be used to
-     * set the diagonal entries of all
-     * cleared rows to something different
-     * from zero. Note that all of these
-     * diagonal entries get the same value
-     * -- if you want different values for
-     * the diagonal entries, you have to
-     * set them by hand.
+     * The second parameter can be used to set the diagonal entries of all
+     * cleared rows to something different from zero. Note that all of these
+     * diagonal entries get the same value -- if you want different values for
+     * the diagonal entries, you have to set them by hand.
      */
     void clear_rows (const std::vector<size_type> &rows,
                      const PetscScalar             new_diag_value = 0);
 
     /**
-     * PETSc matrices store their own
-     * sparsity patterns. So, in analogy to
-     * our own SparsityPattern class,
-     * this function compresses the
-     * sparsity pattern and allows the
-     * resulting matrix to be used in all
-     * other operations where before only
-     * assembly functions were
-     * allowed. This function must
-     * therefore be called once you have
-     * assembled the matrix.
+     * PETSc matrices store their own sparsity patterns. So, in analogy to our
+     * own SparsityPattern class, this function compresses the sparsity
+     * pattern and allows the resulting matrix to be used in all other
+     * operations where before only assembly functions were allowed. This
+     * function must therefore be called once you have assembled the matrix.
      *
-     * See @ref GlossCompress "Compressing distributed objects"
-     * for more information.
-     * more information.
+     * See @ref GlossCompress "Compressing distributed objects" for more
+     * information. more information.
      */
     void compress (::dealii::VectorOperation::values operation);
 
@@ -703,124 +534,87 @@ namespace PETScWrappers
     void compress () DEAL_II_DEPRECATED;
 
     /**
-     * Return the value of the entry
-     * (<i>i,j</i>).  This may be an
-     * expensive operation and you should
-     * always take care where to call this
-     * function. In contrast to the
-     * respective function in the
-     * @p MatrixBase class, we don't
-     * throw an exception if the respective
-     * entry doesn't exist in the sparsity
-     * pattern of this class, since PETSc
-     * does not transmit this information.
+     * Return the value of the entry (<i>i,j</i>).  This may be an expensive
+     * operation and you should always take care where to call this function.
+     * In contrast to the respective function in the @p MatrixBase class, we
+     * don't throw an exception if the respective entry doesn't exist in the
+     * sparsity pattern of this class, since PETSc does not transmit this
+     * information.
      *
-     * This function is therefore exactly
-     * equivalent to the <tt>el()</tt> function.
+     * This function is therefore exactly equivalent to the <tt>el()</tt>
+     * function.
      */
     PetscScalar operator () (const size_type i,
                              const size_type j) const;
 
     /**
-     * Return the value of the matrix entry
-     * (<i>i,j</i>). If this entry does not
-     * exist in the sparsity pattern, then
-     * zero is returned. While this may be
-     * convenient in some cases, note that
-     * it is simple to write algorithms
-     * that are slow compared to an optimal
-     * solution, since the sparsity of the
-     * matrix is not used.
+     * Return the value of the matrix entry (<i>i,j</i>). If this entry does
+     * not exist in the sparsity pattern, then zero is returned. While this
+     * may be convenient in some cases, note that it is simple to write
+     * algorithms that are slow compared to an optimal solution, since the
+     * sparsity of the matrix is not used.
      */
     PetscScalar el (const size_type i,
                     const size_type j) const;
 
     /**
-     * Return the main diagonal
-     * element in the <i>i</i>th
-     * row. This function throws an
-     * error if the matrix is not
-     * quadratic.
+     * Return the main diagonal element in the <i>i</i>th row. This function
+     * throws an error if the matrix is not quadratic.
      *
-     * Since we do not have direct access
-     * to the underlying data structure,
-     * this function is no faster than the
-     * elementwise access using the el()
-     * function. However, we provide this
-     * function for compatibility with the
+     * Since we do not have direct access to the underlying data structure,
+     * this function is no faster than the elementwise access using the el()
+     * function. However, we provide this function for compatibility with the
      * SparseMatrix class.
      */
     PetscScalar diag_element (const size_type i) const;
 
     /**
-     * Return the number of rows in this
-     * matrix.
+     * Return the number of rows in this matrix.
      */
     size_type m () const;
 
     /**
-     * Return the number of columns in this
-     * matrix.
+     * Return the number of columns in this matrix.
      */
     size_type n () const;
 
     /**
-     * Return the local dimension of the
-     * matrix, i.e. the number of rows
-     * stored on the present MPI
-     * process. For sequential matrices,
-     * this number is the same as m(),
-     * but for parallel matrices it may be
-     * smaller.
+     * Return the local dimension of the matrix, i.e. the number of rows
+     * stored on the present MPI process. For sequential matrices, this number
+     * is the same as m(), but for parallel matrices it may be smaller.
      *
-     * To figure out which elements
-     * exactly are stored locally,
-     * use local_range().
+     * To figure out which elements exactly are stored locally, use
+     * local_range().
      */
     size_type local_size () const;
 
     /**
-     * Return a pair of indices
-     * indicating which rows of
-     * this matrix are stored
-     * locally. The first number is
-     * the index of the first
-     * row stored, the second
-     * the index of the one past
-     * the last one that is stored
-     * locally. If this is a
-     * sequential matrix, then the
-     * result will be the pair
-     * (0,m()), otherwise it will be
-     * a pair (i,i+n), where
+     * Return a pair of indices indicating which rows of this matrix are
+     * stored locally. The first number is the index of the first row stored,
+     * the second the index of the one past the last one that is stored
+     * locally. If this is a sequential matrix, then the result will be the
+     * pair (0,m()), otherwise it will be a pair (i,i+n), where
      * <tt>n=local_size()</tt>.
      */
     std::pair<size_type, size_type>
     local_range () const;
 
     /**
-     * Return whether @p index is
-     * in the local range or not,
-     * see also local_range().
+     * Return whether @p index is in the local range or not, see also
+     * local_range().
      */
     bool in_local_range (const size_type index) const;
 
     /**
-     * Return a reference to the MPI
-     * communicator object in use with this
-     * matrix. This function has to be
-     * implemented in derived classes.
+     * Return a reference to the MPI communicator object in use with this
+     * matrix. This function has to be implemented in derived classes.
      */
     virtual const MPI_Comm &get_mpi_communicator () const = 0;
 
     /**
-     * Return the number of nonzero
-     * elements of this
-     * matrix. Actually, it returns
-     * the number of entries in the
-     * sparsity pattern; if any of
-     * the entries should happen to
-     * be zero, it is counted anyway.
+     * Return the number of nonzero elements of this matrix. Actually, it
+     * returns the number of entries in the sparsity pattern; if any of the
+     * entries should happen to be zero, it is counted anyway.
      */
     size_type n_nonzero_elements () const;
 
@@ -830,103 +624,64 @@ namespace PETScWrappers
     size_type row_length (const size_type row) const;
 
     /**
-     * Return the l1-norm of the matrix, that is
-     * $|M|_1=max_{all columns j}\sum_{all
-     * rows i} |M_ij|$,
-     * (max. sum of columns).
-     * This is the
-     * natural matrix norm that is compatible
-     * to the l1-norm for vectors, i.e.
-     * $|Mv|_1\leq |M|_1 |v|_1$.
-     * (cf. Haemmerlin-Hoffmann:
-     * Numerische Mathematik)
+     * Return the l1-norm of the matrix, that is $|M|_1=max_{all columns
+     * j}\sum_{all rows i} |M_ij|$, (max. sum of columns). This is the natural
+     * matrix norm that is compatible to the l1-norm for vectors, i.e.
+     * $|Mv|_1\leq |M|_1 |v|_1$. (cf. Haemmerlin-Hoffmann: Numerische
+     * Mathematik)
      */
     PetscReal l1_norm () const;
 
     /**
-     * Return the linfty-norm of the
-     * matrix, that is
-     * $|M|_infty=max_{all rows i}\sum_{all
-     * columns j} |M_ij|$,
-     * (max. sum of rows).
-     * This is the
-     * natural matrix norm that is compatible
-     * to the linfty-norm of vectors, i.e.
-     * $|Mv|_infty \leq |M|_infty |v|_infty$.
-     * (cf. Haemmerlin-Hoffmann:
+     * Return the linfty-norm of the matrix, that is $|M|_infty=max_{all rows
+     * i}\sum_{all columns j} |M_ij|$, (max. sum of rows). This is the natural
+     * matrix norm that is compatible to the linfty-norm of vectors, i.e.
+     * $|Mv|_infty \leq |M|_infty |v|_infty$. (cf. Haemmerlin-Hoffmann:
      * Numerische Mathematik)
      */
     PetscReal linfty_norm () const;
 
     /**
-     * Return the frobenius norm of the
-     * matrix, i.e. the square root of the
-     * sum of squares of all entries in the
-     * matrix.
+     * Return the frobenius norm of the matrix, i.e. the square root of the
+     * sum of squares of all entries in the matrix.
      */
     PetscReal frobenius_norm () const;
 
 
     /**
-     * Return the square of the norm
-     * of the vector $v$ with respect
-     * to the norm induced by this
-     * matrix,
-     * i.e. $\left(v,Mv\right)$. This
-     * is useful, e.g. in the finite
-     * element context, where the
-     * $L_2$ norm of a function
-     * equals the matrix norm with
-     * respect to the mass matrix of
-     * the vector representing the
-     * nodal values of the finite
-     * element function.
+     * Return the square of the norm of the vector $v$ with respect to the
+     * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful,
+     * e.g. in the finite element context, where the $L_2$ norm of a function
+     * equals the matrix norm with respect to the mass matrix of the vector
+     * representing the nodal values of the finite element function.
      *
-     * Obviously, the matrix needs to
-     * be quadratic for this operation.
+     * Obviously, the matrix needs to be quadratic for this operation.
      *
-     * The implementation of this function
-     * is not as efficient as the one in
-     * the @p MatrixBase class used in
-     * deal.II (i.e. the original one, not
-     * the PETSc wrapper class) since PETSc
-     * doesn't support this operation and
+     * The implementation of this function is not as efficient as the one in
+     * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+     * PETSc wrapper class) since PETSc doesn't support this operation and
      * needs a temporary vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then the given vector has to be
-     * a distributed vector as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither
-     * may the vector be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then the given
+     * vector has to be a distributed vector as well. Conversely, if the
+     * matrix is not distributed, then neither may the vector be.
      */
     PetscScalar matrix_norm_square (const VectorBase &v) const;
 
 
     /**
-     * Compute the matrix scalar
-     * product $\left(u,Mv\right)$.
+     * Compute the matrix scalar product $\left(u,Mv\right)$.
      *
-     * The implementation of this function
-     * is not as efficient as the one in
-     * the @p MatrixBase class used in
-     * deal.II (i.e. the original one, not
-     * the PETSc wrapper class) since PETSc
-     * doesn't support this operation and
+     * The implementation of this function is not as efficient as the one in
+     * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+     * PETSc wrapper class) since PETSc doesn't support this operation and
      * needs a temporary vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     PetscScalar matrix_scalar_product (const VectorBase &u,
                                        const VectorBase &v) const;
@@ -934,23 +689,19 @@ namespace PETScWrappers
 
 #if DEAL_II_PETSC_VERSION_GTE(3,1,0)
     /**
-     * Return the trace of the
-     * matrix, i.e. the sum of all
-     * diagonal entries in the
-     * matrix.
+     * Return the trace of the matrix, i.e. the sum of all diagonal entries in
+     * the matrix.
      */
     PetscScalar trace () const;
 #endif
 
     /**
-     * Multiply the entire matrix by a
-     * fixed factor.
+     * Multiply the entire matrix by a fixed factor.
      */
     MatrixBase &operator *= (const PetscScalar factor);
 
     /**
-     * Divide the entire matrix by a
-     * fixed factor.
+     * Divide the entire matrix by a fixed factor.
      */
     MatrixBase &operator /= (const PetscScalar factor);
 
@@ -962,131 +713,82 @@ namespace PETScWrappers
                      const PetscScalar factor);
 
     /**
-     * Matrix-vector multiplication:
-     * let <i>dst = M*src</i> with
-     * <i>M</i> being this matrix.
+     * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
+     * being this matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     void vmult (VectorBase       &dst,
                 const VectorBase &src) const;
 
     /**
-     * Matrix-vector multiplication: let
-     * <i>dst = M<sup>T</sup>*src</i> with
-     * <i>M</i> being this matrix. This
-     * function does the same as vmult()
-     * but takes the transposed matrix.
+     * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
+     * <i>M</i> being this matrix. This function does the same as vmult() but
+     * takes the transposed matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     void Tvmult (VectorBase       &dst,
                  const VectorBase &src) const;
 
     /**
-     * Adding Matrix-vector
-     * multiplication. Add
-     * <i>M*src</i> on <i>dst</i>
-     * with <i>M</i> being this
-     * matrix.
+     * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
+     * with <i>M</i> being this matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     void vmult_add (VectorBase       &dst,
                     const VectorBase &src) const;
 
     /**
-     * Adding Matrix-vector
-     * multiplication. Add
-     * <i>M<sup>T</sup>*src</i> to
-     * <i>dst</i> with <i>M</i> being
-     * this matrix. This function
-     * does the same as vmult_add()
-     * but takes the transposed
-     * matrix.
+     * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+     * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+     * as vmult_add() but takes the transposed matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     void Tvmult_add (VectorBase       &dst,
                      const VectorBase &src) const;
 
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to be
-     * <i>r=b-Mx</i>. Write the
-     * residual into
-     * @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned.
      *
-     * Source <i>x</i> and destination
-     * <i>dst</i> must not be the same
-     * vector.
+     * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then all vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then all vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     PetscScalar residual (VectorBase       &dst,
                           const VectorBase &x,
                           const VectorBase &b) const;
 
     /**
-     * STL-like iterator with the
-     * first entry.
+     * STL-like iterator with the first entry.
      */
     const_iterator begin () const;
 
@@ -1096,57 +798,42 @@ namespace PETScWrappers
     const_iterator end () const;
 
     /**
-     * STL-like iterator with the
-     * first entry of row @p r.
+     * STL-like iterator with the first entry of row @p r.
      *
-     * Note that if the given row is empty,
-     * i.e. does not contain any nonzero
-     * entries, then the iterator returned by
-     * this function equals
-     * <tt>end(r)</tt>. Note also that the
-     * iterator may not be dereferencable in
-     * that case.
+     * Note that if the given row is empty, i.e. does not contain any nonzero
+     * entries, then the iterator returned by this function equals
+     * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable
+     * in that case.
      */
     const_iterator begin (const size_type r) const;
 
     /**
-     * Final iterator of row <tt>r</tt>. It
-     * points to the first element past the
-     * end of line @p r, or past the end of
-     * the entire sparsity pattern.
+     * Final iterator of row <tt>r</tt>. It points to the first element past
+     * the end of line @p r, or past the end of the entire sparsity pattern.
      *
-     * Note that the end iterator is not
-     * necessarily dereferencable. This is in
-     * particular the case if it is the end
-     * iterator for the last row of a matrix.
+     * Note that the end iterator is not necessarily dereferencable. This is
+     * in particular the case if it is the end iterator for the last row of a
+     * matrix.
      */
     const_iterator end (const size_type r) const;
 
     /**
-     * Conversion operator to gain access
-     * to the underlying PETSc type. If you
-     * do this, you cut this class off some
-     * information it may need, so this
-     * conversion operator should only be
-     * used if you know what you do. In
-     * particular, it should only be used
-     * for read-only operations into the
+     * Conversion operator to gain access to the underlying PETSc type. If you
+     * do this, you cut this class off some information it may need, so this
+     * conversion operator should only be used if you know what you do. In
+     * particular, it should only be used for read-only operations into the
      * matrix.
      */
     operator Mat () const;
 
     /**
-     * Make an in-place transpose of a
-     * matrix.
+     * Make an in-place transpose of a matrix.
      */
     void transpose ();
 
     /**
-     * Test whether a matrix is
-     * symmetric.  Default
-     * tolerance is
-     * $1000\times32$-bit machine
-     * precision.
+     * Test whether a matrix is symmetric.  Default tolerance is
+     * $1000\times32$-bit machine precision.
      */
 #if DEAL_II_PETSC_VERSION_LT(3,2,0)
     PetscTruth
@@ -1156,12 +843,8 @@ namespace PETScWrappers
     is_symmetric (const double tolerance = 1.e-12);
 
     /**
-     * Test whether a matrix is
-     * Hermitian, i.e. it is the
-     * complex conjugate of its
-     * transpose. Default
-     * tolerance is
-     * $1000\times32$-bit machine
+     * Test whether a matrix is Hermitian, i.e. it is the complex conjugate of
+     * its transpose. Default tolerance is $1000\times32$-bit machine
      * precision.
      */
 #if DEAL_II_PETSC_VERSION_LT(3,2,0)
@@ -1172,25 +855,23 @@ namespace PETScWrappers
     is_hermitian (const double tolerance = 1.e-12);
 
     /**
-     * Prints the PETSc matrix object values
-     * using PETSc internal matrix viewer function
-     * <tt>MatView</tt>. The default format prints
-     * the non-zero matrix elements. For other valid
-     * view formats, consult
-     * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatView.html
+     * Prints the PETSc matrix object values using PETSc internal matrix
+     * viewer function <tt>MatView</tt>. The default format prints the non-
+     * zero matrix elements. For other valid view formats, consult
+     * http://www.mcs.anl.gov/petsc/petsc-
+     * current/docs/manualpages/Mat/MatView.html
      */
     void write_ascii (const PetscViewerFormat format = PETSC_VIEWER_DEFAULT);
 
     /**
-     * print command, similar to write_ascii, but the same format as
-     * produced by Trilinos
+     * print command, similar to write_ascii, but the same format as produced
+     * by Trilinos
      */
     void print (std::ostream &out,
                 const bool    alternative_output = false) const;
 
     /**
-     *  Returns the number bytes consumed
-     *  by this matrix on this CPU.
+     * Returns the number bytes consumed by this matrix on this CPU.
      */
     std::size_t memory_consumption() const;
 
@@ -1207,8 +888,8 @@ namespace PETScWrappers
     DeclException0 (ExcSourceEqualsDestination);
 
     /**
-      * Exception.
-      */
+     * Exception.
+     */
     DeclException2 (ExcWrongMode,
                     int, int,
                     << "You tried to do a "
@@ -1225,31 +906,21 @@ namespace PETScWrappers
 
   protected:
     /**
-     * A generic matrix object in
-     * PETSc. The actual type, a sparse
-     * matrix, is set in the constructor.
+     * A generic matrix object in PETSc. The actual type, a sparse matrix, is
+     * set in the constructor.
      */
     Mat matrix;
 
     /**
-     * PETSc doesn't allow to mix additions
-     * to matrix entries and overwriting
-     * them (to make synchronisation of
-     * parallel computations
-     * simpler). Since the interface of the
-     * existing classes don't support the
-     * notion of not interleaving things,
-     * we have to emulate this
-     * ourselves. The way we do it is to,
-     * for each access operation, store
-     * whether it is an insertion or an
-     * addition. If the previous one was of
-     * different type, then we first have
-     * to flush the PETSc buffers;
-     * otherwise, we can simply go on.
+     * PETSc doesn't allow to mix additions to matrix entries and overwriting
+     * them (to make synchronisation of parallel computations simpler). Since
+     * the interface of the existing classes don't support the notion of not
+     * interleaving things, we have to emulate this ourselves. The way we do
+     * it is to, for each access operation, store whether it is an insertion
+     * or an addition. If the previous one was of different type, then we
+     * first have to flush the PETSc buffers; otherwise, we can simply go on.
      *
-     * The following structure and variable
-     * declare and store the previous
+     * The following structure and variable declare and store the previous
      * state.
      */
     struct LastAction
@@ -1258,50 +929,32 @@ namespace PETScWrappers
     };
 
     /**
-     * Store whether the last action was a
-     * write or add operation.
+     * Store whether the last action was a write or add operation.
      */
     LastAction::Values last_action;
 
     /**
-     * Ensure that the add/set mode that
-     * is required for actions following
-     * this call is compatible with the
-     * current mode.
-     * Should be called from all internal
-     * functions accessing matrix elements.
+     * Ensure that the add/set mode that is required for actions following
+     * this call is compatible with the current mode. Should be called from
+     * all internal functions accessing matrix elements.
      */
     void prepare_action(const LastAction::Values new_action);
 
     /**
-     * For some matrix storage
-     * formats, in particular for the
-     * PETSc distributed blockmatrices,
-     * set and add operations on
-     * individual elements can not be
-     * freely mixed. Rather, one has
-     * to synchronize operations when
-     * one wants to switch from
-     * setting elements to adding to
-     * elements.
-     * BlockMatrixBase automatically
-     * synchronizes the access by
-     * calling this helper function
-     * for each block.
-     * This function ensures that the
-     * matrix is in a state that
-     * allows adding elements; if it
-     * previously already was in this
-     * state, the function does
-     * nothing.
+     * For some matrix storage formats, in particular for the PETSc
+     * distributed blockmatrices, set and add operations on individual
+     * elements can not be freely mixed. Rather, one has to synchronize
+     * operations when one wants to switch from setting elements to adding to
+     * elements. BlockMatrixBase automatically synchronizes the access by
+     * calling this helper function for each block. This function ensures that
+     * the matrix is in a state that allows adding elements; if it previously
+     * already was in this state, the function does nothing.
      */
     void prepare_add();
     /**
-     * Same as prepare_add() but
-     * prepare the matrix for setting
-     * elements if the representation
-     * of elements in this class
-     * requires such an operation.
+     * Same as prepare_add() but prepare the matrix for setting elements if
+     * the representation of elements in this class requires such an
+     * operation.
      */
     void prepare_set();
 
@@ -1319,28 +972,22 @@ namespace PETScWrappers
     MatrixBase &operator=(const MatrixBase &);
 
     /**
-     * An internal array of integer
-     * values that is used to store the
-     * column indices when
-     * adding/inserting local data into
-     * the (large) sparse matrix.
+     * An internal array of integer values that is used to store the column
+     * indices when adding/inserting local data into the (large) sparse
+     * matrix.
      */
     std::vector<PetscInt> column_indices;
 
     /**
-     * An internal array of double values
-     * that is used to store the column
-     * indices when adding/inserting
-     * local data into the (large) sparse
+     * An internal array of double values that is used to store the column
+     * indices when adding/inserting local data into the (large) sparse
      * matrix.
      */
     std::vector<PetscScalar> column_values;
 
 
     /**
-     *  To allow calling protected
-     *  prepare_add() and
-     *  prepare_set().
+     * To allow calling protected prepare_add() and prepare_set().
      */
     template <class> friend class dealii::BlockMatrixBase;
   };
index 98d2bc31a6426f1a8c5a3714ab51b1e681aa97ee..f0cc8c995cdce4a09989e14860049d1a9729dc69 100644 (file)
@@ -32,29 +32,30 @@ DEAL_II_NAMESPACE_OPEN
 namespace PETScWrappers
 {
   /**
-   * Implementation of a parallel matrix class based on PETSc <tt>MatShell</tt> matrix-type.
-   * This base class implements only the interface to the PETSc matrix object,
-   * while all the functionality is contained in the matrix-vector
-   * multiplication which must be reimplemented in derived classes.
+   * Implementation of a parallel matrix class based on PETSc
+   * <tt>MatShell</tt> matrix-type. This base class implements only the
+   * interface to the PETSc matrix object, while all the functionality is
+   * contained in the matrix-vector multiplication which must be reimplemented
+   * in derived classes.
    *
    * This interface is an addition to the dealii::MatrixFree class to realize
-   * user-defined matrix-classes together with PETSc solvers and functionalities.
-   * See also the documentation of dealii::MatrixFree class and step-37 and step-48.
+   * user-defined matrix-classes together with PETSc solvers and
+   * functionalities. See also the documentation of dealii::MatrixFree class
+   * and step-37 and step-48.
    *
-   * Similar to other matrix classes in namespaces PETScWrappers and PETScWrappers::MPI,
-   * the MatrixFree class provides the usual matrix-vector multiplication
-   *   <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
+   * Similar to other matrix classes in namespaces PETScWrappers and
+   * PETScWrappers::MPI, the MatrixFree class provides the usual matrix-vector
+   * multiplication <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
    * which is pure virtual and must be reimplemented in derived classes.
-   * Besides the usual interface, this class has a matrix-vector multiplication
-   *   <tt>vmult(Vec  &dst, const Vec  &src)</tt>
-   * taking PETSc Vec objects, which will be called by
-   *   <tt>matrix_free_mult(Mat A, Vec src, Vec dst)</tt>
-   * registered as matrix-vector multiplication of this PETSc matrix object.
-   * The default implementation of the vmult function in the base class translates
-   * the given PETSc <tt>Vec*</tt> vectors into a deal.II vector, calls
-   * the usual vmult function with the usual interface and converts
-   * the result back to PETSc <tt>Vec*</tt>. This could be made much more efficient
-   * in derived classes without allocating new memory.
+   * Besides the usual interface, this class has a matrix-vector
+   * multiplication <tt>vmult(Vec  &dst, const Vec  &src)</tt> taking PETSc
+   * Vec objects, which will be called by <tt>matrix_free_mult(Mat A, Vec src,
+   * Vec dst)</tt> registered as matrix-vector multiplication of this PETSc
+   * matrix object. The default implementation of the vmult function in the
+   * base class translates the given PETSc <tt>Vec*</tt> vectors into a
+   * deal.II vector, calls the usual vmult function with the usual interface
+   * and converts the result back to PETSc <tt>Vec*</tt>. This could be made
+   * much more efficient in derived classes without allocating new memory.
    *
    * @ingroup PETScWrappers
    * @ingroup Matrix1
@@ -65,32 +66,23 @@ namespace PETScWrappers
   public:
 
     /**
-     * Default constructor. Create an
-     * empty matrix object.
+     * Default constructor. Create an empty matrix object.
      */
     MatrixFree ();
 
     /**
-     * Create a matrix object of
-     * dimensions @p m times @p n
-     * with communication happening
-     * over the provided @p communicator.
+     * Create a matrix object of dimensions @p m times @p n with communication
+     * happening over the provided @p communicator.
      *
-     * For the meaning of the @p local_rows
-     * and @p local_columns parameters,
-     * see the PETScWrappers::MPI::SparseMatrix
-     * class documentation.
+     * For the meaning of the @p local_rows and @p local_columns parameters,
+     * see the PETScWrappers::MPI::SparseMatrix class documentation.
      *
-     * As other PETSc matrices, also the
-     * the matrix-free object needs to
-     * have a size and to perform matrix
-     * vector multiplications efficiently
-     * in parallel also @p local_rows
-     * and @p local_columns. But in contrast
-     * to PETSc::SparseMatrix classes a
-     * PETSc matrix-free object does not need
-     * any estimation of non_zero entries
-     * and has no option <tt>is_symmetric</tt>.
+     * As other PETSc matrices, also the the matrix-free object needs to have
+     * a size and to perform matrix vector multiplications efficiently in
+     * parallel also @p local_rows and @p local_columns. But in contrast to
+     * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
+     * any estimation of non_zero entries and has no option
+     * <tt>is_symmetric</tt>.
      */
     MatrixFree (const MPI_Comm     &communicator,
                 const unsigned int  m,
@@ -99,21 +91,15 @@ namespace PETScWrappers
                 const unsigned int  local_columns);
 
     /**
-     * Create a matrix object of
-     * dimensions @p m times @p n
-     * with communication happening
-     * over the provided @p communicator.
+     * Create a matrix object of dimensions @p m times @p n with communication
+     * happening over the provided @p communicator.
      *
-     * As other PETSc matrices, also the
-     * the matrix-free object needs to
-     * have a size and to perform matrix
-     * vector multiplications efficiently
-     * in parallel also @p local_rows
-     * and @p local_columns. But in contrast
-     * to PETSc::SparseMatrix classes a
-     * PETSc matrix-free object does not need
-     * any estimation of non_zero entries
-     * and has no option <tt>is_symmetric</tt>.
+     * As other PETSc matrices, also the the matrix-free object needs to have
+     * a size and to perform matrix vector multiplications efficiently in
+     * parallel also @p local_rows and @p local_columns. But in contrast to
+     * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
+     * any estimation of non_zero entries and has no option
+     * <tt>is_symmetric</tt>.
      */
     MatrixFree (const MPI_Comm     &communicator,
                 const unsigned int  m,
@@ -123,10 +109,9 @@ namespace PETScWrappers
                 const unsigned int  this_process);
 
     /**
-     * Constructor for the serial case:
-     * Same function as
-     * <tt>MatrixFree()</tt>, see above,
-     * with <tt>communicator = MPI_COMM_WORLD</tt>.
+     * Constructor for the serial case: Same function as
+     * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
+     * MPI_COMM_WORLD</tt>.
      */
     MatrixFree (const unsigned int  m,
                 const unsigned int  n,
@@ -134,10 +119,9 @@ namespace PETScWrappers
                 const unsigned int  local_columns);
 
     /**
-     * Constructor for the serial case:
-     * Same function as
-     * <tt>MatrixFree()</tt>, see above,
-     * with <tt>communicator = MPI_COMM_WORLD</tt>.
+     * Constructor for the serial case: Same function as
+     * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
+     * MPI_COMM_WORLD</tt>.
      */
     MatrixFree (const unsigned int  m,
                 const unsigned int  n,
@@ -146,12 +130,9 @@ namespace PETScWrappers
                 const unsigned int  this_process);
 
     /**
-     * Throw away the present matrix and
-     * generate one that has the same
-     * properties as if it were created by
-     * the constructor of this class with
-     * the same argument list as the
-     * present function.
+     * Throw away the present matrix and generate one that has the same
+     * properties as if it were created by the constructor of this class with
+     * the same argument list as the present function.
      */
     void reinit (const MPI_Comm     &communicator,
                  const unsigned int  m,
@@ -160,12 +141,9 @@ namespace PETScWrappers
                  const unsigned int  local_columns);
 
     /**
-     * Throw away the present matrix and
-     * generate one that has the same
-     * properties as if it were created by
-     * the constructor of this class with
-     * the same argument list as the
-     * present function.
+     * Throw away the present matrix and generate one that has the same
+     * properties as if it were created by the constructor of this class with
+     * the same argument list as the present function.
      */
     void reinit (const MPI_Comm     &communicator,
                  const unsigned int  m,
@@ -175,8 +153,8 @@ namespace PETScWrappers
                  const unsigned int  this_process);
 
     /**
-     * Calls the @p reinit() function
-     * above with <tt>communicator = MPI_COMM_WORLD</tt>.
+     * Calls the @p reinit() function above with <tt>communicator =
+     * MPI_COMM_WORLD</tt>.
      */
     void reinit (const unsigned int  m,
                  const unsigned int  n,
@@ -184,8 +162,8 @@ namespace PETScWrappers
                  const unsigned int  local_columns);
 
     /**
-     * Calls the @p reinit() function
-     * above with <tt>communicator = MPI_COMM_WORLD</tt>.
+     * Calls the @p reinit() function above with <tt>communicator =
+     * MPI_COMM_WORLD</tt>.
      */
     void reinit (const unsigned int  m,
                  const unsigned int  n,
@@ -194,58 +172,42 @@ namespace PETScWrappers
                  const unsigned int  this_process);
 
     /**
-     * Release all memory and return
-     * to a state just like after
-     * having called the default
-     * constructor.
+     * Release all memory and return to a state just like after having called
+     * the default constructor.
      */
     void clear ();
 
     /**
-     * Return a reference to the MPI
-     * communicator object in use with
-     * this matrix.
+     * Return a reference to the MPI communicator object in use with this
+     * matrix.
      */
     const MPI_Comm &get_mpi_communicator () const;
 
     /**
-     * Matrix-vector multiplication:
-     * let <i>dst = M*src</i> with
-     * <i>M</i> being this matrix.
+     * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
+     * being this matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix (of type
-     * PETScWrappers::MPI::SparseMatrix),
-     * then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
-     * vectors may be.
+     * Note that if the current object represents a parallel distributed
+     * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+     * have to be distributed vectors as well. Conversely, if the matrix is
+     * not distributed, then neither of the vectors may be.
      */
     virtual
     void vmult (VectorBase       &dst,
                 const VectorBase &src) const = 0;
 
     /**
-     * Matrix-vector multiplication: let
-     * <i>dst = M<sup>T</sup>*src</i> with
-     * <i>M</i> being this matrix. This
-     * function does the same as @p vmult()
+     * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
+     * <i>M</i> being this matrix. This function does the same as @p vmult()
      * but takes the transposed matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
+     * Note that if the current object represents a parallel distributed
+     * matrix then both vectors have to be distributed vectors as well.
+     * Conversely, if the matrix is not distributed, then neither of the
      * vectors may be.
      */
     virtual
@@ -253,21 +215,14 @@ namespace PETScWrappers
                  const VectorBase &src) const = 0;
 
     /**
-     * Adding Matrix-vector
-     * multiplication. Add
-     * <i>M*src</i> on <i>dst</i>
-     * with <i>M</i> being this
-     * matrix.
+     * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
+     * with <i>M</i> being this matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
+     * Note that if the current object represents a parallel distributed
+     * matrix then both vectors have to be distributed vectors as well.
+     * Conversely, if the matrix is not distributed, then neither of the
      * vectors may be.
      */
     virtual
@@ -275,24 +230,15 @@ namespace PETScWrappers
                     const VectorBase &src) const = 0;
 
     /**
-     * Adding Matrix-vector
-     * multiplication. Add
-     * <i>M<sup>T</sup>*src</i> to
-     * <i>dst</i> with <i>M</i> being
-     * this matrix. This function
-     * does the same as @p vmult_add()
-     * but takes the transposed
-     * matrix.
+     * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+     * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+     * as @p vmult_add() but takes the transposed matrix.
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * Note that if the current object
-     * represents a parallel distributed
-     * matrix then both vectors have to be
-     * distributed vectors as
-     * well. Conversely, if the matrix is
-     * not distributed, then neither of the
+     * Note that if the current object represents a parallel distributed
+     * matrix then both vectors have to be distributed vectors as well.
+     * Conversely, if the matrix is not distributed, then neither of the
      * vectors may be.
      */
     virtual
@@ -300,14 +246,11 @@ namespace PETScWrappers
                      const VectorBase &src) const = 0;
 
     /**
-     * The matrix-vector multiplication
-     * called by @p matrix_free_mult().
-     * This function can be reimplemented
-     * in derived classes for efficiency. The default
-     * implementation copies the given vectors
-     * into PETScWrappers::*::Vector
-     * and calls <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
-     * which is purely virtual and must be reimplemented
+     * The matrix-vector multiplication called by @p matrix_free_mult(). This
+     * function can be reimplemented in derived classes for efficiency. The
+     * default implementation copies the given vectors into
+     * PETScWrappers::*::Vector and calls <tt>vmult(VectorBase &dst, const
+     * VectorBase &src)</tt> which is purely virtual and must be reimplemented
      * in derived classes.
      */
     virtual
@@ -316,38 +259,28 @@ namespace PETScWrappers
   private:
 
     /**
-     * Copy of the communicator object to
-     * be used for this parallel matrix-free object.
+     * Copy of the communicator object to be used for this parallel matrix-
+     * free object.
      */
     MPI_Comm  communicator;
 
     /**
-     * Callback-function registered
-     * as the matrix-vector multiplication
-     * of this matrix-free object
-     * called by PETSc routines.
-     * This function must be static and
-     * takes a PETSc matrix @p A,
-     * and vectors @p src and @p dst,
+     * Callback-function registered as the matrix-vector multiplication of
+     * this matrix-free object called by PETSc routines. This function must be
+     * static and takes a PETSc matrix @p A, and vectors @p src and @p dst,
      * where <i>dst = A*src</i>
      *
-     * Source and destination must
-     * not be the same vector.
+     * Source and destination must not be the same vector.
      *
-     * This function calls
-     * <tt>vmult(Vec &dst, const Vec &src)</tt>
-     * which should be reimplemented in
-     * derived classes.
+     * This function calls <tt>vmult(Vec &dst, const Vec &src)</tt> which
+     * should be reimplemented in derived classes.
      */
     static int matrix_free_mult (Mat  A, Vec  src, Vec  dst);
 
     /**
-     * Do the actual work for the
-     * respective @p reinit() function and
-     * the matching constructor,
-     * i.e. create a matrix object. Getting rid
-     * of the previous matrix is left to
-     * the caller.
+     * Do the actual work for the respective @p reinit() function and the
+     * matching constructor, i.e. create a matrix object. Getting rid of the
+     * previous matrix is left to the caller.
      */
     void do_reinit (const unsigned int  m,
                     const unsigned int  n,
index ef4dda3377946a3d360c02257f8e45683350fbd0..b535a8ce72aaba416deeff2fbe01b1894791ef20 100644 (file)
@@ -43,45 +43,42 @@ namespace PETScWrappers
      */
 
     /**
-     * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class. This
-     * class implements the functions that are specific to the PETSc SparseMatrix
-     * base objects for a blocked sparse matrix, and leaves the actual work
-     * relaying most of the calls to the individual blocks to the functions
-     * implemented in the base class. See there also for a description of when
-     * this class is useful.
+     * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class.
+     * This class implements the functions that are specific to the PETSc
+     * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+     * actual work relaying most of the calls to the individual blocks to the
+     * functions implemented in the base class. See there also for a
+     * description of when this class is useful.
      *
-     * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices do
-     * not have external objects for the sparsity patterns. Thus, one does not
-     * determine the size of the individual blocks of a block matrix of this type
-     * by attaching a block sparsity pattern, but by calling reinit() to set the
-     * number of blocks and then by setting the size of each block separately. In
-     * order to fix the data structures of the block matrix, it is then necessary
-     * to let it know that we have changed the sizes of the underlying
-     * matrices. For this, one has to call the collect_sizes() function, for much
-     * the same reason as is documented with the BlockSparsityPattern class.
+     * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices
+     * do not have external objects for the sparsity patterns. Thus, one does
+     * not determine the size of the individual blocks of a block matrix of
+     * this type by attaching a block sparsity pattern, but by calling
+     * reinit() to set the number of blocks and then by setting the size of
+     * each block separately. In order to fix the data structures of the block
+     * matrix, it is then necessary to let it know that we have changed the
+     * sizes of the underlying matrices. For this, one has to call the
+     * collect_sizes() function, for much the same reason as is documented
+     * with the BlockSparsityPattern class.
      *
-     * @ingroup Matrix1
-     * @see @ref GlossBlockLA "Block (linear algebra)"
+     * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
      * @author Wolfgang Bangerth, 2004
      */
     class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix>
     {
     public:
       /**
-       * Typedef the base class for simpler
-       * access to its own typedefs.
+       * Typedef the base class for simpler access to its own typedefs.
        */
       typedef BlockMatrixBase<SparseMatrix> BaseClass;
 
       /**
-       * Typedef the type of the underlying
-       * matrix.
+       * Typedef the type of the underlying matrix.
        */
       typedef BaseClass::BlockType  BlockType;
 
       /**
-       * Import the typedefs from the base
-       * class.
+       * Import the typedefs from the base class.
        */
       typedef BaseClass::value_type      value_type;
       typedef BaseClass::pointer         pointer;
@@ -93,25 +90,15 @@ namespace PETScWrappers
       typedef BaseClass::const_iterator  const_iterator;
 
       /**
-       * Constructor; initializes the
-       * matrix to be empty, without
-       * any structure, i.e.  the
-       * matrix is not usable at
-       * all. This constructor is
-       * therefore only useful for
-       * matrices which are members of
-       * a class. All other matrices
-       * should be created at a point
-       * in the data flow where all
-       * necessary information is
-       * available.
+       * Constructor; initializes the matrix to be empty, without any
+       * structure, i.e.  the matrix is not usable at all. This constructor is
+       * therefore only useful for matrices which are members of a class. All
+       * other matrices should be created at a point in the data flow where
+       * all necessary information is available.
        *
-       * You have to initialize the
-       * matrix before usage with
-       * reinit(BlockSparsityPattern). The
-       * number of blocks per row and
-       * column are then determined by
-       * that function.
+       * You have to initialize the matrix before usage with
+       * reinit(BlockSparsityPattern). The number of blocks per row and column
+       * are then determined by that function.
        */
       BlockSparseMatrix ();
 
@@ -121,71 +108,49 @@ namespace PETScWrappers
       ~BlockSparseMatrix ();
 
       /**
-       * Pseudo copy operator only copying
-       * empty objects. The sizes of the
-       * block matrices need to be the
-       * same.
+       * Pseudo copy operator only copying empty objects. The sizes of the
+       * block matrices need to be the same.
        */
       BlockSparseMatrix &
       operator = (const BlockSparseMatrix &);
 
       /**
-       * This operator assigns a scalar to
-       * a matrix. Since this does usually
-       * not make much sense (should we set
-       * all matrix entries to this value?
-       * Only the nonzero entries of the
-       * sparsity pattern?), this operation
-       * is only allowed if the actual
-       * value to be assigned is zero. This
-       * operator only exists to allow for
-       * the obvious notation
-       * <tt>matrix=0</tt>, which sets all
-       * elements of the matrix to zero,
-       * but keep the sparsity pattern
-       * previously used.
+       * This operator assigns a scalar to a matrix. Since this does usually
+       * not make much sense (should we set all matrix entries to this value?
+       * Only the nonzero entries of the sparsity pattern?), this operation is
+       * only allowed if the actual value to be assigned is zero. This
+       * operator only exists to allow for the obvious notation
+       * <tt>matrix=0</tt>, which sets all elements of the matrix to zero, but
+       * keep the sparsity pattern previously used.
        */
       BlockSparseMatrix &
       operator = (const double d);
 
       /**
-       * Resize the matrix, by setting
-       * the number of block rows and
-       * columns. This deletes all
-       * blocks and replaces them by
-       * unitialized ones, i.e. ones
-       * for which also the sizes are
-       * not yet set. You have to do
-       * that by calling the @p reinit
-       * functions of the blocks
-       * themselves. Do not forget to
-       * call collect_sizes() after
-       * that on this object.
+       * Resize the matrix, by setting the number of block rows and columns.
+       * This deletes all blocks and replaces them by unitialized ones, i.e.
+       * ones for which also the sizes are not yet set. You have to do that by
+       * calling the @p reinit functions of the blocks themselves. Do not
+       * forget to call collect_sizes() after that on this object.
        *
-       * The reason that you have to
-       * set sizes of the blocks
-       * yourself is that the sizes may
-       * be varying, the maximum number
-       * of elements per row may be
-       * varying, etc. It is simpler
-       * not to reproduce the interface
-       * of the SparsityPattern
-       * class here but rather let the
-       * user call whatever function
-       * she desires.
+       * The reason that you have to set sizes of the blocks yourself is that
+       * the sizes may be varying, the maximum number of elements per row may
+       * be varying, etc. It is simpler not to reproduce the interface of the
+       * SparsityPattern class here but rather let the user call whatever
+       * function she desires.
        */
       void reinit (const size_type n_block_rows,
                    const size_type n_block_columns);
 
 
       /**
-       * Efficiently reinit the block matrix for a parallel computation.
-       * Only the BlockSparsityPattern of the Simple type can efficiently
-       * store large sparsity patterns in parallel, so this is the only
-       * supported argument.
-       * The IndexSets describe the locally owned range of DoFs for each block.
-       * Note that each IndexSet needs to be contiguous. For a symmetric structure
-       * hand in the same vector for the first two arguments.
+       * Efficiently reinit the block matrix for a parallel computation. Only
+       * the BlockSparsityPattern of the Simple type can efficiently store
+       * large sparsity patterns in parallel, so this is the only supported
+       * argument. The IndexSets describe the locally owned range of DoFs for
+       * each block. Note that each IndexSet needs to be contiguous. For a
+       * symmetric structure hand in the same vector for the first two
+       * arguments.
        */
       void reinit(const std::vector<IndexSet> &rows,
                   const std::vector<IndexSet> &cols,
@@ -203,108 +168,79 @@ namespace PETScWrappers
 
 
       /**
-       * Matrix-vector multiplication:
-       * let $dst = M*src$ with $M$
-       * being this matrix.
+       * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+       * matrix.
        */
       void vmult (BlockVector       &dst,
                   const BlockVector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block column.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block column.
        */
       void vmult (BlockVector          &dst,
                   const Vector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block row.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block row.
        */
       void vmult (Vector    &dst,
                   const BlockVector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block.
        */
       void vmult (Vector       &dst,
                   const Vector &src) const;
 
       /**
-       * Matrix-vector multiplication:
-       * let $dst = M^T*src$ with $M$
-       * being this matrix. This
-       * function does the same as
-       * vmult() but takes the
+       * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+       * matrix. This function does the same as vmult() but takes the
        * transposed matrix.
        */
       void Tvmult (BlockVector       &dst,
                    const BlockVector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block row.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block row.
        */
       void Tvmult (BlockVector  &dst,
                    const Vector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block column.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block column.
        */
       void Tvmult (Vector    &dst,
                    const BlockVector &src) const;
 
       /**
-       * Matrix-vector
-       * multiplication. Just like the
-       * previous function, but only
-       * applicable if the matrix has
-       * only one block.
+       * Matrix-vector multiplication. Just like the previous function, but
+       * only applicable if the matrix has only one block.
        */
       void Tvmult (Vector       &dst,
                    const Vector &src) const;
 
       /**
-       * This function collects the
-       * sizes of the sub-objects and
-       * stores them in internal
-       * arrays, in order to be able to
-       * relay global indices into the
-       * matrix to indices into the
-       * subobjects. You *must* call
-       * this function each time after
-       * you have changed the size of
-       * the sub-objects.
+       * This function collects the sizes of the sub-objects and stores them
+       * in internal arrays, in order to be able to relay global indices into
+       * the matrix to indices into the subobjects. You *must* call this
+       * function each time after you have changed the size of the sub-
+       * objects.
        */
       void collect_sizes ();
 
       /**
-       * Return a reference to the MPI
-       * communicator object in use with
-       * this matrix.
+       * Return a reference to the MPI communicator object in use with this
+       * matrix.
        */
       const MPI_Comm &get_mpi_communicator () const;
 
       /**
-       * Make the clear() function in the
-       * base class visible, though it is
+       * Make the clear() function in the base class visible, though it is
        * protected.
        */
       using BlockMatrixBase<SparseMatrix>::clear;
index b560e1a1ff5ffe0c2c9175c30662bc597a91dcde..68be3bb698d012be52577faefe6e1a64df20117f 100644 (file)
@@ -43,39 +43,35 @@ namespace PETScWrappers
 
     /**
      * An implementation of block vectors based on the parallel vector class
-     * implemented in PETScWrappers. While the base class provides for most of the
-     * interface, this class handles the actual allocation of vectors and provides
-     * functions that are specific to the underlying vector type.
+     * implemented in PETScWrappers. While the base class provides for most of
+     * the interface, this class handles the actual allocation of vectors and
+     * provides functions that are specific to the underlying vector type.
      *
      * The model of distribution of data is such that each of the blocks is
-     * distributed across all MPI processes named in the MPI communicator. I.e. we
-     * don't just distribute the whole vector, but each component. In the
-     * constructors and reinit() functions, one therefore not only has to specify
-     * the sizes of the individual blocks, but also the number of elements of each
-     * of these blocks to be stored on the local process.
+     * distributed across all MPI processes named in the MPI communicator.
+     * I.e. we don't just distribute the whole vector, but each component. In
+     * the constructors and reinit() functions, one therefore not only has to
+     * specify the sizes of the individual blocks, but also the number of
+     * elements of each of these blocks to be stored on the local process.
      *
-     * @ingroup Vectors
-     * @see @ref GlossBlockLA "Block (linear algebra)"
+     * @ingroup Vectors @see @ref GlossBlockLA "Block (linear algebra)"
      * @author Wolfgang Bangerth, 2004
      */
     class BlockVector : public BlockVectorBase<Vector>
     {
     public:
       /**
-       * Typedef the base class for simpler
-       * access to its own typedefs.
+       * Typedef the base class for simpler access to its own typedefs.
        */
       typedef BlockVectorBase<Vector> BaseClass;
 
       /**
-       * Typedef the type of the underlying
-       * vector.
+       * Typedef the type of the underlying vector.
        */
       typedef BaseClass::BlockType  BlockType;
 
       /**
-       * Import the typedefs from the base
-       * class.
+       * Import the typedefs from the base class.
        */
       typedef BaseClass::value_type      value_type;
       typedef BaseClass::pointer         pointer;
@@ -87,19 +83,15 @@ namespace PETScWrappers
       typedef BaseClass::const_iterator  const_iterator;
 
       /**
-       * Default constructor. Generate an
-       * empty vector without any blocks.
+       * Default constructor. Generate an empty vector without any blocks.
        */
       BlockVector ();
 
       /**
-       *  Constructor. Generate a block
-       *  vector with @p n_blocks blocks,
-       *  each of which is a parallel
-       *  vector across @p communicator
-       *  with @p block_size elements of
-       *  which @p local_size elements are
-       *  stored on the present process.
+       * Constructor. Generate a block vector with @p n_blocks blocks, each of
+       * which is a parallel vector across @p communicator with @p block_size
+       * elements of which @p local_size elements are stored on the present
+       * process.
        */
       explicit BlockVector (const unsigned int  n_blocks,
                             const MPI_Comm     &communicator,
@@ -107,32 +99,25 @@ namespace PETScWrappers
                             const size_type     local_size);
 
       /**
-       * Copy-Constructor. Set all the
-       * properties of the parallel vector
-       * to those of the given argument and
-       * copy the elements.
+       * Copy-Constructor. Set all the properties of the parallel vector to
+       * those of the given argument and copy the elements.
        */
       BlockVector (const BlockVector  &V);
 
       /**
-       * Constructor. Set the number of
-       * blocks to
-       * <tt>block_sizes.size()</tt> and
-       * initialize each block with
-       * <tt>block_sizes[i]</tt> zero
-       * elements. The individual blocks
-       * are distributed across the given
-       * communicator, and each store
-       * <tt>local_elements[i]</tt>
-       * elements on the present process.
+       * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt>
+       * and initialize each block with <tt>block_sizes[i]</tt> zero elements.
+       * The individual blocks are distributed across the given communicator,
+       * and each store <tt>local_elements[i]</tt> elements on the present
+       * process.
        */
       BlockVector (const std::vector<size_type> &block_sizes,
                    const MPI_Comm               &communicator,
                    const std::vector<size_type> &local_elements);
 
       /**
-       * Create a BlockVector with parallel_partitioning.size() blocks,
-       * each initialized with the given IndexSet.
+       * Create a BlockVector with parallel_partitioning.size() blocks, each
+       * initialized with the given IndexSet.
        */
       explicit BlockVector (const std::vector<IndexSet> &parallel_partitioning,
                             const MPI_Comm &communicator = MPI_COMM_WORLD);
@@ -152,63 +137,43 @@ namespace PETScWrappers
       ~BlockVector ();
 
       /**
-       * Copy operator: fill all components
-       * of the vector that are locally
+       * Copy operator: fill all components of the vector that are locally
        * stored with the given scalar value.
        */
       BlockVector &operator = (const value_type s);
 
       /**
-       * Copy operator for arguments of the
-       * same type.
+       * Copy operator for arguments of the same type.
        */
       BlockVector &
       operator= (const BlockVector &V);
 
       /**
-       * Copy the given sequential
-       * (non-distributed) block vector
-       * into the present parallel block
-       * vector. It is assumed that they
-       * have the same size, and this
-       * operation does not change the
-       * partitioning of the parallel
-       * vectors by which its elements are
-       * distributed across several MPI
-       * processes. What this operation
-       * therefore does is to copy that
-       * chunk of the given vector @p v
-       * that corresponds to elements of
-       * the target vector that are stored
-       * locally, and copies them, for each
-       * of the individual blocks of this
-       * object. Elements that are not
-       * stored locally are not touched.
+       * Copy the given sequential (non-distributed) block vector into the
+       * present parallel block vector. It is assumed that they have the same
+       * size, and this operation does not change the partitioning of the
+       * parallel vectors by which its elements are distributed across several
+       * MPI processes. What this operation therefore does is to copy that
+       * chunk of the given vector @p v that corresponds to elements of the
+       * target vector that are stored locally, and copies them, for each of
+       * the individual blocks of this object. Elements that are not stored
+       * locally are not touched.
        *
-       * This being a parallel vector, you
-       * must make sure that @em all
-       * processes call this function at
-       * the same time. It is not possible
-       * to change the local part of a
-       * parallel vector on only one
-       * process, independent of what other
-       * processes do, with this function.
+       * This being a parallel vector, you must make sure that @em all
+       * processes call this function at the same time. It is not possible to
+       * change the local part of a parallel vector on only one process,
+       * independent of what other processes do, with this function.
        */
       BlockVector &
       operator = (const PETScWrappers::BlockVector &v);
 
       /**
-       * Reinitialize the BlockVector to
-       * contain @p n_blocks of size @p
-       * block_size, each of which stores
-       * @p local_size elements
-       * locally. The @p communicator
-       * argument denotes which MPI channel
-       * each of these blocks shall
-       * communicate.
+       * Reinitialize the BlockVector to contain @p n_blocks of size @p
+       * block_size, each of which stores @p local_size elements locally. The
+       * @p communicator argument denotes which MPI channel each of these
+       * blocks shall communicate.
        *
-       * If <tt>fast==false</tt>, the vector
-       * is filled with zeros.
+       * If <tt>fast==false</tt>, the vector is filled with zeros.
        */
       void reinit (const unsigned int  n_blocks,
                    const MPI_Comm     &communicator,
@@ -217,39 +182,23 @@ namespace PETScWrappers
                    const bool fast = false);
 
       /**
-       * Reinitialize the BlockVector such
-       * that it contains
-       * <tt>block_sizes.size()</tt>
-       * blocks. Each block is
-       * reinitialized to dimension
-       * <tt>block_sizes[i]</tt>. Each of
-       * them stores
-       * <tt>local_sizes[i]</tt> elements
-       * on the present process.
+       * Reinitialize the BlockVector such that it contains
+       * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
+       * dimension <tt>block_sizes[i]</tt>. Each of them stores
+       * <tt>local_sizes[i]</tt> elements on the present process.
        *
-       * If the number of blocks is the
-       * same as before this function
-       * was called, all vectors remain
-       * the same and reinit() is
-       * called for each vector.
+       * If the number of blocks is the same as before this function was
+       * called, all vectors remain the same and reinit() is called for each
+       * vector.
        *
-       * If <tt>fast==false</tt>, the vector
-       * is filled with zeros.
+       * If <tt>fast==false</tt>, the vector is filled with zeros.
        *
-       * Note that you must call this
-       * (or the other reinit()
-       * functions) function, rather
-       * than calling the reinit()
-       * functions of an individual
-       * block, to allow the block
-       * vector to update its caches of
-       * vector sizes. If you call
-       * reinit() of one of the
-       * blocks, then subsequent
-       * actions on this object may
-       * yield unpredictable results
-       * since they may be routed to
-       * the wrong block.
+       * Note that you must call this (or the other reinit() functions)
+       * function, rather than calling the reinit() functions of an individual
+       * block, to allow the block vector to update its caches of vector
+       * sizes. If you call reinit() of one of the blocks, then subsequent
+       * actions on this object may yield unpredictable results since they may
+       * be routed to the wrong block.
        */
       void reinit (const std::vector<size_type> &block_sizes,
                    const MPI_Comm               &communicator,
@@ -257,30 +206,18 @@ namespace PETScWrappers
                    const bool                    fast=false);
 
       /**
-       * Change the dimension to that
-       * of the vector <tt>V</tt>. The same
-       * applies as for the other
-       * reinit() function.
+       * Change the dimension to that of the vector <tt>V</tt>. The same
+       * applies as for the other reinit() function.
        *
-       * The elements of <tt>V</tt> are not
-       * copied, i.e.  this function is
-       * the same as calling <tt>reinit
-       * (V.size(), fast)</tt>.
+       * The elements of <tt>V</tt> are not copied, i.e.  this function is the
+       * same as calling <tt>reinit (V.size(), fast)</tt>.
        *
-       * Note that you must call this
-       * (or the other reinit()
-       * functions) function, rather
-       * than calling the reinit()
-       * functions of an individual
-       * block, to allow the block
-       * vector to update its caches of
-       * vector sizes. If you call
-       * reinit() on one of the
-       * blocks, then subsequent
-       * actions on this object may
-       * yield unpredictable results
-       * since they may be routed to
-       * the wrong block.
+       * Note that you must call this (or the other reinit() functions)
+       * function, rather than calling the reinit() functions of an individual
+       * block, to allow the block vector to update its caches of vector
+       * sizes. If you call reinit() on one of the blocks, then subsequent
+       * actions on this object may yield unpredictable results since they may
+       * be routed to the wrong block.
        */
       void reinit (const BlockVector &V,
                    const bool         fast=false);
@@ -300,15 +237,10 @@ namespace PETScWrappers
                    const MPI_Comm              &communicator);
 
       /**
-       * Change the number of blocks to
-       * <tt>num_blocks</tt>. The individual
-       * blocks will get initialized with
-       * zero size, so it is assumed that
-       * the user resizes the
-       * individual blocks by herself
-       * in an appropriate way, and
-       * calls <tt>collect_sizes</tt>
-       * afterwards.
+       * Change the number of blocks to <tt>num_blocks</tt>. The individual
+       * blocks will get initialized with zero size, so it is assumed that the
+       * user resizes the individual blocks by herself in an appropriate way,
+       * and calls <tt>collect_sizes</tt> afterwards.
        */
       void reinit (const unsigned int num_blocks);
 
@@ -318,41 +250,27 @@ namespace PETScWrappers
       bool has_ghost_elements() const;
 
       /**
-       * Return a reference to the MPI
-       * communicator object in use with
-       * this vector.
+       * Return a reference to the MPI communicator object in use with this
+       * vector.
        */
       const MPI_Comm &get_mpi_communicator () const;
 
       /**
-       * Swap the contents of this
-       * vector and the other vector
-       * <tt>v</tt>. One could do this
-       * operation with a temporary
-       * variable and copying over the
-       * data elements, but this
-       * function is significantly more
-       * efficient since it only swaps
-       * the pointers to the data of
-       * the two vectors and therefore
-       * does not need to allocate
-       * temporary storage and move
-       * data around.
+       * Swap the contents of this vector and the other vector <tt>v</tt>. One
+       * could do this operation with a temporary variable and copying over
+       * the data elements, but this function is significantly more efficient
+       * since it only swaps the pointers to the data of the two vectors and
+       * therefore does not need to allocate temporary storage and move data
+       * around.
        *
-       * Limitation: right now this
-       * function only works if both
-       * vectors have the same number
-       * of blocks. If needed, the
-       * numbers of blocks should be
+       * Limitation: right now this function only works if both vectors have
+       * the same number of blocks. If needed, the numbers of blocks should be
        * exchanged, too.
        *
-       * This function is analog to the
-       * the swap() function of all C++
-       * standard containers. Also,
-       * there is a global function
-       * swap(u,v) that simply calls
-       * <tt>u.swap(v)</tt>, again in analogy
-       * to standard functions.
+       * This function is analog to the the swap() function of all C++
+       * standard containers. Also, there is a global function swap(u,v) that
+       * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
+       * functions.
        */
       void swap (BlockVector &v);
 
@@ -602,9 +520,9 @@ namespace PETScWrappers
 
 
     /**
-     * Global function which overloads the default implementation
-     * of the C++ standard library which uses a temporary object. The
-     * function simply exchanges the data of the two vectors.
+     * Global function which overloads the default implementation of the C++
+     * standard library which uses a temporary object. The function simply
+     * exchanges the data of the two vectors.
      *
      * @relates PETScWrappers::MPI::BlockVector
      * @author Wolfgang Bangerth, 2000
index 06dc1c64c97aeb2b99930e370d711242950df9a6..1b7df5c61c465c7470db1049a9ef8589834bfacd 100644 (file)
@@ -40,18 +40,19 @@ namespace PETScWrappers
 
 
     /**
-     * Implementation of a parallel sparse matrix class based on PETSC, with rows
-     * of the matrix distributed across an MPI network. All the functionality is
-     * actually in the base class, except for the calls to generate a parallel
-     * sparse matrix. This is possible since PETSc only works on an abstract
-     * matrix type and internally distributes to functions that do the actual work
-     * depending on the actual matrix type (much like using virtual
-     * functions). Only the functions creating a matrix of specific type differ,
-     * and are implemented in this particular class.
+     * Implementation of a parallel sparse matrix class based on PETSC, with
+     * rows of the matrix distributed across an MPI network. All the
+     * functionality is actually in the base class, except for the calls to
+     * generate a parallel sparse matrix. This is possible since PETSc only
+     * works on an abstract matrix type and internally distributes to
+     * functions that do the actual work depending on the actual matrix type
+     * (much like using virtual functions). Only the functions creating a
+     * matrix of specific type differ, and are implemented in this particular
+     * class.
      *
-     * There are a number of comments on the communication model as well as access
-     * to individual elements in the documentation to the parallel vector
-     * class. These comments apply here as well.
+     * There are a number of comments on the communication model as well as
+     * access to individual elements in the documentation to the parallel
+     * vector class. These comments apply here as well.
      *
      *
      * <h3>Partitioning of matrices</h3>
@@ -60,54 +61,56 @@ namespace PETScWrappers
      * certain number of rows (i.e. only this process stores the respective
      * entries in these rows). The number of rows each process owns has to be
      * passed to the constructors and reinit() functions via the argument @p
-     * local_rows. The individual values passed as @p local_rows on all the MPI
-     * processes of course have to add up to the global number of rows of the
-     * matrix.
+     * local_rows. The individual values passed as @p local_rows on all the
+     * MPI processes of course have to add up to the global number of rows of
+     * the matrix.
      *
      * In addition to this, PETSc also partitions the rectangular chunk of the
-     * matrix it owns (i.e. the @p local_rows times n() elements in the matrix),
-     * so that matrix vector multiplications can be performed efficiently. This
-     * column-partitioning therefore has to match the partitioning of the vectors
-     * with which the matrix is multiplied, just as the row-partitioning has to
-     * match the partitioning of destination vectors. This partitioning is passed
-     * to the constructors and reinit() functions through the @p local_columns
-     * variable, which again has to add up to the global number of columns in the
-     * matrix. The name @p local_columns may be named inappropriately since it
-     * does not reflect that only these columns are stored locally, but it
-     * reflects the fact that these are the columns for which the elements of
-     * incoming vectors are stored locally.
+     * matrix it owns (i.e. the @p local_rows times n() elements in the
+     * matrix), so that matrix vector multiplications can be performed
+     * efficiently. This column-partitioning therefore has to match the
+     * partitioning of the vectors with which the matrix is multiplied, just
+     * as the row-partitioning has to match the partitioning of destination
+     * vectors. This partitioning is passed to the constructors and reinit()
+     * functions through the @p local_columns variable, which again has to add
+     * up to the global number of columns in the matrix. The name @p
+     * local_columns may be named inappropriately since it does not reflect
+     * that only these columns are stored locally, but it reflects the fact
+     * that these are the columns for which the elements of incoming vectors
+     * are stored locally.
      *
-     * To make things even more complicated, PETSc needs a very good estimate of
-     * the number of elements to be stored in each row to be efficient. Otherwise
-     * it spends most of the time with allocating small chunks of memory, a
-     * process that can slow down programs to a crawl if it happens to often. As
-     * if a good estimate of the number of entries per row isn't even, it even
-     * needs to split this as follows: for each row it owns, it needs an estimate
-     * for the number of elements in this row that fall into the columns that are
-     * set apart for this process (see above), and the number of elements that are
-     * in the rest of the columns.
+     * To make things even more complicated, PETSc needs a very good estimate
+     * of the number of elements to be stored in each row to be efficient.
+     * Otherwise it spends most of the time with allocating small chunks of
+     * memory, a process that can slow down programs to a crawl if it happens
+     * to often. As if a good estimate of the number of entries per row isn't
+     * even, it even needs to split this as follows: for each row it owns, it
+     * needs an estimate for the number of elements in this row that fall into
+     * the columns that are set apart for this process (see above), and the
+     * number of elements that are in the rest of the columns.
      *
      * Since in general this information is not readily available, most of the
      * initializing functions of this class assume that all of the number of
      * elements you give as an argument to @p n_nonzero_per_row or by @p
-     * row_lengths fall into the columns "owned" by this process, and none into
-     * the other ones. This is a fair guess for most of the rows, since in a good
-     * domain partitioning, nodes only interact with nodes that are within the
-     * same subdomain. It does not hold for nodes on the interfaces of subdomain,
-     * however, and for the rows corresponding to these nodes, PETSc will have to
-     * allocate additional memory, a costly process.
+     * row_lengths fall into the columns "owned" by this process, and none
+     * into the other ones. This is a fair guess for most of the rows, since
+     * in a good domain partitioning, nodes only interact with nodes that are
+     * within the same subdomain. It does not hold for nodes on the interfaces
+     * of subdomain, however, and for the rows corresponding to these nodes,
+     * PETSc will have to allocate additional memory, a costly process.
      *
-     * The only way to avoid this is to tell PETSc where the actual entries of the
-     * matrix will be. For this, there are constructors and reinit() functions of
-     * this class that take a CompressedSparsityPattern object containing all this
-     * information. While in the general case it is sufficient if the constructors
-     * and reinit() functions know the number of local rows and columns, the
-     * functions getting a sparsity pattern also need to know the number of local
-     * rows (@p local_rows_per_process) and columns (@p local_columns_per_process)
-     * for all other processes, in order to compute which parts of the matrix are
-     * which. Thus, it is not sufficient to just count the number of degrees of
-     * freedom that belong to a particular process, but you have to have the
-     * numbers for all processes available at all processes.
+     * The only way to avoid this is to tell PETSc where the actual entries of
+     * the matrix will be. For this, there are constructors and reinit()
+     * functions of this class that take a CompressedSparsityPattern object
+     * containing all this information. While in the general case it is
+     * sufficient if the constructors and reinit() functions know the number
+     * of local rows and columns, the functions getting a sparsity pattern
+     * also need to know the number of local rows (@p local_rows_per_process)
+     * and columns (@p local_columns_per_process) for all other processes, in
+     * order to compute which parts of the matrix are which. Thus, it is not
+     * sufficient to just count the number of degrees of freedom that belong
+     * to a particular process, but you have to have the numbers for all
+     * processes available at all processes.
      *
      * @ingroup PETScWrappers
      * @ingroup Matrix1
@@ -122,38 +125,26 @@ namespace PETScWrappers
       typedef types::global_dof_index size_type;
 
       /**
-       * A structure that describes some of
-       * the traits of this class in terms
-       * of its run-time behavior. Some
-       * other classes (such as the block
-       * matrix classes) that take one or
-       * other of the matrix classes as its
-       * template parameters can tune their
-       * behavior based on the variables in
+       * A structure that describes some of the traits of this class in terms
+       * of its run-time behavior. Some other classes (such as the block
+       * matrix classes) that take one or other of the matrix classes as its
+       * template parameters can tune their behavior based on the variables in
        * this class.
        */
       struct Traits
       {
         /**
-         * It is not safe to elide
-         * additions of zeros to
-         * individual elements of this
-         * matrix. The reason is that
-         * additions to the matrix may
-         * trigger collective operations
-         * synchronising buffers on
-         * multiple processes. If an
-         * addition is elided on one
-         * process, this may lead to
-         * other processes hanging in an
-         * infinite waiting loop.
+         * It is not safe to elide additions of zeros to individual elements
+         * of this matrix. The reason is that additions to the matrix may
+         * trigger collective operations synchronising buffers on multiple
+         * processes. If an addition is elided on one process, this may lead
+         * to other processes hanging in an infinite waiting loop.
          */
         static const bool zero_addition_can_be_elided = false;
       };
 
       /**
-       * Default constructor. Create an
-       * empty matrix.
+       * Default constructor. Create an empty matrix.
        */
       SparseMatrix ();
 
@@ -163,38 +154,23 @@ namespace PETScWrappers
       ~SparseMatrix ();
 
       /**
-       * Create a sparse matrix of
-       * dimensions @p m times @p n, with
-       * an initial guess of @p
-       * n_nonzero_per_row and @p
-       * n_offdiag_nonzero_per_row nonzero
-       * elements per row (see documentation
-       * of the MatCreateAIJ PETSc function
-       * for more information about these
-       * parameters). PETSc is able to
-       * cope with the situation that more
-       * than this number of elements are
-       * later allocated for a row, but this
-       * involves copying data, and is thus
-       * expensive.
+       * Create a sparse matrix of dimensions @p m times @p n, with an initial
+       * guess of @p n_nonzero_per_row and @p n_offdiag_nonzero_per_row
+       * nonzero elements per row (see documentation of the MatCreateAIJ PETSc
+       * function for more information about these parameters). PETSc is able
+       * to cope with the situation that more than this number of elements are
+       * later allocated for a row, but this involves copying data, and is
+       * thus expensive.
        *
-       * For the meaning of the @p
-       * local_row and @p local_columns
-       * parameters, see the class
-       * documentation.
+       * For the meaning of the @p local_row and @p local_columns parameters,
+       * see the class documentation.
        *
-       * The @p is_symmetric flag determines
-       * whether we should tell PETSc that
-       * the matrix is going to be symmetric
-       * (as indicated by the call
-       * <tt>MatSetOption(mat,
-       * MAT_SYMMETRIC)</tt>. Note that the
-       * PETSc documentation states that one
-       * cannot form an ILU decomposition of
-       * a matrix for which this flag has
-       * been set to @p true, only an
-       * ICC. The default value of this flag
-       * is @p false.
+       * The @p is_symmetric flag determines whether we should tell PETSc that
+       * the matrix is going to be symmetric (as indicated by the call
+       * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+       * documentation states that one cannot form an ILU decomposition of a
+       * matrix for which this flag has been set to @p true, only an ICC. The
+       * default value of this flag is @p false.
        */
       SparseMatrix (const MPI_Comm  &communicator,
                     const size_type  m,
@@ -206,39 +182,24 @@ namespace PETScWrappers
                     const size_type  n_offdiag_nonzero_per_row = 0);
 
       /**
-       * Initialize a rectangular matrix
-       * with @p m rows and @p n columns.
-       * The maximal number of nonzero
-       * entries for diagonal and off-
-       * diagonal blocks of each row is
-       * given by the @p row_lengths and
-       * @p offdiag_row_lengths arrays.
+       * Initialize a rectangular matrix with @p m rows and @p n columns. The
+       * maximal number of nonzero entries for diagonal and off- diagonal
+       * blocks of each row is given by the @p row_lengths and @p
+       * offdiag_row_lengths arrays.
        *
-       * For the meaning of the @p
-       * local_row and @p local_columns
-       * parameters, see the class
-       * documentation.
+       * For the meaning of the @p local_row and @p local_columns parameters,
+       * see the class documentation.
        *
-       * Just as for the other
-       * constructors: PETSc is able to
-       * cope with the situation that more
-       * than this number of elements are
-       * later allocated for a row, but
-       * this involves copying data, and is
-       * thus expensive.
+       * Just as for the other constructors: PETSc is able to cope with the
+       * situation that more than this number of elements are later allocated
+       * for a row, but this involves copying data, and is thus expensive.
        *
-       * The @p is_symmetric flag
-       * determines whether we should tell
-       * PETSc that the matrix is going to
-       * be symmetric (as indicated by the
-       * call <tt>MatSetOption(mat,
-       * MAT_SYMMETRIC)</tt>. Note that the
-       * PETSc documentation states that
-       * one cannot form an ILU
-       * decomposition of a matrix for
-       * which this flag has been set to @p
-       * true, only an ICC. The default
-       * value of this flag is @p false.
+       * The @p is_symmetric flag determines whether we should tell PETSc that
+       * the matrix is going to be symmetric (as indicated by the call
+       * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+       * documentation states that one cannot form an ILU decomposition of a
+       * matrix for which this flag has been set to @p true, only an ICC. The
+       * default value of this flag is @p false.
        */
       SparseMatrix (const MPI_Comm               &communicator,
                     const size_type               m,
@@ -250,44 +211,26 @@ namespace PETScWrappers
                     const std::vector<size_type> &offdiag_row_lengths = std::vector<size_type>());
 
       /**
-       * Initialize using the given
-       * sparsity pattern with
-       * communication happening over the
-       * provided @p communicator.
+       * Initialize using the given sparsity pattern with communication
+       * happening over the provided @p communicator.
        *
-       * For the meaning of the @p
-       * local_rows_per_process and @p
-       * local_columns_per_process
-       * parameters, see the class
-       * documentation.
+       * For the meaning of the @p local_rows_per_process and @p
+       * local_columns_per_process parameters, see the class documentation.
        *
-       * Note that PETSc can be very slow
-       * if you do not provide it with a
-       * good estimate of the lengths of
-       * rows. Using the present function
-       * is a very efficient way to do
-       * this, as it uses the exact number
-       * of nonzero entries for each row of
-       * the matrix by using the given
-       * sparsity pattern argument. If the
-       * @p preset_nonzero_locations flag
-       * is @p true, this function in
-       * addition not only sets the correct
-       * row sizes up front, but also
-       * pre-allocated the correct nonzero
-       * entries in the matrix.
+       * Note that PETSc can be very slow if you do not provide it with a good
+       * estimate of the lengths of rows. Using the present function is a very
+       * efficient way to do this, as it uses the exact number of nonzero
+       * entries for each row of the matrix by using the given sparsity
+       * pattern argument. If the @p preset_nonzero_locations flag is @p true,
+       * this function in addition not only sets the correct row sizes up
+       * front, but also pre-allocated the correct nonzero entries in the
+       * matrix.
        *
-       * PETsc allows to later add
-       * additional nonzero entries to a
-       * matrix, by simply writing to these
-       * elements. However, this will then
-       * lead to additional memory
-       * allocations which are very
-       * inefficient and will greatly slow
-       * down your program. It is therefore
-       * significantly more efficient to
-       * get memory allocation right from
-       * the start.
+       * PETsc allows to later add additional nonzero entries to a matrix, by
+       * simply writing to these elements. However, this will then lead to
+       * additional memory allocations which are very inefficient and will
+       * greatly slow down your program. It is therefore significantly more
+       * efficient to get memory allocation right from the start.
        */
       template <typename SparsityType>
       SparseMatrix (const MPI_Comm               &communicator,
@@ -298,37 +241,27 @@ namespace PETScWrappers
                     const bool                    preset_nonzero_locations = true);
 
       /**
-       * This operator assigns a scalar to
-       * a matrix. Since this does usually
-       * not make much sense (should we set
-       * all matrix entries to this value?
-       * Only the nonzero entries of the
-       * sparsity pattern?), this operation
-       * is only allowed if the actual
-       * value to be assigned is zero. This
-       * operator only exists to allow for
-       * the obvious notation
-       * <tt>matrix=0</tt>, which sets all
-       * elements of the matrix to zero,
-       * but keep the sparsity pattern
-       * previously used.
+       * This operator assigns a scalar to a matrix. Since this does usually
+       * not make much sense (should we set all matrix entries to this value?
+       * Only the nonzero entries of the sparsity pattern?), this operation is
+       * only allowed if the actual value to be assigned is zero. This
+       * operator only exists to allow for the obvious notation
+       * <tt>matrix=0</tt>, which sets all elements of the matrix to zero, but
+       * keep the sparsity pattern previously used.
        */
       SparseMatrix &operator = (const value_type d);
 
 
       /**
-       * Make a copy of the PETSc matrix @p other. It is assumed that both matrices have
-       * the same SparsityPattern.
+       * Make a copy of the PETSc matrix @p other. It is assumed that both
+       * matrices have the same SparsityPattern.
        */
       void copy_from(const SparseMatrix &other);
 
       /**
-       * Throw away the present matrix and
-       * generate one that has the same
-       * properties as if it were created by
-       * the constructor of this class with
-       * the same argument list as the
-       * present function.
+       * Throw away the present matrix and generate one that has the same
+       * properties as if it were created by the constructor of this class
+       * with the same argument list as the present function.
        */
       void reinit (const MPI_Comm     &communicator,
                    const size_type m,
@@ -340,12 +273,9 @@ namespace PETScWrappers
                    const size_type n_offdiag_nonzero_per_row = 0);
 
       /**
-       * Throw away the present matrix and
-       * generate one that has the same
-       * properties as if it were created by
-       * the constructor of this class with
-       * the same argument list as the
-       * present function.
+       * Throw away the present matrix and generate one that has the same
+       * properties as if it were created by the constructor of this class
+       * with the same argument list as the present function.
        */
       void reinit (const MPI_Comm               &communicator,
                    const size_type               m,
@@ -357,38 +287,23 @@ namespace PETScWrappers
                    const std::vector<size_type> &offdiag_row_lengths = std::vector<size_type>());
 
       /**
-       * Initialize using the given
-       * sparsity pattern with
-       * communication happening over the
-       * provided @p communicator.
+       * Initialize using the given sparsity pattern with communication
+       * happening over the provided @p communicator.
        *
-       * Note that PETSc can be very slow
-       * if you do not provide it with a
-       * good estimate of the lengths of
-       * rows. Using the present function
-       * is a very efficient way to do
-       * this, as it uses the exact number
-       * of nonzero entries for each row of
-       * the matrix by using the given
-       * sparsity pattern argument. If the
-       * @p preset_nonzero_locations flag
-       * is @p true, this function in
-       * addition not only sets the correct
-       * row sizes up front, but also
-       * pre-allocated the correct nonzero
-       * entries in the matrix.
+       * Note that PETSc can be very slow if you do not provide it with a good
+       * estimate of the lengths of rows. Using the present function is a very
+       * efficient way to do this, as it uses the exact number of nonzero
+       * entries for each row of the matrix by using the given sparsity
+       * pattern argument. If the @p preset_nonzero_locations flag is @p true,
+       * this function in addition not only sets the correct row sizes up
+       * front, but also pre-allocated the correct nonzero entries in the
+       * matrix.
        *
-       * PETsc allows to later add
-       * additional nonzero entries to a
-       * matrix, by simply writing to these
-       * elements. However, this will then
-       * lead to additional memory
-       * allocations which are very
-       * inefficient and will greatly slow
-       * down your program. It is therefore
-       * significantly more efficient to
-       * get memory allocation right from
-       * the start.
+       * PETsc allows to later add additional nonzero entries to a matrix, by
+       * simply writing to these elements. However, this will then lead to
+       * additional memory allocations which are very inefficient and will
+       * greatly slow down your program. It is therefore significantly more
+       * efficient to get memory allocation right from the start.
        */
       template <typename SparsityType>
       void reinit (const MPI_Comm               &communicator,
@@ -399,10 +314,10 @@ namespace PETScWrappers
                    const bool                    preset_nonzero_locations = true);
 
       /**
-       * Create a matrix where the size() of the IndexSets determine the global
-       * number of rows and columns and the entries of the IndexSet give
-       * the rows and columns for the calling processor.
-       * Note that only contiguous IndexSets are supported.
+       * Create a matrix where the size() of the IndexSets determine the
+       * global number of rows and columns and the entries of the IndexSet
+       * give the rows and columns for the calling processor. Note that only
+       * contiguous IndexSets are supported.
        */
       template <typename SparsityType>
       void reinit (const IndexSet &local_rows,
@@ -411,14 +326,15 @@ namespace PETScWrappers
                    const MPI_Comm                  &communicator);
 
       /**
-       * Return a reference to the MPI
-       * communicator object in use with
-       * this matrix.
+       * Return a reference to the MPI communicator object in use with this
+       * matrix.
        */
       virtual const MPI_Comm &get_mpi_communicator () const;
 
-      /** @addtogroup Exceptions
-       * @{ */
+      /**
+       * @addtogroup Exceptions
+       * @{
+       */
       /**
        * Exception
        */
@@ -429,44 +345,29 @@ namespace PETScWrappers
       //@}
 
       /**
-       * Return the square of the norm
-       * of the vector $v$ with respect
-       * to the norm induced by this
-       * matrix,
-       * i.e. $\left(v,Mv\right)$. This
-       * is useful, e.g. in the finite
-       * element context, where the
-       * $L_2$ norm of a function
-       * equals the matrix norm with
-       * respect to the mass matrix of
-       * the vector representing the
-       * nodal values of the finite
-       * element function.
+       * Return the square of the norm of the vector $v$ with respect to the
+       * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is
+       * useful, e.g. in the finite element context, where the $L_2$ norm of a
+       * function equals the matrix norm with respect to the mass matrix of
+       * the vector representing the nodal values of the finite element
+       * function.
        *
-       * Obviously, the matrix needs to
-       * be quadratic for this operation.
+       * Obviously, the matrix needs to be quadratic for this operation.
        *
-       * The implementation of this function
-       * is not as efficient as the one in
-       * the @p MatrixBase class used in
-       * deal.II (i.e. the original one, not
-       * the PETSc wrapper class) since PETSc
-       * doesn't support this operation and
-       * needs a temporary vector.
+       * The implementation of this function is not as efficient as the one in
+       * the @p MatrixBase class used in deal.II (i.e. the original one, not
+       * the PETSc wrapper class) since PETSc doesn't support this operation
+       * and needs a temporary vector.
        */
       PetscScalar matrix_norm_square (const Vector &v) const;
 
       /**
-       * Compute the matrix scalar
-       * product $\left(u,Mv\right)$.
+       * Compute the matrix scalar product $\left(u,Mv\right)$.
        *
-       * The implementation of this function
-       * is not as efficient as the one in
-       * the @p MatrixBase class used in
-       * deal.II (i.e. the original one, not
-       * the PETSc wrapper class) since PETSc
-       * doesn't support this operation and
-       * needs a temporary vector.
+       * The implementation of this function is not as efficient as the one in
+       * the @p MatrixBase class used in deal.II (i.e. the original one, not
+       * the PETSc wrapper class) since PETSc doesn't support this operation
+       * and needs a temporary vector.
        */
       PetscScalar matrix_scalar_product (const Vector &u,
                                          const Vector &v) const;
@@ -474,18 +375,14 @@ namespace PETScWrappers
     private:
 
       /**
-       * Copy of the communicator object to
-       * be used for this parallel vector.
+       * Copy of the communicator object to be used for this parallel vector.
        */
       MPI_Comm communicator;
 
       /**
-       * Do the actual work for the
-       * respective reinit() function and
-       * the matching constructor,
-       * i.e. create a matrix. Getting rid
-       * of the previous matrix is left to
-       * the caller.
+       * Do the actual work for the respective reinit() function and the
+       * matching constructor, i.e. create a matrix. Getting rid of the
+       * previous matrix is left to the caller.
        */
       void do_reinit (const size_type m,
                       const size_type n,
@@ -525,9 +422,7 @@ namespace PETScWrappers
                       const SparsityType         &sparsity_pattern);
 
       /**
-       *  To allow calling protected
-       *  prepare_add() and
-       *  prepare_set().
+       * To allow calling protected prepare_add() and prepare_set().
        */
       friend class BlockMatrixBase<SparseMatrix>;
     };
index 98f37face1a732b467cf7111c3a6eaba59723848..3cb45e50effb6c803a7951df0850c001186766d1 100644 (file)
@@ -53,69 +53,71 @@ namespace PETScWrappers
 
     /**
      * Implementation of a parallel vector class based on PETSC and using MPI
-     * communication to synchronise distributed operations. All the functionality
-     * is actually in the base class, except for the calls to generate a
-     * parallel vector. This is possible since PETSc only works on an abstract
-     * vector type and internally distributes to functions that do the actual work
-     * depending on the actual vector type (much like using virtual
-     * functions). Only the functions creating a vector of specific type differ,
-     * and are implemented in this particular class.
+     * communication to synchronise distributed operations. All the
+     * functionality is actually in the base class, except for the calls to
+     * generate a parallel vector. This is possible since PETSc only works on
+     * an abstract vector type and internally distributes to functions that do
+     * the actual work depending on the actual vector type (much like using
+     * virtual functions). Only the functions creating a vector of specific
+     * type differ, and are implemented in this particular class.
      *
      *
      * <h3>Parallel communication model</h3>
      *
-     * The parallel functionality of PETSc is built on top of the Message Passing
-     * Interface (MPI). MPI's communication model is built on collective
-     * communications: if one process wants something from another, that other
-     * process has to be willing to accept this communication. A process cannot
-     * query data from another process by calling a remote function, without that
-     * other process expecting such a transaction. The consequence is that most of
-     * the operations in the base class of this class have to be called
-     * collectively. For example, if you want to compute the l2 norm of a parallel
-     * vector, @em all processes across which this vector is shared have to call
-     * the @p l2_norm function. If you don't do this, but instead only call the @p
-     * l2_norm function on one process, then the following happens: This one
-     * process will call one of the collective MPI functions and wait for all the
-     * other processes to join in on this. Since the other processes don't call
-     * this function, you will either get a time-out on the first process, or,
-     * worse, by the time the next a callto a PETSc function generates an MPI
-     * message on the other processes, you will get a cryptic message that only a
-     * subset of processes attempted a communication. These bugs can be very hard
-     * to figure out, unless you are well-acquainted with the communication model
+     * The parallel functionality of PETSc is built on top of the Message
+     * Passing Interface (MPI). MPI's communication model is built on
+     * collective communications: if one process wants something from another,
+     * that other process has to be willing to accept this communication. A
+     * process cannot query data from another process by calling a remote
+     * function, without that other process expecting such a transaction. The
+     * consequence is that most of the operations in the base class of this
+     * class have to be called collectively. For example, if you want to
+     * compute the l2 norm of a parallel vector, @em all processes across
+     * which this vector is shared have to call the @p l2_norm function. If
+     * you don't do this, but instead only call the @p l2_norm function on one
+     * process, then the following happens: This one process will call one of
+     * the collective MPI functions and wait for all the other processes to
+     * join in on this. Since the other processes don't call this function,
+     * you will either get a time-out on the first process, or, worse, by the
+     * time the next a callto a PETSc function generates an MPI message on the
+     * other processes, you will get a cryptic message that only a subset of
+     * processes attempted a communication. These bugs can be very hard to
+     * figure out, unless you are well-acquainted with the communication model
      * of MPI, and know which functions may generate MPI messages.
      *
-     * One particular case, where an MPI message may be generated unexpectedly is
-     * discussed below.
+     * One particular case, where an MPI message may be generated unexpectedly
+     * is discussed below.
      *
      *
      * <h3>Accessing individual elements of a vector</h3>
      *
-     * PETSc does allow read access to individual elements of a vector, but in the
-     * distributed case only to elements that are stored locally. We implement
-     * this through calls like <tt>d=vec(i)</tt>. However, if you access an
-     * element outside the locally stored range, an exception is generated.
+     * PETSc does allow read access to individual elements of a vector, but in
+     * the distributed case only to elements that are stored locally. We
+     * implement this through calls like <tt>d=vec(i)</tt>. However, if you
+     * access an element outside the locally stored range, an exception is
+     * generated.
      *
      * In contrast to read access, PETSc (and the respective deal.II wrapper
-     * classes) allow to write (or add) to individual elements of vectors, even if
-     * they are stored on a different process. You can do this writing, for
-     * example, <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or similar
-     * operations. There is one catch, however, that may lead to very confusing
-     * error messages: PETSc requires application programs to call the compress()
-     * function when they switch from adding, to elements to writing to
-     * elements. The reasoning is that all processes might accumulate addition
-     * operations to elements, even if multiple processes write to the same
-     * elements. By the time we call compress() the next time, all these additions
-     * are executed. However, if one process adds to an element, and another
-     * overwrites to it, the order of execution would yield non-deterministic
-     * behavior if we don't make sure that a synchronisation with compress()
-     * happens in between.
+     * classes) allow to write (or add) to individual elements of vectors,
+     * even if they are stored on a different process. You can do this
+     * writing, for example, <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or
+     * similar operations. There is one catch, however, that may lead to very
+     * confusing error messages: PETSc requires application programs to call
+     * the compress() function when they switch from adding, to elements to
+     * writing to elements. The reasoning is that all processes might
+     * accumulate addition operations to elements, even if multiple processes
+     * write to the same elements. By the time we call compress() the next
+     * time, all these additions are executed. However, if one process adds to
+     * an element, and another overwrites to it, the order of execution would
+     * yield non-deterministic behavior if we don't make sure that a
+     * synchronisation with compress() happens in between.
      *
-     * In order to make sure these calls to compress() happen at the appropriate
-     * time, the deal.II wrappers keep a state variable that store which is the
-     * presently allowed operation: additions or writes. If it encounters an
-     * operation of the opposite kind, it calls compress() and flips the
-     * state. This can sometimes lead to very confusing behavior, in code that may
-     * for example look like this:
+     * In order to make sure these calls to compress() happen at the
+     * appropriate time, the deal.II wrappers keep a state variable that store
+     * which is the presently allowed operation: additions or writes. If it
+     * encounters an operation of the opposite kind, it calls compress() and
+     * flips the state. This can sometimes lead to very confusing behavior, in
+     * code that may for example look like this:
      * @code
      *   PETScWrappers::MPI::Vector vector;
      *   ...
@@ -134,20 +136,20 @@ namespace PETScWrappers
      * @endcode
      *
      * This code can run into trouble: by the time we see the first addition
-     * operation, we need to flush the overwrite buffers for the vector, and the
-     * deal.II library will do so by calling compress(). However, it will only do
-     * so for all processes that actually do an addition -- if the condition is
-     * never true for one of the processes, then this one will not get to the
-     * actual compress() call, whereas all the other ones do. This gets us into
-     * trouble, since all the other processes hang in the call to flush the write
-     * buffers, while the one other process advances to the call to compute the l2
-     * norm. At this time, you will get an error that some operation was attempted
-     * by only a subset of processes. This behavior may seem surprising, unless
-     * you know that write/addition operations on single elements may trigger this
-     * behavior.
+     * operation, we need to flush the overwrite buffers for the vector, and
+     * the deal.II library will do so by calling compress(). However, it will
+     * only do so for all processes that actually do an addition -- if the
+     * condition is never true for one of the processes, then this one will
+     * not get to the actual compress() call, whereas all the other ones do.
+     * This gets us into trouble, since all the other processes hang in the
+     * call to flush the write buffers, while the one other process advances
+     * to the call to compute the l2 norm. At this time, you will get an error
+     * that some operation was attempted by only a subset of processes. This
+     * behavior may seem surprising, unless you know that write/addition
+     * operations on single elements may trigger this behavior.
      *
-     * The problem described here may be avoided by placing additional calls to
-     * compress(), or making sure that all processes do the same type of
+     * The problem described here may be avoided by placing additional calls
+     * to compress(), or making sure that all processes do the same type of
      * operations at the same time, for example by placing zero additions if
      * necessary.
      *
@@ -166,47 +168,37 @@ namespace PETScWrappers
       typedef types::global_dof_index size_type;
 
       /**
-       * A variable that indicates whether this vector
-       * supports distributed data storage. If true, then
-       * this vector also needs an appropriate compress()
-       * function that allows communicating recent set or
-       * add operations to individual elements to be communicated
-       * to other processors.
+       * A variable that indicates whether this vector supports distributed
+       * data storage. If true, then this vector also needs an appropriate
+       * compress() function that allows communicating recent set or add
+       * operations to individual elements to be communicated to other
+       * processors.
        *
-       * For the current class, the variable equals
-       * true, since it does support parallel data storage.
+       * For the current class, the variable equals true, since it does
+       * support parallel data storage.
        */
       static const bool supports_distributed_data = true;
 
       /**
-      * Default constructor. Initialize the
-      * vector as empty.
-      */
+       * Default constructor. Initialize the vector as empty.
+       */
       Vector ();
 
       /**
-       * Constructor. Set dimension to
-       * @p n and initialize all
-       * elements with zero.
+       * Constructor. Set dimension to @p n and initialize all elements with
+       * zero.
        *
-       * @arg local_size denotes the size
-       * of the chunk that shall be stored
-       * on the present process.
+       * @arg local_size denotes the size of the chunk that shall be stored on
+       * the present process.
        *
-       * @arg communicator denotes the MPI
-       * communicator over which the
-       * different parts of the vector
-       * shall communicate
+       * @arg communicator denotes the MPI communicator over which the
+       * different parts of the vector shall communicate
        *
-       * The constructor is made explicit
-       * to avoid accidents like this:
-       * <tt>v=0;</tt>. Presumably, the user
-       * wants to set every element of the
-       * vector to zero, but instead, what
-       * happens is this call:
-       * <tt>v=Vector@<number@>(0);</tt>, i.e. the
-       * vector is replaced by one of
-       * length zero.
+       * The constructor is made explicit to avoid accidents like this:
+       * <tt>v=0;</tt>. Presumably, the user wants to set every element of the
+       * vector to zero, but instead, what happens is this call:
+       * <tt>v=Vector@<number@>(0);</tt>, i.e. the vector is replaced by one
+       * of length zero.
        */
       explicit Vector (const MPI_Comm  &communicator,
                        const size_type  n,
@@ -214,19 +206,14 @@ namespace PETScWrappers
 
 
       /**
-       * Copy-constructor from deal.II
-       * vectors. Sets the dimension to that
-       * of the given vector, and copies all
-       * elements.
+       * Copy-constructor from deal.II vectors. Sets the dimension to that of
+       * the given vector, and copies all elements.
        *
-       * @arg local_size denotes the size
-       * of the chunk that shall be stored
-       * on the present process.
+       * @arg local_size denotes the size of the chunk that shall be stored on
+       * the present process.
        *
-       * @arg communicator denotes the MPI
-       * communicator over which the
-       * different parts of the vector
-       * shall communicate
+       * @arg communicator denotes the MPI communicator over which the
+       * different parts of the vector shall communicate
        */
       template <typename Number>
       explicit Vector (const MPI_Comm               &communicator,
@@ -235,18 +222,13 @@ namespace PETScWrappers
 
 
       /**
-       * Copy-constructor the
-       * values from a PETSc wrapper vector
-       * class.
+       * Copy-constructor the values from a PETSc wrapper vector class.
        *
-       * @arg local_size denotes the size
-       * of the chunk that shall be stored
-       * on the present process.
+       * @arg local_size denotes the size of the chunk that shall be stored on
+       * the present process.
        *
-       * @arg communicator denotes the MPI
-       * communicator over which the
-       * different parts of the vector
-       * shall communicate
+       * @arg communicator denotes the MPI communicator over which the
+       * different parts of the vector shall communicate
        */
       explicit Vector (const MPI_Comm     &communicator,
                        const VectorBase   &v,
@@ -254,27 +236,20 @@ namespace PETScWrappers
 
 
       /**
-       * Constructs a new parallel ghosted PETSc
-       * vector from an Indexset. Note that
-       * @p local must be contiguous and
-       * the global size of the vector is
-       * determined by local.size(). The
-       * global indices in @p ghost are
-       * supplied as ghost indices that can
-       * also be read locally.
+       * Constructs a new parallel ghosted PETSc vector from an Indexset. Note
+       * that @p local must be contiguous and the global size of the vector is
+       * determined by local.size(). The global indices in @p ghost are
+       * supplied as ghost indices that can also be read locally.
        *
-       * Note that the @p ghost IndexSet
-       * may be empty and that any indices
-       * already contained in @p local are
-       * ignored during construction. That
-       * way, the ghost parameter can equal
-       * the set of locally relevant
+       * Note that the @p ghost IndexSet may be empty and that any indices
+       * already contained in @p local are ignored during construction. That
+       * way, the ghost parameter can equal the set of locally relevant
        * degrees of freedom, see step-32.
        *
-       * @deprecated Use Vector::Vector(const IndexSet &,const IndexSet &,const MPI_Comm &) instead.
+       * @deprecated Use Vector::Vector(const IndexSet &,const IndexSet
+       * &,const MPI_Comm &) instead.
        *
-       * @note This operation always creates a ghosted
-       * vector.
+       * @note This operation always creates a ghosted vector.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -283,25 +258,17 @@ namespace PETScWrappers
                        const IndexSet &ghost) DEAL_II_DEPRECATED;
 
       /**
-       * Constructs a new parallel ghosted PETSc
-       * vector from an Indexset. Note that
-       * @p local must be contiguous and
-       * the global size of the vector is
-       * determined by local.size(). The
-       * global indices in @p ghost are
-       * supplied as ghost indices that can
-       * also be read locally.
+       * Constructs a new parallel ghosted PETSc vector from an Indexset. Note
+       * that @p local must be contiguous and the global size of the vector is
+       * determined by local.size(). The global indices in @p ghost are
+       * supplied as ghost indices that can also be read locally.
        *
-       * Note that the @p ghost IndexSet
-       * may be empty and that any indices
-       * already contained in @p local are
-       * ignored during construction. That
-       * way, the ghost parameter can equal
-       * the set of locally relevant
+       * Note that the @p ghost IndexSet may be empty and that any indices
+       * already contained in @p local are ignored during construction. That
+       * way, the ghost parameter can equal the set of locally relevant
        * degrees of freedom, see step-32.
        *
-       * @note This operation always creates a ghosted
-       * vector.
+       * @note This operation always creates a ghosted vector.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -310,123 +277,81 @@ namespace PETScWrappers
               const MPI_Comm &communicator);
 
       /**
-       * Constructs a new parallel PETSc
-       * vector from an IndexSet. This creates a non
-       * ghosted vector.
+       * Constructs a new parallel PETSc vector from an IndexSet. This creates
+       * a non ghosted vector.
        *
-       * @deprecated Use Vector::Vector(const IndexSet &,const MPI_Comm &) instead.
+       * @deprecated Use Vector::Vector(const IndexSet &,const MPI_Comm &)
+       * instead.
        */
       explicit Vector (const MPI_Comm &communicator,
                        const IndexSet &local) DEAL_II_DEPRECATED;
 
       /**
-       * Constructs a new parallel PETSc
-       * vector from an IndexSet. This creates a non
-       * ghosted vector.
+       * Constructs a new parallel PETSc vector from an IndexSet. This creates
+       * a non ghosted vector.
        */
       explicit Vector (const IndexSet &local,
                        const MPI_Comm &communicator);
 
       /**
-       * Copy the given vector. Resize the
-       * present vector if necessary. Also
-       * take over the MPI communicator of
-       * @p v.
+       * Copy the given vector. Resize the present vector if necessary. Also
+       * take over the MPI communicator of @p v.
        */
       Vector &operator = (const Vector &v);
 
 
       /**
-       * Copy the given sequential
-       * (non-distributed) vector
-       * into the present parallel
-       * vector. It is assumed that
-       * they have the same size,
-       * and this operation does
-       * not change the
-       * partitioning of the
-       * parallel vector by which
-       * its elements are
-       * distributed across several
-       * MPI processes. What this
-       * operation therefore does
-       * is to copy that chunk of
-       * the given vector @p v that
-       * corresponds to elements of
-       * the target vector that are
-       * stored locally, and copies
-       * them. Elements that are
-       * not stored locally are not
-       * touched.
+       * Copy the given sequential (non-distributed) vector into the present
+       * parallel vector. It is assumed that they have the same size, and this
+       * operation does not change the partitioning of the parallel vector by
+       * which its elements are distributed across several MPI processes. What
+       * this operation therefore does is to copy that chunk of the given
+       * vector @p v that corresponds to elements of the target vector that
+       * are stored locally, and copies them. Elements that are not stored
+       * locally are not touched.
        *
-       * This being a parallel
-       * vector, you must make sure
-       * that @em all processes
-       * call this function at the
-       * same time. It is not
-       * possible to change the
-       * local part of a parallel
-       * vector on only one
-       * process, independent of
-       * what other processes do,
-       * with this function.
+       * This being a parallel vector, you must make sure that @em all
+       * processes call this function at the same time. It is not possible to
+       * change the local part of a parallel vector on only one process,
+       * independent of what other processes do, with this function.
        */
       Vector &operator = (const PETScWrappers::Vector &v);
 
       /**
-       * Set all components of the vector to
-       * the given number @p s. Simply pass
-       * this down to the base class, but we
-       * still need to declare this function
-       * to make the example given in the
-       * discussion about making the
+       * Set all components of the vector to the given number @p s. Simply
+       * pass this down to the base class, but we still need to declare this
+       * function to make the example given in the discussion about making the
        * constructor explicit work.
        */
       Vector &operator = (const PetscScalar s);
 
       /**
-       * Copy the values of a deal.II vector
-       * (as opposed to those of the PETSc
-       * vector wrapper class) into this
-       * object.
+       * Copy the values of a deal.II vector (as opposed to those of the PETSc
+       * vector wrapper class) into this object.
        *
-       * Contrary to the case of sequential
-       * vectors, this operators requires
-       * that the present vector already
-       * has the correct size, since we
-       * need to have a partition and a
-       * communicator present which we
-       * otherwise can't get from the
-       * source vector.
+       * Contrary to the case of sequential vectors, this operators requires
+       * that the present vector already has the correct size, since we need
+       * to have a partition and a communicator present which we otherwise
+       * can't get from the source vector.
        */
       template <typename number>
       Vector &operator = (const dealii::Vector<number> &v);
 
       /**
-       * Change the dimension of the vector
-       * to @p N. It is unspecified how
-       * resizing the vector affects the
-       * memory allocation of this object;
-       * i.e., it is not guaranteed that
-       * resizing it to a smaller size
-       * actually also reduces memory
-       * consumption, or if for efficiency
-       * the same amount of memory is used
+       * Change the dimension of the vector to @p N. It is unspecified how
+       * resizing the vector affects the memory allocation of this object;
+       * i.e., it is not guaranteed that resizing it to a smaller size
+       * actually also reduces memory consumption, or if for efficiency the
+       * same amount of memory is used
        *
-       * @p local_size denotes how many
-       * of the @p N values shall be
-       * stored locally on the present
-       * process.
-       * for less data.
+       * @p local_size denotes how many of the @p N values shall be stored
+       * locally on the present process. for less data.
        *
-       * @p communicator denotes the MPI
-       * communicator henceforth to be used
+       * @p communicator denotes the MPI communicator henceforth to be used
        * for this vector.
        *
-       * If @p fast is false, the vector
-       * is filled by zeros. Otherwise, the
-       * elements are left an unspecified
-       * state.
+       * If @p fast is false, the vector is filled by zeros. Otherwise, the
+       * elements are left an unspecified state.
        */
       void reinit (const MPI_Comm  &communicator,
                    const size_type  N,
@@ -434,28 +359,22 @@ namespace PETScWrappers
                    const bool       fast = false);
 
       /**
-       * Change the dimension to that of
-       * the vector @p v, and also take
-       * over the partitioning into local
-       * sizes as well as the MPI
-       * communicator. The same applies as
-       * for the other @p reinit function.
+       * Change the dimension to that of the vector @p v, and also take over
+       * the partitioning into local sizes as well as the MPI communicator.
+       * The same applies as for the other @p reinit function.
        *
-       * The elements of @p v are not
-       * copied, i.e. this function is the
-       * same as calling
-       * <tt>reinit(v.size(),
-       * v.local_size(), fast)</tt>.
+       * The elements of @p v are not copied, i.e. this function is the same
+       * as calling <tt>reinit(v.size(), v.local_size(), fast)</tt>.
        */
       void reinit (const Vector &v,
                    const bool    fast = false);
 
       /**
-       * Reinit as a ghosted vector. See
-       * constructor with same signature
-       * for more details.
+       * Reinit as a ghosted vector. See constructor with same signature for
+       * more details.
        *
-       * @deprecated Use Vector::reinit(const IndexSet &, const IndexSet &, const MPI_Comm &) instead.
+       * @deprecated Use Vector::reinit(const IndexSet &, const IndexSet &,
+       * const MPI_Comm &) instead.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -463,9 +382,8 @@ namespace PETScWrappers
                    const IndexSet   &local,
                    const IndexSet &ghost) DEAL_II_DEPRECATED;
       /**
-       * Reinit as a vector without ghost elements. See
-       * the constructor with same signature
-       * for more details.
+       * Reinit as a vector without ghost elements. See the constructor with
+       * same signature for more details.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -474,19 +392,18 @@ namespace PETScWrappers
                    const MPI_Comm &communicator);
 
       /**
-       * Reinit as a vector without ghost elements. See
-       * constructor with same signature
-       * for more details.
+       * Reinit as a vector without ghost elements. See constructor with same
+       * signature for more details.
        *
-       * @deprecated Use Vector::reinit(const IndexSet &, const MPI_Comm &) instead.
+       * @deprecated Use Vector::reinit(const IndexSet &, const MPI_Comm &)
+       * instead.
        */
       void reinit (const MPI_Comm     &communicator,
                    const IndexSet   &local) DEAL_II_DEPRECATED;
 
       /**
-       * Reinit as a vector without ghost elements. See
-       * constructor with same signature
-       * for more details.
+       * Reinit as a vector without ghost elements. See constructor with same
+       * signature for more details.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -494,30 +411,21 @@ namespace PETScWrappers
                    const MPI_Comm &communicator);
 
       /**
-       * Return a reference to the MPI
-       * communicator object in use with
-       * this vector.
+       * Return a reference to the MPI communicator object in use with this
+       * vector.
        */
       const MPI_Comm &get_mpi_communicator () const;
 
       /**
-       * Print to a
-       * stream. @p precision denotes
-       * the desired precision with
-       * which values shall be printed,
-       * @p scientific whether
-       * scientific notation shall be
-       * used. If @p across is
-       * @p true then the vector is
-       * printed in a line, while if
-       * @p false then the elements
-       * are printed on a separate line
-       * each.
+       * Print to a stream. @p precision denotes the desired precision with
+       * which values shall be printed, @p scientific whether scientific
+       * notation shall be used. If @p across is @p true then the vector is
+       * printed in a line, while if @p false then the elements are printed on
+       * a separate line each.
        *
-       * @note This function overloads the one in the
-       * base class to ensure that the right thing happens
-       * for parallel vectors that are distributed across
-       * processors.
+       * @note This function overloads the one in the base class to ensure
+       * that the right thing happens for parallel vectors that are
+       * distributed across processors.
        */
       void print (std::ostream       &out,
                   const unsigned int  precision  = 3,
@@ -527,20 +435,17 @@ namespace PETScWrappers
       /**
        * @copydoc PETScWrappers::VectorBase::all_zero()
        *
-       * @note This function overloads the one in the base class
-       * to make this a collective operation.
+       * @note This function overloads the one in the base class to make this
+       * a collective operation.
        */
       bool all_zero () const;
 
     protected:
       /**
-       * Create a vector of length
-       * @p n. For this class, we create a
-       * parallel vector. @p n denotes
-       * the total size of the vector to be
-       * created. @p local_size denotes
-       * how many of these elements shall
-       * be stored locally.
+       * Create a vector of length @p n. For this class, we create a parallel
+       * vector. @p n denotes the total size of the vector to be created. @p
+       * local_size denotes how many of these elements shall be stored
+       * locally.
        */
       virtual void create_vector (const size_type n,
                                   const size_type local_size);
@@ -548,12 +453,9 @@ namespace PETScWrappers
 
 
       /**
-       * Create a vector of global length
-       * @p n, local size @p local_size and
-       * with the specified ghost
-       * indices. Note that you need to
-       * call update_ghost_values() before
-       * accessing those.
+       * Create a vector of global length @p n, local size @p local_size and
+       * with the specified ghost indices. Note that you need to call
+       * update_ghost_values() before accessing those.
        */
       virtual void create_vector (const size_type n,
                                   const size_type local_size,
@@ -562,8 +464,7 @@ namespace PETScWrappers
 
     private:
       /**
-       * Copy of the communicator object to
-       * be used for this parallel vector.
+       * Copy of the communicator object to be used for this parallel vector.
        */
       MPI_Comm communicator;
     };
@@ -573,9 +474,9 @@ namespace PETScWrappers
 
 
     /**
-     * Global function @p swap which overloads the default implementation
-     * of the C++ standard library which uses a temporary object. The
-     * function simply exchanges the data of the two vectors.
+     * Global function @p swap which overloads the default implementation of
+     * the C++ standard library which uses a temporary object. The function
+     * simply exchanges the data of the two vectors.
      *
      * @relates PETScWrappers::MPI::Vector
      * @author Wolfgang Bangerth, 2004
index abbe1d2c38fd40ed32929ae9b4f1a2ebbcf9847c..0def3db8b18e7c8a6bbccd6bf60eb0c21384d128 100644 (file)
@@ -46,8 +46,8 @@ namespace PETScWrappers
    *
    * Note that derived classes only provide interfaces to the relevant
    * functionality of PETSc. PETSc does not implement all preconditioners for
-   * all matrix types. In particular, some preconditioners are not going to work
-   * for parallel jobs, such as for example the ILU preconditioner.
+   * all matrix types. In particular, some preconditioners are not going to
+   * work for parallel jobs, such as for example the ILU preconditioner.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, Timo Heister, 2004, 2011
@@ -66,16 +66,14 @@ namespace PETScWrappers
     virtual ~PreconditionerBase ();
 
     /**
-     * Apply the preconditioner once to the
-     * given src vector.
+     * Apply the preconditioner once to the given src vector.
      */
     void vmult (VectorBase       &dst,
                 const VectorBase &src) const;
 
 
     /**
-     * Gives access to the underlying PETSc
-     * object.
+     * Gives access to the underlying PETSc object.
      */
     const PC &get_pc () const;
 
@@ -86,32 +84,26 @@ namespace PETScWrappers
     PC pc;
 
     /**
-     * A pointer to the matrix that acts as
-     * a preconditioner.
+     * A pointer to the matrix that acts as a preconditioner.
      */
     Mat matrix;
 
     /**
-     * Internal function to create the
-     * PETSc preconditioner object. Fails
-     * if called twice.
+     * Internal function to create the PETSc preconditioner object. Fails if
+     * called twice.
      */
     void create_pc ();
 
     /**
-     * Conversion operator to get a
-     * representation of the matrix that
-     * represents this preconditioner. We
-     * use this inside the actual solver,
-     * where we need to pass this matrix to
-     * the PETSc solvers.
+     * Conversion operator to get a representation of the matrix that
+     * represents this preconditioner. We use this inside the actual solver,
+     * where we need to pass this matrix to the PETSc solvers.
      */
     operator Mat () const;
 
     /**
-     * Make the solver class a friend,
-     * since it needs to call the
-     * conversion operator.
+     * Make the solver class a friend, since it needs to call the conversion
+     * operator.
      */
     friend class SolverBase;
   };
@@ -132,48 +124,38 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {};
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionJacobi ();
 
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionJacobi (const MatrixBase     &matrix,
                         const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -183,13 +165,13 @@ namespace PETScWrappers
   /**
    * A class that implements the interface to use the PETSc Block Jacobi
    * preconditioner. The blocking structure of the matrix is determined by the
-   * association of degrees of freedom to the individual processors in an
-   * MPI-parallel job. If you use this preconditioner on a sequential job (or an
+   * association of degrees of freedom to the individual processors in an MPI-
+   * parallel job. If you use this preconditioner on a sequential job (or an
    * MPI job with only one process) then the entire matrix is the only block.
    *
    * By default, PETSc uses an ILU(0) decomposition of each diagonal block of
-   * the matrix for preconditioning. This can be changed, as is explained in the
-   * relevant section of the PETSc manual, but is not implemented here.
+   * the matrix for preconditioning. This can be changed, as is explained in
+   * the relevant section of the PETSc manual, but is not implemented here.
    *
    * See the comment in the base class @ref PreconditionerBase for when this
    * preconditioner may or may not work.
@@ -201,47 +183,37 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {};
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionBlockJacobi ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionBlockJacobi (const MatrixBase     &matrix,
                              const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -262,16 +234,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the damping parameter
-       * to one.
+       * Constructor. By default, set the damping parameter to one.
        */
       AdditionalData (const double omega = 1);
 
@@ -282,39 +251,30 @@ namespace PETScWrappers
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionSOR ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionSOR (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -335,16 +295,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the damping parameter
-       * to one.
+       * Constructor. By default, set the damping parameter to one.
        */
       AdditionalData (const double omega = 1);
 
@@ -355,39 +312,30 @@ namespace PETScWrappers
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionSSOR ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionSSOR (const MatrixBase     &matrix,
                       const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -408,16 +356,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the damping parameter
-       * to one.
+       * Constructor. By default, set the damping parameter to one.
        */
       AdditionalData (const double omega = 1);
 
@@ -428,39 +373,30 @@ namespace PETScWrappers
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionEisenstat ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionEisenstat (const MatrixBase     &matrix,
                            const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -468,8 +404,8 @@ namespace PETScWrappers
 
 
   /**
-   * A class that implements the interface to use the PETSc Incomplete Cholesky
-   * preconditioner.
+   * A class that implements the interface to use the PETSc Incomplete
+   * Cholesky preconditioner.
    *
    * See the comment in the base class @ref PreconditionerBase for when this
    * preconditioner may or may not work.
@@ -481,16 +417,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the fill-in parameter
-       * to zero.
+       * Constructor. By default, set the fill-in parameter to zero.
        */
       AdditionalData (const unsigned int levels = 0);
 
@@ -501,39 +434,30 @@ namespace PETScWrappers
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionICC ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionICC (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -554,16 +478,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the fill-in parameter
-       * to zero.
+       * Constructor. By default, set the fill-in parameter to zero.
        */
       AdditionalData (const unsigned int levels = 0);
 
@@ -574,39 +495,30 @@ namespace PETScWrappers
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionILU ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionILU (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -614,10 +526,9 @@ namespace PETScWrappers
 
 
   /**
-   * A class that implements the interface to use the PETSc LU
-   * preconditioner. The LU decomposition is only implemented for single
-   * processor machines. It should provide a convenient interface to
-   * another direct solver.
+   * A class that implements the interface to use the PETSc LU preconditioner.
+   * The LU decomposition is only implemented for single processor machines.
+   * It should provide a convenient interface to another direct solver.
    *
    * See the comment in the base class @ref PreconditionerBase for when this
    * preconditioner may or may not work.
@@ -629,81 +540,64 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. (Default values
-       * taken from function PCCreate_LU
-       * of the PetSC lib.)
+       * Constructor. (Default values taken from function PCCreate_LU of the
+       * PetSC lib.)
        */
       AdditionalData (const double pivoting = 1.e-6,
                       const double zero_pivot = 1.e-12,
                       const double damping = 0.0);
 
       /**
-       * Determines, when Pivoting is
-       * done during LU decomposition.
-       * 0.0 indicates no pivoting,
-       * and 1.0 complete pivoting.
-       * Confer PetSC manual for more
-       * details.
+       * Determines, when Pivoting is done during LU decomposition. 0.0
+       * indicates no pivoting, and 1.0 complete pivoting. Confer PetSC manual
+       * for more details.
        */
       double pivoting;
 
       /**
-       * Size at which smaller pivots
-       * are declared to be zero.
-       * Confer PetSC manual for more
-       * details.
+       * Size at which smaller pivots are declared to be zero. Confer PetSC
+       * manual for more details.
        */
       double zero_pivot;
 
       /**
-       * This quantity is added to the
-       * diagonal of the matrix during
+       * This quantity is added to the diagonal of the matrix during
        * factorisation.
        */
       double damping;
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionLU ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionLU (const MatrixBase     &matrix,
                     const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -726,15 +620,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. Note that BoomerAMG
-       * offers a lot more options to set
+       * Constructor. Note that BoomerAMG offers a lot more options to set
        * than what is exposed here.
        */
       AdditionalData (
@@ -746,102 +638,72 @@ namespace PETScWrappers
       );
 
       /**
-       * Set this flag to true if you
-       * have a symmetric system matrix
-       * and you want to use a solver
-       * which asumes a symmetric
-       * preconditioner like CG. The
-       * relaxation is done with
-       * SSOR/Jacobi when set to true and
-       * with SOR/Jacobi otherwise.
+       * Set this flag to true if you have a symmetric system matrix and you
+       * want to use a solver which asumes a symmetric preconditioner like CG.
+       * The relaxation is done with SSOR/Jacobi when set to true and with
+       * SOR/Jacobi otherwise.
        */
       bool symmetric_operator;
 
       /**
-       * Threshold of when nodes are
-       * considered strongly
-       * connected. See
-       * HYPRE_BoomerAMGSetStrongThreshold(). Recommended
-       * values are 0.25 for 2d and 0.5
-       * for 3d problems, but it is
-       * problem dependent.
+       * Threshold of when nodes are considered strongly connected. See
+       * HYPRE_BoomerAMGSetStrongThreshold(). Recommended values are 0.25 for
+       * 2d and 0.5 for 3d problems, but it is problem dependent.
        */
       double strong_threshold;
 
       /**
-       * If set to a value smaller than
-       * 1.0 then diagonally dominant
-       * parts of the matrix are treated
-       * as having no strongly connected
-       * nodes. If the row sum weighted
-       * by the diagonal entry is bigger
-       * than the given value, it is
-       * considered diagonally
-       * dominant. This feature is turned
-       * of by setting the value to
-       * 1.0. This is the default as some
-       * matrices can result in having
-       * only diagonally dominant entries
-       * and thus no multigrid levels are
-       * constructed. The default in
-       * BoomerAMG for this is 0.9. When
-       * you try this, check for a
-       * reasonable number of levels
+       * If set to a value smaller than 1.0 then diagonally dominant parts of
+       * the matrix are treated as having no strongly connected nodes. If the
+       * row sum weighted by the diagonal entry is bigger than the given
+       * value, it is considered diagonally dominant. This feature is turned
+       * of by setting the value to 1.0. This is the default as some matrices
+       * can result in having only diagonally dominant entries and thus no
+       * multigrid levels are constructed. The default in BoomerAMG for this
+       * is 0.9. When you try this, check for a reasonable number of levels
        * created.
        */
       double max_row_sum;
 
       /**
-      * Number of levels of aggressive
-      * coarsening. Increasing this
-      * value reduces the construction
-      * time and memory requirements but
-      * may decrease effectiveness.*/
+       * Number of levels of aggressive coarsening. Increasing this value
+       * reduces the construction time and memory requirements but may
+       * decrease effectiveness.
+       */
       unsigned int aggressive_coarsening_num_levels;
 
       /**
-       * Setting this flag to true
-       * produces debug output from
-       * HYPRE, when the preconditioner
-       * is constructed.
+       * Setting this flag to true produces debug output from HYPRE, when the
+       * preconditioner is constructed.
        */
       bool output_details;
     };
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionBoomerAMG ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionBoomerAMG (const MatrixBase     &matrix,
                            const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -850,19 +712,18 @@ namespace PETScWrappers
 
   /**
    * A class that implements the interface to use the ParaSails sparse
-   * approximate inverse preconditioner from the HYPRE suite. Note that
-   * PETSc has to be configured with HYPRE (e.g. with --download-hypre=1).
+   * approximate inverse preconditioner from the HYPRE suite. Note that PETSc
+   * has to be configured with HYPRE (e.g. with --download-hypre=1).
    *
-   * ParaSails uses least-squares minimization to compute a sparse
-   * approximate inverse. The sparsity pattern used is the pattern
-   * of a power of a sparsified matrix. ParaSails also uses a post-filtering
-   * technique to reduce the cost of applying the preconditioner.
+   * ParaSails uses least-squares minimization to compute a sparse approximate
+   * inverse. The sparsity pattern used is the pattern of a power of a
+   * sparsified matrix. ParaSails also uses a post-filtering technique to
+   * reduce the cost of applying the preconditioner.
    *
-   * ParaSails solves symmetric positive definite (SPD) problems
-   * using a factorized SPD preconditioner and can also solve
-   * general (nonsymmetric and/or indefinite) problems with a
-   * nonfactorized preconditioner. The problem type has to be
-   * set in @p AdditionalData.
+   * ParaSails solves symmetric positive definite (SPD) problems using a
+   * factorized SPD preconditioner and can also solve general (nonsymmetric
+   * and/or indefinite) problems with a nonfactorized preconditioner. The
+   * problem type has to be set in @p AdditionalData.
    *
    * The preconditioner does support parallel distributed computations.
    *
@@ -873,8 +734,7 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
@@ -891,69 +751,53 @@ namespace PETScWrappers
       );
 
       /**
-       * This parameter specifies the
-       * type of problem to solve:
+       * This parameter specifies the type of problem to solve:
        * <ul>
-       * <li> @p 0: nonsymmetric and/or indefinite problem, and nonsymmetric preconditioner
+       * <li> @p 0: nonsymmetric and/or indefinite problem, and nonsymmetric
+       * preconditioner
        * <li> @p 1: SPD problem, and SPD (factored) preconditioner
-       * <li> @p 2: nonsymmetric, definite problem, and SPD (factored) preconditioner
+       * <li> @p 2: nonsymmetric, definite problem, and SPD (factored)
+       * preconditioner
        * </ul>
        * Default is <tt>symmetric = 1</tt>.
        */
       unsigned int symmetric;
 
       /**
-       * The sparsity pattern used for the
-       * approximate inverse is the pattern
-       * of a power <tt>B^m</tt> where <tt>B</tt>
-       * has been sparsified from the given
-       * matrix <tt>A</tt>, <tt>n_level</tt>
-       * is equal to <tt>m+1</tt>. Default
-       * value is <tt>n_levels = 1</tt>.
+       * The sparsity pattern used for the approximate inverse is the pattern
+       * of a power <tt>B^m</tt> where <tt>B</tt> has been sparsified from the
+       * given matrix <tt>A</tt>, <tt>n_level</tt> is equal to <tt>m+1</tt>.
+       * Default value is <tt>n_levels = 1</tt>.
        */
       unsigned int n_levels;
 
       /**
-       * Sparsification is performed by
-       * dropping nonzeros which are smaller
-       * than <tt>thresh</tt> in magnitude.
-       * Lower values of <tt>thresh</tt>
-       * lead to more accurate, but also more
-       * expensive preconditioners. Default
-       * value is <tt>thresh = 0.1</tt>. Setting
-       * <tt>thresh < 0</tt> a threshold
-       * is selected automatically, such that
-       * <tt>-thresh</tt> represents the
-       * fraction of nonzero elements that are
-       * dropped. For example, if <tt>thresh = -0.9</tt>,
-       * then <tt>B</tt> will contain about
-       * ten percent of the nonzeros of the
-       * given matrix <tt>A</tt>.
+       * Sparsification is performed by dropping nonzeros which are smaller
+       * than <tt>thresh</tt> in magnitude. Lower values of <tt>thresh</tt>
+       * lead to more accurate, but also more expensive preconditioners.
+       * Default value is <tt>thresh = 0.1</tt>. Setting <tt>thresh < 0</tt> a
+       * threshold is selected automatically, such that <tt>-thresh</tt>
+       * represents the fraction of nonzero elements that are dropped. For
+       * example, if <tt>thresh = -0.9</tt>, then <tt>B</tt> will contain
+       * about ten percent of the nonzeros of the given matrix <tt>A</tt>.
        */
       double threshold;
 
       /**
-       * Filtering is a post-processing procedure,
-       * <tt>filter</tt> represents a fraction
-       * of nonzero elements that are dropped
-       * after creating the approximate inverse
-       * sparsity pattern. Default value is
-       * <tt>filter = 0.05</tt>. Setting <tt>filter < 0</tt>
-       * a value is selected automatically, such
-       * that <tt>-filter</tt> represents the
-       * fraction of nonzero elements that are
-       * dropped. For example, if <tt>thresh = -0.9</tt>,
-       * then about 90 percent of the entries
-       * in the computed approximate inverse are
-       * dropped.
+       * Filtering is a post-processing procedure, <tt>filter</tt> represents
+       * a fraction of nonzero elements that are dropped after creating the
+       * approximate inverse sparsity pattern. Default value is <tt>filter =
+       * 0.05</tt>. Setting <tt>filter < 0</tt> a value is selected
+       * automatically, such that <tt>-filter</tt> represents the fraction of
+       * nonzero elements that are dropped. For example, if <tt>thresh =
+       * -0.9</tt>, then about 90 percent of the entries in the computed
+       * approximate inverse are dropped.
        */
       double filter;
 
       /**
-       * Setting this flag to true
-       * produces output from HYPRE,
-       * when the preconditioner
-       * is constructed.
+       * Setting this flag to true produces output from HYPRE, when the
+       * preconditioner is constructed.
        */
       bool output_details;
     };
@@ -961,39 +805,30 @@ namespace PETScWrappers
 
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionParaSails ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any.
      */
     PreconditionParaSails (const MatrixBase     &matrix,
                            const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   private:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
@@ -1010,49 +845,39 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional flags to the
+     * Standardized data struct to pipe additional flags to the
      * preconditioner.
      */
     struct AdditionalData
     {};
 
     /**
-     * Empty Constructor. You need to call
-     * initialize() before using this
+     * Empty Constructor. You need to call initialize() before using this
      * object.
      */
     PreconditionNone ();
 
     /**
-     * Constructor. Take the matrix which
-     * is used to form the preconditioner,
-     * and additional flags if there are
-     * any. The matrix is completely
-     * ignored in computations.
+     * Constructor. Take the matrix which is used to form the preconditioner,
+     * and additional flags if there are any. The matrix is completely ignored
+     * in computations.
      */
     PreconditionNone (const MatrixBase     &matrix,
                       const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner
-     * object and calculate all data that
-     * is necessary for applying it in a
-     * solver. This function is
-     * automatically called when calling
-     * the constructor with the same
-     * arguments and is only used if you
-     * create the preconditioner without
-     * arguments. The matrix is completely
-     * ignored in computations.
+     * Initializes the preconditioner object and calculate all data that is
+     * necessary for applying it in a solver. This function is automatically
+     * called when calling the constructor with the same arguments and is only
+     * used if you create the preconditioner without arguments. The matrix is
+     * completely ignored in computations.
      */
     void initialize (const MatrixBase     &matrix,
                      const AdditionalData &additional_data = AdditionalData());
 
   private:
     /**
-     * Store a copy of the flags for this
-     * particular preconditioner.
+     * Store a copy of the flags for this particular preconditioner.
      */
     AdditionalData additional_data;
   };
index c4b33057de07fe7ee49073715c5bfae10e110fd8..ef584f8ee3fe646ad9ece17bf8073b3ad8c1384a 100644 (file)
@@ -45,37 +45,34 @@ namespace PETScWrappers
    * classes simply set the right flags to select one solver or another, or to
    * set certain parameters for individual solvers.
    *
-   * Optionally, the user can create a solver derived from the
-   * SolverBase class and can set the default arguments necessary to
-   * solve the linear system of equations with SolverControl. These
-   * default options can be overridden by specifying command line
-   * arguments of the form @p -ksp_*. For example,
-   * @p -ksp_monitor_true_residual prints out true residual norm
+   * Optionally, the user can create a solver derived from the SolverBase
+   * class and can set the default arguments necessary to solve the linear
+   * system of equations with SolverControl. These default options can be
+   * overridden by specifying command line arguments of the form @p -ksp_*.
+   * For example, @p -ksp_monitor_true_residual prints out true residual norm
    * (unpreconditioned) at each iteration and @p -ksp_view provides
-   * information about the linear solver and the preconditioner used in
-   * the current context. The type of the solver can also be changed
-   * during runtime by specifying @p -ksp_type {richardson, cg, gmres,
-   * fgmres, ..} to dynamically test the optimal solver along with a
-   * suitable preconditioner set using @p -pc_type {jacobi, bjacobi,
-   * ilu, lu, ..}. There are several other command line options
-   * available to modify the behavior of the PETSc linear solver and can
-   * be obtained from the <a
-   * href="http://www.mcs.anl.gov/petsc">documentation and manual
-   * pages</a>.
+   * information about the linear solver and the preconditioner used in the
+   * current context. The type of the solver can also be changed during
+   * runtime by specifying @p -ksp_type {richardson, cg, gmres, fgmres, ..} to
+   * dynamically test the optimal solver along with a suitable preconditioner
+   * set using @p -pc_type {jacobi, bjacobi, ilu, lu, ..}. There are several
+   * other command line options available to modify the behavior of the PETSc
+   * linear solver and can be obtained from the <a
+   * href="http://www.mcs.anl.gov/petsc">documentation and manual pages</a>.
    *
    * @note Repeated calls to solve() on a solver object with a Preconditioner
-   * must be used with care. The preconditioner is initialized in the first call
-   * to solve() and subsequent calls reuse the solver and preconditioner
-   * object. This is done for performance reasons. The solver and preconditioner
-   * can be reset by calling reset().
+   * must be used with care. The preconditioner is initialized in the first
+   * call to solve() and subsequent calls reuse the solver and preconditioner
+   * object. This is done for performance reasons. The solver and
+   * preconditioner can be reset by calling reset().
    *
    * One of the gotchas of PETSc is that -- in particular in MPI mode -- it
    * often does not produce very helpful error messages. In order to save
    * other users some time in searching a hard to track down error, here is
-   * one situation and the error message one gets there:
-   * when you don't specify an MPI communicator to your solver's constructor. In
-   * this case, you will get an error of the following form from each of your
-   * parallel processes:
+   * one situation and the error message one gets there: when you don't
+   * specify an MPI communicator to your solver's constructor. In this case,
+   * you will get an error of the following form from each of your parallel
+   * processes:
    * @verbatim
    *   [1]PETSC ERROR: PCSetVector() line 1173 in src/ksp/pc/interface/precon.c
    *   [1]PETSC ERROR:   Arguments must have same communicators!
@@ -83,15 +80,14 @@ namespace PETScWrappers
    *   [1]PETSC ERROR: KSPSetUp() line 195 in src/ksp/ksp/interface/itfunc.c
    * @endverbatim
    *
-   * This error, on which one can spend a very long time figuring out
-   * what exactly goes wrong, results from not specifying an MPI
-   * communicator. Note that the communicator @em must match that of the
-   * matrix and all vectors in the linear system which we want to
-   * solve. Aggravating the situation is the fact that the default
-   * argument to the solver classes, @p PETSC_COMM_SELF, is the
-   * appropriate argument for the sequential case (which is why it is
-   * the default argument), so this error only shows up in parallel
-   * mode.
+   * This error, on which one can spend a very long time figuring out what
+   * exactly goes wrong, results from not specifying an MPI communicator. Note
+   * that the communicator @em must match that of the matrix and all vectors
+   * in the linear system which we want to solve. Aggravating the situation is
+   * the fact that the default argument to the solver classes, @p
+   * PETSC_COMM_SELF, is the appropriate argument for the sequential case
+   * (which is why it is the default argument), so this error only shows up in
+   * parallel mode.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, 2004
@@ -100,20 +96,13 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Constructor. Takes the solver
-     * control object and the MPI
-     * communicator over which parallel
-     * computations are to happen.
+     * Constructor. Takes the solver control object and the MPI communicator
+     * over which parallel computations are to happen.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverBase (SolverControl  &cn,
                 const MPI_Comm &mpi_communicator);
@@ -124,16 +113,11 @@ namespace PETScWrappers
     virtual ~SolverBase ();
 
     /**
-     * Solve the linear system
-     * <tt>Ax=b</tt>. Depending on the
-     * information provided by derived
-     * classes and the object passed as a
-     * preconditioner, one of the linear
-     * solvers and preconditioners of PETSc
-     * is chosen.  Repeated calls to
-     * solve() do not reconstruct the
-     * preconditioner for performance
-     * reasons. See class Documentation.
+     * Solve the linear system <tt>Ax=b</tt>. Depending on the information
+     * provided by derived classes and the object passed as a preconditioner,
+     * one of the linear solvers and preconditioners of PETSc is chosen.
+     * Repeated calls to solve() do not reconstruct the preconditioner for
+     * performance reasons. See class Documentation.
      */
     void
     solve (const MatrixBase         &A,
@@ -143,25 +127,21 @@ namespace PETScWrappers
 
 
     /**
-     * Resets the contained preconditioner
-     * and solver object. See class
+     * Resets the contained preconditioner and solver object. See class
      * description for more details.
      */
     virtual void reset();
 
 
     /**
-      * Sets a prefix name for the solver
-      * object. Useful when customizing the
-      * PETSc KSP object with command-line
-      * options.
-      */
+     * Sets a prefix name for the solver object. Useful when customizing the
+     * PETSc KSP object with command-line options.
+     */
     void set_prefix(const std::string &prefix);
 
 
     /**
-     * Access to object that controls
-     * convergence.
+     * Access to object that controls convergence.
      */
     SolverControl &control() const;
 
@@ -176,51 +156,38 @@ namespace PETScWrappers
   protected:
 
     /**
-     * Reference to the object that
-     * controls convergence of the
-     * iterative solver. In fact, for these
-     * PETSc wrappers, PETSc does so
-     * itself, but we copy the data from
-     * this object before starting the
-     * solution process, and copy the data
-     * back into it afterwards.
+     * Reference to the object that controls convergence of the iterative
+     * solver. In fact, for these PETSc wrappers, PETSc does so itself, but we
+     * copy the data from this object before starting the solution process,
+     * and copy the data back into it afterwards.
      */
     SolverControl &solver_control;
 
     /**
-     * Copy of the MPI communicator object
-     * to be used for the solver.
+     * Copy of the MPI communicator object to be used for the solver.
      */
     const MPI_Comm mpi_communicator;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     * requested by the derived class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is requested by the derived class.
      */
     virtual void set_solver_type (KSP &ksp) const = 0;
 
     /**
-     * Solver prefix name to qualify options
-     * specific to the PETSc KSP object in the
-     * current context.
-     * Note: A hyphen (-) must NOT be given
-     * at the beginning of the prefix name.
-     * The first character of all runtime
+     * Solver prefix name to qualify options specific to the PETSc KSP object
+     * in the current context. Note: A hyphen (-) must NOT be given at the
+     * beginning of the prefix name. The first character of all runtime
      * options is AUTOMATICALLY the hyphen.
      */
     std::string prefix_name;
 
   private:
     /**
-     * A function that is used in PETSc as
-     * a callback to check on
-     * convergence. It takes the
-     * information provided from PETSc and
-     * checks it against deal.II's own
-     * SolverControl objects to see if
-     * convergence has been reached.
+     * A function that is used in PETSc as a callback to check on convergence.
+     * It takes the information provided from PETSc and checks it against
+     * deal.II's own SolverControl objects to see if convergence has been
+     * reached.
      */
     static
     PetscErrorCode convergence_test (KSP                 ksp,
@@ -230,33 +197,21 @@ namespace PETScWrappers
                                      void               *solver_control);
 
     /**
-     * A structure that contains the PETSc
-     * solver and preconditioner
-     * objects. This object is preserved
-     * between subsequent calls to the
-     * solver if the same preconditioner is
-     * used as in the previous solver
-     * step. This may save some computation
-     * time, if setting up a preconditioner
-     * is expensive, such as in the case of
-     * an ILU for example.
+     * A structure that contains the PETSc solver and preconditioner objects.
+     * This object is preserved between subsequent calls to the solver if the
+     * same preconditioner is used as in the previous solver step. This may
+     * save some computation time, if setting up a preconditioner is
+     * expensive, such as in the case of an ILU for example.
      *
-     * The actual declaration of this class
-     * is complicated by the fact that
-     * PETSc changed its solver interface
-     * completely and incompatibly between
+     * The actual declaration of this class is complicated by the fact that
+     * PETSc changed its solver interface completely and incompatibly between
      * versions 2.1.6 and 2.2.0 :-(
      *
-     * Objects of this type are explicitly
-     * created, but are destroyed when the
-     * surrounding solver object goes out
-     * of scope, or when we assign a new
-     * value to the pointer to this
-     * object. The respective *Destroy
-     * functions are therefore written into
-     * the destructor of this object, even
-     * though the object does not have a
-     * constructor.
+     * Objects of this type are explicitly created, but are destroyed when the
+     * surrounding solver object goes out of scope, or when we assign a new
+     * value to the pointer to this object. The respective *Destroy functions
+     * are therefore written into the destructor of this object, even though
+     * the object does not have a constructor.
      */
     struct SolverData
     {
@@ -266,18 +221,15 @@ namespace PETScWrappers
       ~SolverData ();
 
       /**
-       * Objects for Krylov subspace
-       * solvers and preconditioners.
+       * Objects for Krylov subspace solvers and preconditioners.
        */
       KSP  ksp;
       PC   pc;
     };
 
     /**
-     * Pointer to an object that stores the
-     * solver context. This is recreated in
-     * the main solver routine if
-     * necessary.
+     * Pointer to an object that stores the solver context. This is recreated
+     * in the main solver routine if necessary.
      */
     std_cxx11::shared_ptr<SolverData> solver_data;
   };
@@ -295,16 +247,12 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default,
-       * set the damping parameter
-       * to one.
+       * Constructor. By default, set the damping parameter to one.
        */
       AdditionalData (const double omega = 1);
 
@@ -315,32 +263,20 @@ namespace PETScWrappers
     };
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverRichardson (SolverControl        &cn,
                       const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -348,16 +284,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -375,40 +308,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverChebychev (SolverControl        &cn,
                      const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -416,16 +335,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -433,8 +349,7 @@ namespace PETScWrappers
 
 
   /**
-   * An implementation of the solver interface using the PETSc CG
-   * solver.
+   * An implementation of the solver interface using the PETSc CG solver.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, 2004
@@ -443,40 +358,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverCG (SolverControl        &cn,
               const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -484,16 +385,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -501,8 +399,7 @@ namespace PETScWrappers
 
 
   /**
-   * An implementation of the solver interface using the PETSc BiCG
-   * solver.
+   * An implementation of the solver interface using the PETSc BiCG solver.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, 2004
@@ -511,40 +408,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverBiCG (SolverControl        &cn,
                 const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -552,16 +435,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -569,8 +449,7 @@ namespace PETScWrappers
 
 
   /**
-   * An implementation of the solver interface using the PETSc GMRES
-   * solver.
+   * An implementation of the solver interface using the PETSc GMRES solver.
    *
    * @author Wolfgang Bangerth, 2004
    */
@@ -578,61 +457,43 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default, set the
-       * number of temporary vectors to
-       * 30, i.e. do a restart every 30
-       * iterations.
+       * Constructor. By default, set the number of temporary vectors to 30,
+       * i.e. do a restart every 30 iterations.
        */
       AdditionalData (const unsigned int restart_parameter = 30,
                       const bool right_preconditioning = false);
 
       /**
-       * Maximum number of
-       * tmp vectors.
+       * Maximum number of tmp vectors.
        */
       unsigned int restart_parameter;
 
       /**
-       * Flag for right
-       * preconditioning.
+       * Flag for right preconditioning.
        */
       bool right_preconditioning;
     };
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverGMRES (SolverControl        &cn,
                  const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -640,16 +501,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -667,40 +525,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverBicgstab (SolverControl        &cn,
                     const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -708,16 +552,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -733,40 +574,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverCGS (SolverControl        &cn,
                const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -774,16 +601,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -791,8 +615,7 @@ namespace PETScWrappers
 
 
   /**
-   * An implementation of the solver interface using the PETSc TFQMR
-   * solver.
+   * An implementation of the solver interface using the PETSc TFQMR solver.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, 2004
@@ -801,40 +624,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverTFQMR (SolverControl        &cn,
                  const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -842,16 +651,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -863,8 +669,8 @@ namespace PETScWrappers
    * An implementation of the solver interface using the PETSc TFQMR-2 solver
    * (called TCQMR in PETSc). Note that this solver had a serious bug in
    * versions up to and including PETSc 2.1.6, in that it did not check
-   * convergence and always returned an error code. Thus, this class will abort
-   * with an error indicating failure to converge with PETSc 2.1.6 and
+   * convergence and always returned an error code. Thus, this class will
+   * abort with an error indicating failure to converge with PETSc 2.1.6 and
    * prior. This should be fixed in later versions of PETSc, though.
    *
    * @ingroup PETScWrappers
@@ -874,40 +680,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverTCQMR (SolverControl        &cn,
                  const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -915,16 +707,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -932,8 +721,7 @@ namespace PETScWrappers
 
 
   /**
-   * An implementation of the solver interface using the PETSc CR
-   * solver.
+   * An implementation of the solver interface using the PETSc CR solver.
    *
    * @ingroup PETScWrappers
    * @author Wolfgang Bangerth, 2004
@@ -942,40 +730,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverCR (SolverControl        &cn,
               const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -983,16 +757,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -1010,40 +781,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverLSQR (SolverControl        &cn,
                 const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -1051,27 +808,24 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     *appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
 
 
   /**
-   * An implementation of the solver interface using the PETSc PREONLY
-   * solver. Actually this is NOT a real solution algorithm. solve() only
-   * applies the preconditioner once and returns immediately. Its only purpose
-   * is to provide a solver object, when the preconditioner should be used as a
-   * real solver. It is very useful in conjunction with the complete LU
+   * An implementation of the solver interface using the PETSc PREONLY solver.
+   * Actually this is NOT a real solution algorithm. solve() only applies the
+   * preconditioner once and returns immediately. Its only purpose is to
+   * provide a solver object, when the preconditioner should be used as a real
+   * solver. It is very useful in conjunction with the complete LU
    * decomposition preconditioner <tt> PreconditionLU </tt>, which in
    * conjunction with this solver class becomes a direct solver.
    *
@@ -1082,40 +836,26 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
 
     /**
-     * Constructor. In contrast to
-     * deal.II's own solvers, there is no
-     * need to give a vector memory
-     * object. However, PETSc solvers want
-     * to have an MPI communicator context
-     * over which computations are
-     * parallelized. By default,
-     * @p PETSC_COMM_SELF is used here,
-     * but you can change this. Note that
-     * for single processor (non-MPI)
-     * versions, this parameter does not
+     * Constructor. In contrast to deal.II's own solvers, there is no need to
+     * give a vector memory object. However, PETSc solvers want to have an MPI
+     * communicator context over which computations are parallelized. By
+     * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+     * that for single processor (non-MPI) versions, this parameter does not
      * have any effect.
      *
-     * The last argument takes a structure
-     * with additional, solver dependent
+     * The last argument takes a structure with additional, solver dependent
      * flags for tuning.
      *
-     * Note that the communicator used here
-     * must match the communicator used in
-     * the system matrix, solution, and
-     * right hand side object of the solve
-     * to be done with this
-     * solver. Otherwise, PETSc will
-     * generate hard to track down errors,
-     * see the documentation of the
-     * SolverBase class.
+     * Note that the communicator used here must match the communicator used
+     * in the system matrix, solution, and right hand side object of the solve
+     * to be done with this solver. Otherwise, PETSc will generate hard to
+     * track down errors, see the documentation of the SolverBase class.
      */
     SolverPreOnly (SolverControl        &cn,
                    const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -1123,16 +863,13 @@ namespace PETScWrappers
 
   protected:
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Krylov
-     * Subspace Solver context object, and
-     * sets the type of solver that is
-     * appropriate for this class.
+     * Function that takes a Krylov Subspace Solver context object, and sets
+     * the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (KSP &ksp) const;
   };
@@ -1141,11 +878,11 @@ namespace PETScWrappers
    * An implementation of the solver interface using the sparse direct MUMPS
    * solver through PETSc. This class has the usual interface of all other
    * solver classes but it is of course different in that it doesn't implement
-   * an iterative solver. As a consequence, things like the SolverControl object
-   * have no particular meaning here.
+   * an iterative solver. As a consequence, things like the SolverControl
+   * object have no particular meaning here.
    *
-   * MUMPS allows to make use of symmetry in this matrix. In this class this is
-   * made possible by the set_symmetric_mode() function. If your matrix is
+   * MUMPS allows to make use of symmetry in this matrix. In this class this
+   * is made possible by the set_symmetric_mode() function. If your matrix is
    * symmetric, you can use this class as follows:
    * @code
    *    SolverControl cn;
@@ -1154,9 +891,10 @@ namespace PETScWrappers
    *    solver.solve(system_matrix, solution, system_rhs);
    * @endcode
    *
-   * @note The class internally calls KSPSetFromOptions thus you are
-   * able to use all the PETSc parameters for MATSOLVERMUMPS package.
-   * See http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMUMPS.html
+   * @note The class internally calls KSPSetFromOptions thus you are able to
+   * use all the PETSc parameters for MATSOLVERMUMPS package. See
+   * http://www.mcs.anl.gov/petsc/petsc-
+   * current/docs/manualpages/Mat/MATSOLVERMUMPS.html
    *
    * @ingroup PETScWrappers
    * @author Daniel Brauss, Alexander Grayver, 2012
@@ -1165,9 +903,7 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Standardized data structure
-     * to pipe additional data to
-     * the solver.
+     * Standardized data structure to pipe additional data to the solver.
      */
     struct AdditionalData
     {};
@@ -1179,27 +915,22 @@ namespace PETScWrappers
                        const AdditionalData &data = AdditionalData());
 
     /**
-     * The method to solve the
-     * linear system.
+     * The method to solve the linear system.
      */
     void solve (const MatrixBase &A,
                 VectorBase       &x,
                 const VectorBase &b);
 
     /**
-    * The method allows to take advantage
-    * if the system matrix is symmetric by
-    * using LDL^T decomposition instead of
-    * more expensive LU. The argument
-    * indicates whether the matrix is
-    * symmetric or not.
-    */
+     * The method allows to take advantage if the system matrix is symmetric
+     * by using LDL^T decomposition instead of more expensive LU. The argument
+     * indicates whether the matrix is symmetric or not.
+     */
     void set_symmetric_mode (const bool flag);
 
   protected:
     /**
-     * Store a copy of flags for this
-     * particular solver.
+     * Store a copy of flags for this particular solver.
      */
     const AdditionalData additional_data;
 
@@ -1207,12 +938,10 @@ namespace PETScWrappers
 
   private:
     /**
-     * A function that is used in PETSc
-     * as a callback to check convergence.
-     * It takes the information provided
-     * from PETSc and checks it against
-     * deal.II's own SolverControl objects
-     * to see if convergence has been reached.
+     * A function that is used in PETSc as a callback to check convergence. It
+     * takes the information provided from PETSc and checks it against
+     * deal.II's own SolverControl objects to see if convergence has been
+     * reached.
      */
     static
     PetscErrorCode convergence_test (KSP                ksp,
@@ -1222,13 +951,9 @@ namespace PETScWrappers
                                      void               *solver_control);
 
     /**
-     * A structure that contains the
-     * PETSc solver and preconditioner
-     * objects.  Since the solve member
-     * function in the base is not used
-     * here, the private SolverData struct
-     * located in the base could not be used
-     * either.
+     * A structure that contains the PETSc solver and preconditioner objects.
+     * Since the solve member function in the base is not used here, the
+     * private SolverData struct located in the base could not be used either.
      */
     struct SolverDataMUMPS
     {
@@ -1244,11 +969,8 @@ namespace PETScWrappers
     std_cxx11::shared_ptr<SolverDataMUMPS> solver_data;
 
     /**
-     * Flag specifies whether matrix
-     * being factorized is symmetric
-     * or not. It influences the type
-     * of the used preconditioner
-     * (PCLU or PCCHOLESKY)
+     * Flag specifies whether matrix being factorized is symmetric or not. It
+     * influences the type of the used preconditioner (PCLU or PCCHOLESKY)
      */
     bool symmetric_mode;
   };
index 7a366152eedd5189ab09c124f41fd21785f77145..9bbf0b2edef87cb7bf331c5e780c603a0d580f1f 100644 (file)
@@ -33,13 +33,13 @@ template <typename MatrixType> class BlockMatrixBase;
 namespace PETScWrappers
 {
   /**
-   * Implementation of a sequential sparse matrix class based on PETSC. All the
-   * functionality is actually in the base class, except for the calls to
-   * generate a sequential sparse matrix. This is possible since PETSc only works
-   * on an abstract matrix type and internally distributes to functions that do
-   * the actual work depending on the actual matrix type (much like using
-   * virtual functions). Only the functions creating a matrix of specific type
-   * differ, and are implemented in this particular class.
+   * Implementation of a sequential sparse matrix class based on PETSC. All
+   * the functionality is actually in the base class, except for the calls to
+   * generate a sequential sparse matrix. This is possible since PETSc only
+   * works on an abstract matrix type and internally distributes to functions
+   * that do the actual work depending on the actual matrix type (much like
+   * using virtual functions). Only the functions creating a matrix of
+   * specific type differ, and are implemented in this particular class.
    *
    * @ingroup PETScWrappers
    * @ingroup Matrix1
@@ -50,56 +50,39 @@ namespace PETScWrappers
   public:
 
     /**
-     * A structure that describes some of
-     * the traits of this class in terms of
-     * its run-time behavior. Some other
-     * classes (such as the block matrix
-     * classes) that take one or other of
-     * the matrix classes as its template
-     * parameters can tune their behavior
-     * based on the variables in this
+     * A structure that describes some of the traits of this class in terms of
+     * its run-time behavior. Some other classes (such as the block matrix
+     * classes) that take one or other of the matrix classes as its template
+     * parameters can tune their behavior based on the variables in this
      * class.
      */
     struct Traits
     {
       /**
-       * It is safe to elide additions of
-       * zeros to individual elements of
-       * this matrix.
+       * It is safe to elide additions of zeros to individual elements of this
+       * matrix.
        */
       static const bool zero_addition_can_be_elided = true;
     };
 
     /**
-     * Default constructor. Create an empty
-     * matrix.
+     * Default constructor. Create an empty matrix.
      */
     SparseMatrix ();
 
     /**
-     * Create a sparse matrix of dimensions
-     * @p m times @p n, with an
-     * initial guess of
-     * @p n_nonzero_per_row nonzero
-     * elements per row. PETSc is able to
-     * cope with the situation that more
-     * than this number of elements is
-     * later allocated for a row, but this
-     * involves copying data, and is thus
+     * Create a sparse matrix of dimensions @p m times @p n, with an initial
+     * guess of @p n_nonzero_per_row nonzero elements per row. PETSc is able
+     * to cope with the situation that more than this number of elements is
+     * later allocated for a row, but this involves copying data, and is thus
      * expensive.
      *
-     * The @p is_symmetric flag determines
-     * whether we should tell PETSc that
-     * the matrix is going to be symmetric
-     * (as indicated by the call
-     * <tt>MatSetOption(mat,
-     * MAT_SYMMETRIC)</tt>. Note that the
-     * PETSc documentation states that one
-     * cannot form an ILU decomposition of
-     * a matrix for which this flag has
-     * been set to @p true, only an
-     * ICC. The default value of this flag
-     * is @p false.
+     * The @p is_symmetric flag determines whether we should tell PETSc that
+     * the matrix is going to be symmetric (as indicated by the call
+     * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+     * documentation states that one cannot form an ILU decomposition of a
+     * matrix for which this flag has been set to @p true, only an ICC. The
+     * default value of this flag is @p false.
      */
     SparseMatrix (const size_type m,
                   const size_type n,
@@ -107,32 +90,20 @@ namespace PETScWrappers
                   const bool      is_symmetric = false);
 
     /**
-     * Initialize a rectangular matrix with
-     * @p m rows and @p n
-     * columns.  The maximal number of
-     * nonzero entries for each row
-     * separately is given by the
-     * @p row_lengths array.
+     * Initialize a rectangular matrix with @p m rows and @p n columns.  The
+     * maximal number of nonzero entries for each row separately is given by
+     * the @p row_lengths array.
      *
-     * Just as for the other constructors:
-     * PETSc is able to cope with the
-     * situation that more than this number
-     * of elements is later allocated for a
-     * row, but this involves copying data,
-     * and is thus expensive.
+     * Just as for the other constructors: PETSc is able to cope with the
+     * situation that more than this number of elements is later allocated for
+     * a row, but this involves copying data, and is thus expensive.
      *
-     * The @p is_symmetric flag determines
-     * whether we should tell PETSc that
-     * the matrix is going to be symmetric
-     * (as indicated by the call
-     * <tt>MatSetOption(mat,
-     * MAT_SYMMETRIC)</tt>. Note that the
-     * PETSc documentation states that one
-     * cannot form an ILU decomposition of
-     * a matrix for which this flag has
-     * been set to @p true, only an
-     * ICC. The default value of this flag
-     * is @p false.
+     * The @p is_symmetric flag determines whether we should tell PETSc that
+     * the matrix is going to be symmetric (as indicated by the call
+     * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+     * documentation states that one cannot form an ILU decomposition of a
+     * matrix for which this flag has been set to @p true, only an ICC. The
+     * default value of this flag is @p false.
      */
     SparseMatrix (const size_type               m,
                   const size_type               n,
@@ -140,66 +111,41 @@ namespace PETScWrappers
                   const bool                    is_symmetric = false);
 
     /**
-     * Initialize a sparse matrix using the
-     * given sparsity pattern.
+     * Initialize a sparse matrix using the given sparsity pattern.
      *
-     * Note that PETSc can be very slow
-     * if you do not provide it with a
-     * good estimate of the lengths of
-     * rows. Using the present function
-     * is a very efficient way to do
-     * this, as it uses the exact number
-     * of nonzero entries for each row of
-     * the matrix by using the given
-     * sparsity pattern argument. If the
-     * @p preset_nonzero_locations flag
-     * is @p true, this function in
-     * addition not only sets the correct
-     * row sizes up front, but also
-     * pre-allocated the correct nonzero
-     * entries in the matrix.
+     * Note that PETSc can be very slow if you do not provide it with a good
+     * estimate of the lengths of rows. Using the present function is a very
+     * efficient way to do this, as it uses the exact number of nonzero
+     * entries for each row of the matrix by using the given sparsity pattern
+     * argument. If the @p preset_nonzero_locations flag is @p true, this
+     * function in addition not only sets the correct row sizes up front, but
+     * also pre-allocated the correct nonzero entries in the matrix.
      *
-     * PETsc allows to later add
-     * additional nonzero entries to a
-     * matrix, by simply writing to these
-     * elements. However, this will then
-     * lead to additional memory
-     * allocations which are very
-     * inefficient and will greatly slow
-     * down your program. It is therefore
-     * significantly more efficient to
-     * get memory allocation right from
-     * the start.
+     * PETsc allows to later add additional nonzero entries to a matrix, by
+     * simply writing to these elements. However, this will then lead to
+     * additional memory allocations which are very inefficient and will
+     * greatly slow down your program. It is therefore significantly more
+     * efficient to get memory allocation right from the start.
      */
     template <typename SparsityType>
     explicit SparseMatrix (const SparsityType &sparsity_pattern,
                            const bool          preset_nonzero_locations = true);
 
     /**
-     * This operator assigns a scalar to
-     * a matrix. Since this does usually
-     * not make much sense (should we set
-     * all matrix entries to this value?
-     * Only the nonzero entries of the
-     * sparsity pattern?), this operation
-     * is only allowed if the actual
-     * value to be assigned is zero. This
-     * operator only exists to allow for
-     * the obvious notation
-     * <tt>matrix=0</tt>, which sets all
-     * elements of the matrix to zero,
-     * but keep the sparsity pattern
+     * This operator assigns a scalar to a matrix. Since this does usually not
+     * make much sense (should we set all matrix entries to this value? Only
+     * the nonzero entries of the sparsity pattern?), this operation is only
+     * allowed if the actual value to be assigned is zero. This operator only
+     * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+     * all elements of the matrix to zero, but keep the sparsity pattern
      * previously used.
      */
     SparseMatrix &operator = (const double d);
 
     /**
-     * Throw away the present matrix and
-     * generate one that has the same
-     * properties as if it were created by
-     * the constructor of this class with
-     * the same argument list as the
-     * present function.
+     * Throw away the present matrix and generate one that has the same
+     * properties as if it were created by the constructor of this class with
+     * the same argument list as the present function.
      */
     void reinit (const size_type m,
                  const size_type n,
@@ -207,12 +153,9 @@ namespace PETScWrappers
                  const bool      is_symmetric = false);
 
     /**
-     * Throw away the present matrix and
-     * generate one that has the same
-     * properties as if it were created by
-     * the constructor of this class with
-     * the same argument list as the
-     * present function.
+     * Throw away the present matrix and generate one that has the same
+     * properties as if it were created by the constructor of this class with
+     * the same argument list as the present function.
      */
     void reinit (const size_type               m,
                  const size_type               n,
@@ -220,104 +163,63 @@ namespace PETScWrappers
                  const bool                    is_symmetric = false);
 
     /**
-     * Initialize a sparse matrix using the
-     * given sparsity pattern.
+     * Initialize a sparse matrix using the given sparsity pattern.
      *
-     * Note that PETSc can be very slow
-     * if you do not provide it with a
-     * good estimate of the lengths of
-     * rows. Using the present function
-     * is a very efficient way to do
-     * this, as it uses the exact number
-     * of nonzero entries for each row of
-     * the matrix by using the given
-     * sparsity pattern argument. If the
-     * @p preset_nonzero_locations flag
-     * is @p true, this function in
-     * addition not only sets the correct
-     * row sizes up front, but also
-     * pre-allocated the correct nonzero
-     * entries in the matrix.
+     * Note that PETSc can be very slow if you do not provide it with a good
+     * estimate of the lengths of rows. Using the present function is a very
+     * efficient way to do this, as it uses the exact number of nonzero
+     * entries for each row of the matrix by using the given sparsity pattern
+     * argument. If the @p preset_nonzero_locations flag is @p true, this
+     * function in addition not only sets the correct row sizes up front, but
+     * also pre-allocated the correct nonzero entries in the matrix.
      *
-     * PETsc allows to later add
-     * additional nonzero entries to a
-     * matrix, by simply writing to these
-     * elements. However, this will then
-     * lead to additional memory
-     * allocations which are very
-     * inefficient and will greatly slow
-     * down your program. It is therefore
-     * significantly more efficient to
-     * get memory allocation right from
-     * the start.
+     * PETsc allows to later add additional nonzero entries to a matrix, by
+     * simply writing to these elements. However, this will then lead to
+     * additional memory allocations which are very inefficient and will
+     * greatly slow down your program. It is therefore significantly more
+     * efficient to get memory allocation right from the start.
      *
-     * Despite the fact that it would
-     * seem to be an obvious win, setting
-     * the @p preset_nonzero_locations
-     * flag to @p true doesn't seem to
-     * accelerate program. Rather on the
-     * contrary, it seems to be able to
-     * slow down entire programs
-     * somewhat. This is suprising, since
-     * we can use efficient function
-     * calls into PETSc that allow to
-     * create multiple entries at once;
-     * nevertheless, given the fact that
-     * it is inefficient, the respective
-     * flag has a default value equal to
-     * @p false.
+     * Despite the fact that it would seem to be an obvious win, setting the
+     * @p preset_nonzero_locations flag to @p true doesn't seem to accelerate
+     * program. Rather on the contrary, it seems to be able to slow down
+     * entire programs somewhat. This is suprising, since we can use efficient
+     * function calls into PETSc that allow to create multiple entries at
+     * once; nevertheless, given the fact that it is inefficient, the
+     * respective flag has a default value equal to @p false.
      */
     template <typename SparsityType>
     void reinit (const SparsityType &sparsity_pattern,
                  const bool          preset_nonzero_locations = true);
 
     /**
-     * Return a reference to the MPI
-     * communicator object in use with this
-     * matrix. Since this is a sequential
-     * matrix, it returns the MPI_COMM_SELF
+     * Return a reference to the MPI communicator object in use with this
+     * matrix. Since this is a sequential matrix, it returns the MPI_COMM_SELF
      * communicator.
      */
     virtual const MPI_Comm &get_mpi_communicator () const;
 
     /**
-     * Return the square of the norm
-     * of the vector $v$ with respect
-     * to the norm induced by this
-     * matrix,
-     * i.e. $\left(v,Mv\right)$. This
-     * is useful, e.g. in the finite
-     * element context, where the
-     * $L_2$ norm of a function
-     * equals the matrix norm with
-     * respect to the mass matrix of
-     * the vector representing the
-     * nodal values of the finite
-     * element function.
+     * Return the square of the norm of the vector $v$ with respect to the
+     * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful,
+     * e.g. in the finite element context, where the $L_2$ norm of a function
+     * equals the matrix norm with respect to the mass matrix of the vector
+     * representing the nodal values of the finite element function.
      *
-     * Obviously, the matrix needs to
-     * be quadratic for this operation.
+     * Obviously, the matrix needs to be quadratic for this operation.
      *
-     * The implementation of this function
-     * is not as efficient as the one in
-     * the @p MatrixBase class used in
-     * deal.II (i.e. the original one, not
-     * the PETSc wrapper class) since PETSc
-     * doesn't support this operation and
+     * The implementation of this function is not as efficient as the one in
+     * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+     * PETSc wrapper class) since PETSc doesn't support this operation and
      * needs a temporary vector.
      */
     PetscScalar matrix_norm_square (const VectorBase &v) const;
 
     /**
-     * Compute the matrix scalar
-     * product $\left(u,Mv\right)$.
+     * Compute the matrix scalar product $\left(u,Mv\right)$.
      *
-     * The implementation of this function
-     * is not as efficient as the one in
-     * the @p MatrixBase class used in
-     * deal.II (i.e. the original one, not
-     * the PETSc wrapper class) since PETSc
-     * doesn't support this operation and
+     * The implementation of this function is not as efficient as the one in
+     * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+     * PETSc wrapper class) since PETSc doesn't support this operation and
      * needs a temporary vector.
      */
     PetscScalar matrix_scalar_product (const VectorBase &u,
@@ -335,10 +237,8 @@ namespace PETScWrappers
     SparseMatrix &operator= (const SparseMatrix &);
 
     /**
-     * Do the actual work for the
-     * respective reinit() function and the
-     * matching constructor, i.e. create a
-     * matrix. Getting rid of the previous
+     * Do the actual work for the respective reinit() function and the
+     * matching constructor, i.e. create a matrix. Getting rid of the previous
      * matrix is left to the caller.
      */
     void do_reinit (const size_type m,
@@ -362,9 +262,7 @@ namespace PETScWrappers
                     const bool          preset_nonzero_locations);
 
     /**
-     *  To allow calling protected
-     *  prepare_add() and
-     *  prepare_set().
+     * To allow calling protected prepare_add() and prepare_set().
      */
     friend class BlockMatrixBase<SparseMatrix>;
   };
index 37289951687e7e8071b24e3957d53bef620de85c..ef73d9a019e965c8c031ab0906c2ca825821185c 100644 (file)
@@ -39,11 +39,11 @@ namespace PETScWrappers
   /**
    * Implementation of a sequential vector class based on PETSC. All the
    * functionality is actually in the base class, except for the calls to
-   * generate a sequential vector. This is possible since PETSc only works on an
-   * abstract vector type and internally distributes to functions that do the
-   * actual work depending on the actual vector type (much like using virtual
-   * functions). Only the functions creating a vector of specific type differ,
-   * and are implemented in this particular class.
+   * generate a sequential vector. This is possible since PETSc only works on
+   * an abstract vector type and internally distributes to functions that do
+   * the actual work depending on the actual vector type (much like using
+   * virtual functions). Only the functions creating a vector of specific type
+   * differ, and are implemented in this particular class.
    *
    * @ingroup Vectors
    * @author Wolfgang Bangerth, 2004
@@ -57,176 +57,128 @@ namespace PETScWrappers
     typedef types::global_dof_index size_type;
 
     /**
-     * A variable that indicates whether this vector
-     * supports distributed data storage. If true, then
-     * this vector also needs an appropriate compress()
-     * function that allows communicating recent set or
-     * add operations to individual elements to be communicated
-     * to other processors.
+     * A variable that indicates whether this vector supports distributed data
+     * storage. If true, then this vector also needs an appropriate compress()
+     * function that allows communicating recent set or add operations to
+     * individual elements to be communicated to other processors.
      *
-     * For the current class, the variable equals
-     * false, since it does not support parallel data storage.
-     * If you do need parallel data storage, use
-     * PETScWrappers::MPI::Vector.
+     * For the current class, the variable equals false, since it does not
+     * support parallel data storage. If you do need parallel data storage,
+     * use PETScWrappers::MPI::Vector.
      */
     static const bool supports_distributed_data = false;
 
     /**
-     * Default constructor. Initialize the
-     * vector as empty.
+     * Default constructor. Initialize the vector as empty.
      */
     Vector ();
 
     /**
-     * Constructor. Set dimension to
-     * @p n and initialize all
-     * elements with zero.
+     * Constructor. Set dimension to @p n and initialize all elements with
+     * zero.
      *
-     * The constructor is made explicit to
-     * avoid accidents like this:
-     * <tt>v=0;</tt>. Presumably, the user wants
-     * to set every element of the vector to
-     * zero, but instead, what happens is
-     * this call: <tt>v=Vector@<number@>(0);</tt>,
-     * i.e. the vector is replaced by one of
+     * The constructor is made explicit to avoid accidents like this:
+     * <tt>v=0;</tt>. Presumably, the user wants to set every element of the
+     * vector to zero, but instead, what happens is this call:
+     * <tt>v=Vector@<number@>(0);</tt>, i.e. the vector is replaced by one of
      * length zero.
      */
     explicit Vector (const size_type n);
 
     /**
-     * Copy-constructor from deal.II
-     * vectors. Sets the dimension to that
-     * of the given vector, and copies all
-     * elements.
+     * Copy-constructor from deal.II vectors. Sets the dimension to that of
+     * the given vector, and copies all elements.
      */
     template <typename Number>
     explicit Vector (const dealii::Vector<Number> &v);
 
     /**
-     * Construct it from an existing PETSc
-     * Vector of type Vec. Note: this does
-     * not copy the contents and just keeps
-     * a pointer. You need to make sure the
-     * vector is not used twice at the same
-     * time or destroyed while in use. This
-     * class does not destroy the PETSc
-     * object. Handle with care!
+     * Construct it from an existing PETSc Vector of type Vec. Note: this does
+     * not copy the contents and just keeps a pointer. You need to make sure
+     * the vector is not used twice at the same time or destroyed while in
+     * use. This class does not destroy the PETSc object. Handle with care!
      */
     explicit Vector (const Vec &v);
 
     /**
-     * Copy-constructor the values from a
-     * PETSc wrapper vector class.
+     * Copy-constructor the values from a PETSc wrapper vector class.
      */
     Vector (const Vector &v);
 
     /**
-     * Copy-constructor: copy the values
-     * from a PETSc wrapper parallel vector
+     * Copy-constructor: copy the values from a PETSc wrapper parallel vector
      * class.
      *
-     * Note that due to the communication
-     * model of MPI, @em all processes have
-     * to actually perform this operation,
-     * even if they do not use the
-     * result. It is not sufficient if only
-     * one processor tries to copy the
-     * elements from the other processors
-     * over to its own process space.
+     * Note that due to the communication model of MPI, @em all processes have
+     * to actually perform this operation, even if they do not use the result.
+     * It is not sufficient if only one processor tries to copy the elements
+     * from the other processors over to its own process space.
      */
     explicit Vector (const MPI::Vector &v);
 
     /**
-     * Copy the given vector. Resize the
-     * present vector if necessary.
+     * Copy the given vector. Resize the present vector if necessary.
      */
     Vector &operator = (const Vector &v);
 
     /**
-     * Copy all the elements of the
-     * parallel vector @p v into this
-     * local vector. Note that due to the
-     * communication model of MPI, @em all
-     * processes have to actually perform
-     * this operation, even if they do not
-     * use the result. It is not sufficient
-     * if only one processor tries to copy
-     * the elements from the other
-     * processors over to its own process
+     * Copy all the elements of the parallel vector @p v into this local
+     * vector. Note that due to the communication model of MPI, @em all
+     * processes have to actually perform this operation, even if they do not
+     * use the result. It is not sufficient if only one processor tries to
+     * copy the elements from the other processors over to its own process
      * space.
      */
     Vector &operator = (const MPI::Vector &v);
 
     /**
-     * Set all components of the vector to
-     * the given number @p s. Simply pass
-     * this down to the base class, but we
-     * still need to declare this function
-     * to make the example given in the
-     * discussion about making the
+     * Set all components of the vector to the given number @p s. Simply pass
+     * this down to the base class, but we still need to declare this function
+     * to make the example given in the discussion about making the
      * constructor explicit work.
      *
-     * Since the semantics of assigning a
-     * scalar to a vector are not
-     * immediately clear, this operator
-     * should really only be used if you
-     * want to set the entire vector to
-     * zero. This allows the intuitive
-     * notation <tt>v=0</tt>. Assigning
-     * other values is deprecated and may
-     * be disallowed in the future.
+     * Since the semantics of assigning a scalar to a vector are not
+     * immediately clear, this operator should really only be used if you want
+     * to set the entire vector to zero. This allows the intuitive notation
+     * <tt>v=0</tt>. Assigning other values is deprecated and may be
+     * disallowed in the future.
      */
     Vector &operator = (const PetscScalar s);
 
     /**
-     * Copy the values of a deal.II vector
-     * (as opposed to those of the PETSc
-     * vector wrapper class) into this
-     * object.
+     * Copy the values of a deal.II vector (as opposed to those of the PETSc
+     * vector wrapper class) into this object.
      */
     template <typename number>
     Vector &operator = (const dealii::Vector<number> &v);
 
     /**
-     * Change the dimension of the vector
-     * to @p N. It is unspecified how
-     * resizing the vector affects the
-     * memory allocation of this object;
-     * i.e., it is not guaranteed that
-     * resizing it to a smaller size
-     * actually also reduces memory
-     * consumption, or if for efficiency
-     * the same amount of memory is used
-     * for less data.
+     * Change the dimension of the vector to @p N. It is unspecified how
+     * resizing the vector affects the memory allocation of this object; i.e.,
+     * it is not guaranteed that resizing it to a smaller size actually also
+     * reduces memory consumption, or if for efficiency the same amount of
+     * memory is used for less data.
      *
-     * If @p fast is false, the vector is
-     * filled by zeros. Otherwise, the
-     * elements are left an unspecified
-     * state.
+     * If @p fast is false, the vector is filled by zeros. Otherwise, the
+     * elements are left an unspecified state.
      */
     void reinit (const size_type N,
                  const bool      fast = false);
 
     /**
-     * Change the dimension to that of the
-     * vector @p v. The same applies as
+     * Change the dimension to that of the vector @p v. The same applies as
      * for the other reinit() function.
      *
-     * The elements of @p v are not
-     * copied, i.e.  this function is the
-     * same as calling <tt>reinit (v.size(),
-     * fast)</tt>.
+     * The elements of @p v are not copied, i.e.  this function is the same as
+     * calling <tt>reinit (v.size(), fast)</tt>.
      */
     void reinit (const Vector &v,
                  const bool    fast = false);
 
   protected:
     /**
-     * Create a vector of length @p n. For
-     * this class, we create a sequential
-     * vector. @p n denotes the total
-     * size of the vector to be
-     * created.
+     * Create a vector of length @p n. For this class, we create a sequential
+     * vector. @p n denotes the total size of the vector to be created.
      */
     void create_vector (const size_type n);
   };
@@ -237,9 +189,9 @@ namespace PETScWrappers
 
 
   /**
-   * Global function @p swap which overloads the default implementation
-   * of the C++ standard library which uses a temporary object. The
-   * function simply exchanges the data of the two vectors.
+   * Global function @p swap which overloads the default implementation of the
+   * C++ standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates PETScWrappers::Vector
    * @author Wolfgang Bangerth, 2004
index 37f98f72a106ee6f52fe584cdb20d160669a8e69..bee40b44e8192ce9d297abec1cbe1c679df5be6b 100644 (file)
@@ -61,22 +61,15 @@ namespace PETScWrappers
   namespace internal
   {
     /**
-     * Since access to PETSc vectors only
-     * goes through functions, rather than by
-     * obtaining a reference to a vector
-     * element, we need a wrapper class that
-     * acts as if it was a reference, and
-     * basically redirects all accesses (read
-     * and write) to member functions of this
-     * class.
+     * Since access to PETSc vectors only goes through functions, rather than
+     * by obtaining a reference to a vector element, we need a wrapper class
+     * that acts as if it was a reference, and basically redirects all
+     * accesses (read and write) to member functions of this class.
      *
-     * This class implements such a wrapper:
-     * it is initialized with a vector and an
-     * element within it, and has a
-     * conversion operator to extract the
-     * scalar value of this element. It also
-     * has a variety of assignment operator
-     * for writing to this one element.
+     * This class implements such a wrapper: it is initialized with a vector
+     * and an element within it, and has a conversion operator to extract the
+     * scalar value of this element. It also has a variety of assignment
+     * operator for writing to this one element.
      * @ingroup PETScWrappers
      */
     class VectorReference
@@ -89,8 +82,7 @@ namespace PETScWrappers
 
     private:
       /**
-       * Constructor. It is made private so
-       * as to only allow the actual vector
+       * Constructor. It is made private so as to only allow the actual vector
        * class to create it.
        */
       VectorReference (const VectorBase  &vector,
@@ -100,72 +92,53 @@ namespace PETScWrappers
     public:
 
       /**
-       * This looks like a copy operator,
-       * but does something different than
-       * usual. In particular, it does not
-       * copy the member variables of this
-       * reference. Rather, it handles the
-       * situation where we have two
-       * vectors @p v and @p w, and assign
-       * elements like in
-       * <tt>v(i)=w(i)</tt>. Here, both
-       * left and right hand side of the
-       * assignment have data type
-       * VectorReference, but what we
-       * really mean is to assign the
-       * vector elements represented by the
-       * two references. This operator
-       * implements this operation. Note
-       * also that this allows us to make
-       * the assignment operator const.
+       * This looks like a copy operator, but does something different than
+       * usual. In particular, it does not copy the member variables of this
+       * reference. Rather, it handles the situation where we have two vectors
+       * @p v and @p w, and assign elements like in <tt>v(i)=w(i)</tt>. Here,
+       * both left and right hand side of the assignment have data type
+       * VectorReference, but what we really mean is to assign the vector
+       * elements represented by the two references. This operator implements
+       * this operation. Note also that this allows us to make the assignment
+       * operator const.
        */
       const VectorReference &operator = (const VectorReference &r) const;
 
       /**
-       * The same function as above, but
-       * for non-const reference
-       * objects. The function is needed
-       * since the compiler might otherwise
-       * automatically generate a copy
-       * operator for non-const objects.
+       * The same function as above, but for non-const reference objects. The
+       * function is needed since the compiler might otherwise automatically
+       * generate a copy operator for non-const objects.
        */
       VectorReference &operator = (const VectorReference &r);
 
       /**
-       * Set the referenced element of the
-       * vector to <tt>s</tt>.
+       * Set the referenced element of the vector to <tt>s</tt>.
        */
       const VectorReference &operator = (const PetscScalar &s) const;
 
       /**
-       * Add <tt>s</tt> to the referenced
-       * element of the vector.
+       * Add <tt>s</tt> to the referenced element of the vector.
        */
       const VectorReference &operator += (const PetscScalar &s) const;
 
       /**
-       * Subtract <tt>s</tt> from the
-       * referenced element of the vector.
+       * Subtract <tt>s</tt> from the referenced element of the vector.
        */
       const VectorReference &operator -= (const PetscScalar &s) const;
 
       /**
-       * Multiply the referenced element of
-       * the vector by <tt>s</tt>.
+       * Multiply the referenced element of the vector by <tt>s</tt>.
        */
       const VectorReference &operator *= (const PetscScalar &s) const;
 
       /**
-       * Divide the referenced element of
-       * the vector by <tt>s</tt>.
+       * Divide the referenced element of the vector by <tt>s</tt>.
        */
       const VectorReference &operator /= (const PetscScalar &s) const;
 
       /**
-       * Convert the reference to an actual
-       * value, i.e. return the value of
-       * the referenced element of the
-       * vector.
+       * Convert the reference to an actual value, i.e. return the value of
+       * the referenced element of the vector.
        */
       operator PetscScalar () const;
 
@@ -204,20 +177,17 @@ namespace PETScWrappers
 
     private:
       /**
-       * Point to the vector we are
-       * referencing.
+       * Point to the vector we are referencing.
        */
       const VectorBase   &vector;
 
       /**
-       * Index of the referenced element of
-       * the vector.
+       * Index of the referenced element of the vector.
        */
       const size_type index;
 
       /**
-       * Make the vector class a friend, so
-       * that it can create objects of the
+       * Make the vector class a friend, so that it can create objects of the
        * present type.
        */
       friend class ::dealii::PETScWrappers::VectorBase;
@@ -229,20 +199,20 @@ namespace PETScWrappers
 
 
   /**
-   * Base class for all vector classes that are implemented on top of the PETSc
-   * vector types. Since in PETSc all vector types (i.e. sequential and parallel
-   * ones) are built by filling the contents of an abstract object that is only
-   * referenced through a pointer of a type that is independent of the actual
-   * vector type, we can implement almost all functionality of vectors in this
-   * base class. Derived classes will then only have to provide the
-   * functionality to create one or the other kind of vector.
+   * Base class for all vector classes that are implemented on top of the
+   * PETSc vector types. Since in PETSc all vector types (i.e. sequential and
+   * parallel ones) are built by filling the contents of an abstract object
+   * that is only referenced through a pointer of a type that is independent
+   * of the actual vector type, we can implement almost all functionality of
+   * vectors in this base class. Derived classes will then only have to
+   * provide the functionality to create one or the other kind of vector.
    *
-   * The interface of this class is modeled after the existing Vector
-   * class in deal.II. It has almost the same member functions, and is often
+   * The interface of this class is modeled after the existing Vector class in
+   * deal.II. It has almost the same member functions, and is often
    * exchangable. However, since PETSc only supports a single scalar type
    * (either double, float, or a complex data type), it is not templated, and
-   * only works with whatever your PETSc installation has defined the data type
-   * @p PetscScalar to.
+   * only works with whatever your PETSc installation has defined the data
+   * type @p PetscScalar to.
    *
    * Note that PETSc only guarantees that operations do what you expect if the
    * functions @p VecAssemblyBegin and @p VecAssemblyEnd have been called
@@ -256,11 +226,9 @@ namespace PETScWrappers
   {
   public:
     /**
-     * Declare some of the standard types
-     * used in all containers. These types
-     * parallel those in the <tt>C++</tt>
-     * standard libraries <tt>vector<...></tt>
-     * class.
+     * Declare some of the standard types used in all containers. These types
+     * parallel those in the <tt>C++</tt> standard libraries
+     * <tt>vector<...></tt> class.
      */
     typedef PetscScalar               value_type;
     typedef PetscReal                 real_type;
@@ -269,24 +237,20 @@ namespace PETScWrappers
     typedef const internal::VectorReference const_reference;
 
     /**
-     * Default constructor. It doesn't do
-     * anything, derived classes will have
+     * Default constructor. It doesn't do anything, derived classes will have
      * to initialize the data.
      */
     VectorBase ();
 
     /**
-     * Copy constructor. Sets the dimension
-     * to that of the given vector, and
+     * Copy constructor. Sets the dimension to that of the given vector, and
      * copies all elements.
      */
     VectorBase (const VectorBase &v);
 
     /**
-     * Initialize a Vector from a PETSc Vec
-     * object. Note that we do not copy the
-     * vector and we do not attain
-     * ownership, so we do not destroy the
+     * Initialize a Vector from a PETSc Vec object. Note that we do not copy
+     * the vector and we do not attain ownership, so we do not destroy the
      * PETSc object in the destructor.
      */
     explicit VectorBase (const Vec &v);
@@ -297,16 +261,13 @@ namespace PETScWrappers
     virtual ~VectorBase ();
 
     /**
-     * Compress the underlying
-     * representation of the PETSc object,
-     * i.e. flush the buffers of the vector
-     * object if it has any. This function
-     * is necessary after writing into a
-     * vector element-by-element and before
+     * Compress the underlying representation of the PETSc object, i.e. flush
+     * the buffers of the vector object if it has any. This function is
+     * necessary after writing into a vector element-by-element and before
      * anything else can be done on it.
      *
-     * See @ref GlossCompress "Compressing distributed objects"
-     * for more information.
+     * See @ref GlossCompress "Compressing distributed objects" for more
+     * information.
      */
     void compress (::dealii::VectorOperation::values operation);
 
@@ -316,104 +277,75 @@ namespace PETScWrappers
     void compress () DEAL_II_DEPRECATED;
 
     /**
-     * Set all components of the vector to
-     * the given number @p s. Simply pass
-     * this down to the individual block
-     * objects, but we still need to declare
-     * this function to make the example
-     * given in the discussion about making
+     * Set all components of the vector to the given number @p s. Simply pass
+     * this down to the individual block objects, but we still need to declare
+     * this function to make the example given in the discussion about making
      * the constructor explicit work.
      *
      *
-     * Since the semantics of assigning a
-     * scalar to a vector are not
-     * immediately clear, this operator
-     * should really only be used if you
-     * want to set the entire vector to
-     * zero. This allows the intuitive
-     * notation <tt>v=0</tt>. Assigning
-     * other values is deprecated and may
-     * be disallowed in the future.
+     * Since the semantics of assigning a scalar to a vector are not
+     * immediately clear, this operator should really only be used if you want
+     * to set the entire vector to zero. This allows the intuitive notation
+     * <tt>v=0</tt>. Assigning other values is deprecated and may be
+     * disallowed in the future.
      */
     VectorBase &operator = (const PetscScalar s);
 
     /**
-     * Test for equality. This function
-     * assumes that the present vector and
-     * the one to compare with have the same
-     * size already, since comparing vectors
-     * of different sizes makes not much
-     * sense anyway.
+     * Test for equality. This function assumes that the present vector and
+     * the one to compare with have the same size already, since comparing
+     * vectors of different sizes makes not much sense anyway.
      */
     bool operator == (const VectorBase &v) const;
 
     /**
-     * Test for inequality. This function
-     * assumes that the present vector and
-     * the one to compare with have the same
-     * size already, since comparing vectors
-     * of different sizes makes not much
-     * sense anyway.
+     * Test for inequality. This function assumes that the present vector and
+     * the one to compare with have the same size already, since comparing
+     * vectors of different sizes makes not much sense anyway.
      */
     bool operator != (const VectorBase &v) const;
 
     /**
-     * Return the global dimension of the
-     * vector.
+     * Return the global dimension of the vector.
      */
     size_type size () const;
 
     /**
-     * Return the local dimension of the
-     * vector, i.e. the number of elements
-     * stored on the present MPI
-     * process. For sequential vectors,
-     * this number is the same as size(),
-     * but for parallel vectors it may be
-     * smaller.
+     * Return the local dimension of the vector, i.e. the number of elements
+     * stored on the present MPI process. For sequential vectors, this number
+     * is the same as size(), but for parallel vectors it may be smaller.
      *
-     * To figure out which elements
-     * exactly are stored locally,
-     * use local_range().
+     * To figure out which elements exactly are stored locally, use
+     * local_range().
      */
     size_type local_size () const;
 
     /**
-     * Return a pair of indices
-     * indicating which elements of
-     * this vector are stored
-     * locally. The first number is
-     * the index of the first
-     * element stored, the second
-     * the index of the one past
-     * the last one that is stored
-     * locally. If this is a
-     * sequential vector, then the
-     * result will be the pair
-     * (0,N), otherwise it will be
-     * a pair (i,i+n), where
+     * Return a pair of indices indicating which elements of this vector are
+     * stored locally. The first number is the index of the first element
+     * stored, the second the index of the one past the last one that is
+     * stored locally. If this is a sequential vector, then the result will be
+     * the pair (0,N), otherwise it will be a pair (i,i+n), where
      * <tt>n=local_size()</tt>.
      */
     std::pair<size_type, size_type>
     local_range () const;
 
     /**
-     * Return whether @p index is
-     * in the local range or not,
-     * see also local_range().
+     * Return whether @p index is in the local range or not, see also
+     * local_range().
      */
     bool in_local_range (const size_type index) const;
 
     /**
-     * Return an index set that describes which elements of this vector
-     * are owned by the current processor. Note that this index set does
-     * not include elements this vector may store locally as ghost
-     * elements but that are in fact owned by another processor.
-     * As a consequence, the index sets returned on different
-     * processors if this is a distributed vector will form disjoint
-     * sets that add up to the complete index set.
-     * Obviously, if a vector is created on only one processor, then
-     * the result would satisfy
+     * Return an index set that describes which elements of this vector are
+     * owned by the current processor. Note that this index set does not
+     * include elements this vector may store locally as ghost elements but
+     * that are in fact owned by another processor. As a consequence, the
+     * index sets returned on different processors if this is a distributed
+     * vector will form disjoint sets that add up to the complete index set.
+     * Obviously, if a vector is created on only one processor, then the
+     * result would satisfy
      * @code
      *   vec.locally_owned_elements() == complete_index_set (vec.size())
      * @endcode
@@ -421,30 +353,26 @@ namespace PETScWrappers
     IndexSet locally_owned_elements () const;
 
     /**
-     * Return if the vector contains ghost
-     * elements.
+     * Return if the vector contains ghost elements.
      *
      * @see @ref GlossGhostedVector "vectors with ghost elements"
      */
     bool has_ghost_elements() const;
 
     /**
-     * Provide access to a given element,
-     * both read and write.
+     * Provide access to a given element, both read and write.
      */
     reference
     operator () (const size_type index);
 
     /**
-     * Provide read-only access to an
-     * element.
+     * Provide read-only access to an element.
      */
     PetscScalar
     operator () (const size_type index) const;
 
     /**
-     * Provide access to a given
-     * element, both read and write.
+     * Provide access to a given element, both read and write.
      *
      * Exactly the same as operator().
      */
@@ -452,9 +380,8 @@ namespace PETScWrappers
     operator [] (const size_type index);
 
     /**
-     * Provide read-only access to an
-     * element. This is equivalent to
-     * the <code>el()</code> command.
+     * Provide read-only access to an element. This is equivalent to the
+     * <code>el()</code> command.
      *
      * Exactly the same as operator().
      */
@@ -462,34 +389,26 @@ namespace PETScWrappers
     operator [] (const size_type index) const;
 
     /**
-     * A collective set operation: instead
-     * of setting individual elements of a
-     * vector, this function allows to set
-     * a whole set of elements at once. The
-     * indices of the elements to be set
-     * are stated in the first argument,
-     * the corresponding values in the
-     * second.
+     * A collective set operation: instead of setting individual elements of a
+     * vector, this function allows to set a whole set of elements at once.
+     * The indices of the elements to be set are stated in the first argument,
+     * the corresponding values in the second.
      */
     void set (const std::vector<size_type>   &indices,
               const std::vector<PetscScalar>  &values);
 
     /**
-     * A collective get operation: instead
-     * of getting individual elements of a
-     * vector, this function allows to get
-     * a whole set of elements at once. The
-     * indices of the elements to be read
-     * are stated in the first argument,
-     * the corresponding values are returned in the
-     * second.
+     * A collective get operation: instead of getting individual elements of a
+     * vector, this function allows to get a whole set of elements at once.
+     * The indices of the elements to be read are stated in the first
+     * argument, the corresponding values are returned in the second.
      */
     void extract_subvector_to (const std::vector<size_type> &indices,
                                std::vector<PetscScalar> &values) const;
 
     /**
-     * Just as the above, but with pointers.
-     * Useful in minimizing copying of data around.
+     * Just as the above, but with pointers. Useful in minimizing copying of
+     * data around.
      */
     template <typename ForwardIterator, typename OutputIterator>
     void extract_subvector_to (const ForwardIterator    indices_begin,
@@ -497,40 +416,30 @@ namespace PETScWrappers
                                OutputIterator           values_begin) const;
 
     /**
-     * A collective add operation: This
-     * function adds a whole set of values
-     * stored in @p values to the vector
-     * components specified by @p indices.
+     * A collective add operation: This function adds a whole set of values
+     * stored in @p values to the vector components specified by @p indices.
      */
     void add (const std::vector<size_type> &indices,
               const std::vector<PetscScalar>  &values);
 
     /**
-     * This is a second collective
-     * add operation. As a
-     * difference, this function
-     * takes a deal.II vector of
-     * values.
+     * This is a second collective add operation. As a difference, this
+     * function takes a deal.II vector of values.
      */
     void add (const std::vector<size_type>        &indices,
               const ::dealii::Vector<PetscScalar> &values);
 
     /**
-     * Take an address where
-     * <tt>n_elements</tt> are stored
-     * contiguously and add them into
-     * the vector. Handles all cases
-     * which are not covered by the
-     * other two <tt>add()</tt>
-     * functions above.
+     * Take an address where <tt>n_elements</tt> are stored contiguously and
+     * add them into the vector. Handles all cases which are not covered by
+     * the other two <tt>add()</tt> functions above.
      */
     void add (const size_type    n_elements,
               const size_type   *indices,
               const PetscScalar  *values);
 
     /**
-     * Return the scalar product of two
-     * vectors. The vectors must have the
+     * Return the scalar product of two vectors. The vectors must have the
      * same size.
      */
     PetscScalar operator * (const VectorBase &vec) const;
@@ -546,29 +455,25 @@ namespace PETScWrappers
     PetscScalar mean_value () const;
 
     /**
-     * $l_1$-norm of the vector.
-     * The sum of the absolute values.
+     * $l_1$-norm of the vector. The sum of the absolute values.
      */
     real_type l1_norm () const;
 
     /**
-     * $l_2$-norm of the vector.  The
-     * square root of the sum of the
-     * squares of the elements.
+     * $l_2$-norm of the vector.  The square root of the sum of the squares of
+     * the elements.
      */
     real_type l2_norm () const;
 
     /**
-     * $l_p$-norm of the vector. The
-     * pth root of the sum of the pth
-     * powers of the absolute values
-     * of the elements.
+     * $l_p$-norm of the vector. The pth root of the sum of the pth powers of
+     * the absolute values of the elements.
      */
     real_type lp_norm (const real_type p) const;
 
     /**
-     * $l_\infty$-norm of the vector. Return the value of the vector
-     * element with the maximum absolute value.
+     * $l_\infty$-norm of the vector. Return the value of the vector element
+     * with the maximum absolute value.
      */
     real_type linfty_norm () const;
 
@@ -592,8 +497,8 @@ namespace PETScWrappers
                              const VectorBase &W);
 
     /**
-     * Normalize vector by dividing by the $l_2$-norm of the
-     * vector. Return the vector norm before normalization.
+     * Normalize vector by dividing by the $l_2$-norm of the vector. Return
+     * the vector norm before normalization.
      */
     real_type normalize () const;
 
@@ -618,111 +523,89 @@ namespace PETScWrappers
     VectorBase &conjugate ();
 
     /**
-     * A collective piecewise
-     * multiply operation on
-     * <code>this</code> vector
-     * with itself. TODO: The model
-     * for this function should be
-     * similer to add ().
+     * A collective piecewise multiply operation on <code>this</code> vector
+     * with itself. TODO: The model for this function should be similer to add
+     * ().
      */
     VectorBase &mult ();
 
     /**
-     * Same as above, but a
-     * collective piecewise
-     * multiply operation of
-     * <code>this</code> vector
-     * with <b>v</b>.
+     * Same as above, but a collective piecewise multiply operation of
+     * <code>this</code> vector with <b>v</b>.
      */
     VectorBase &mult (const VectorBase &v);
 
     /**
-     * Same as above, but a
-     * collective piecewise
-     * multiply operation of
+     * Same as above, but a collective piecewise multiply operation of
      * <b>u</b> with <b>v</b>.
      */
     VectorBase &mult (const VectorBase &u,
                       const VectorBase &v);
 
     /**
-     * Return whether the vector contains only elements with value
-     * zero. This is a collective operation. This function is expensive, because
+     * Return whether the vector contains only elements with value zero. This
+     * is a collective operation. This function is expensive, because
      * potentially all elements have to be checked.
      */
     bool all_zero () const;
 
     /**
-     * Return @p true if the vector has no
-     * negative entries, i.e. all entries
-     * are zero or positive. This function
-     * is used, for example, to check
-     * whether refinement indicators are
-     * really all positive (or zero).
+     * Return @p true if the vector has no negative entries, i.e. all entries
+     * are zero or positive. This function is used, for example, to check
+     * whether refinement indicators are really all positive (or zero).
      */
     bool is_non_negative () const;
 
     /**
-     * Multiply the entire vector by a
-     * fixed factor.
+     * Multiply the entire vector by a fixed factor.
      */
     VectorBase &operator *= (const PetscScalar factor);
 
     /**
-     * Divide the entire vector by a
-     * fixed factor.
+     * Divide the entire vector by a fixed factor.
      */
     VectorBase &operator /= (const PetscScalar factor);
 
     /**
-     * Add the given vector to the present
-     * one.
+     * Add the given vector to the present one.
      */
     VectorBase &operator += (const VectorBase &V);
 
     /**
-     * Subtract the given vector from the
-     * present one.
+     * Subtract the given vector from the present one.
      */
     VectorBase &operator -= (const VectorBase &V);
 
     /**
-     * Addition of @p s to all
-     * components. Note that @p s is a
-     * scalar and not a vector.
+     * Addition of @p s to all components. Note that @p s is a scalar and not
+     * a vector.
      */
     void add (const PetscScalar s);
 
     /**
-     * Simple vector addition, equal to the
-     * <tt>operator +=</tt>.
+     * Simple vector addition, equal to the <tt>operator +=</tt>.
      */
     void add (const VectorBase &V);
 
     /**
-     * Simple addition of a multiple of a
-     * vector, i.e. <tt>*this += a*V</tt>.
+     * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>.
      */
     void add (const PetscScalar a, const VectorBase &V);
 
     /**
-     * Multiple addition of scaled vectors,
-     * i.e. <tt>*this += a*V+b*W</tt>.
+     * Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>.
      */
     void add (const PetscScalar a, const VectorBase &V,
               const PetscScalar b, const VectorBase &W);
 
     /**
-     * Scaling and simple vector addition,
-     * i.e.
-     * <tt>*this = s*(*this)+V</tt>.
+     * Scaling and simple vector addition, i.e. <tt>*this = s*(*this)+V</tt>.
      */
     void sadd (const PetscScalar s,
                const VectorBase     &V);
 
     /**
-     * Scaling and simple addition, i.e.
-     * <tt>*this = s*(*this)+a*V</tt>.
+     * Scaling and simple addition, i.e. <tt>*this = s*(*this)+a*V</tt>.
      */
     void sadd (const PetscScalar s,
                const PetscScalar a,
@@ -738,8 +621,8 @@ namespace PETScWrappers
                const VectorBase     &W);
 
     /**
-     * Scaling and multiple addition.
-     * <tt>*this = s*(*this)+a*V + b*W + c*X</tt>.
+     * Scaling and multiple addition. <tt>*this = s*(*this)+a*V + b*W +
+     * c*X</tt>.
      */
     void sadd (const PetscScalar s,
                const PetscScalar a,
@@ -750,13 +633,9 @@ namespace PETScWrappers
                const VectorBase     &X);
 
     /**
-     * Scale each element of this
-     * vector by the corresponding
-     * element in the argument. This
-     * function is mostly meant to
-     * simulate multiplication (and
-     * immediate re-assignment) by a
-     * diagonal scaling matrix.
+     * Scale each element of this vector by the corresponding element in the
+     * argument. This function is mostly meant to simulate multiplication (and
+     * immediate re-assignment) by a diagonal scaling matrix.
      */
     void scale (const VectorBase &scaling_factors);
 
@@ -772,58 +651,43 @@ namespace PETScWrappers
               const PetscScalar b, const VectorBase &W);
 
     /**
-     * Compute the elementwise ratio of the
-     * two given vectors, that is let
-     * <tt>this[i] = a[i]/b[i]</tt>. This is
-     * useful for example if you want to
-     * compute the cellwise ratio of true to
-     * estimated error.
+     * Compute the elementwise ratio of the two given vectors, that is let
+     * <tt>this[i] = a[i]/b[i]</tt>. This is useful for example if you want to
+     * compute the cellwise ratio of true to estimated error.
      *
-     * This vector is appropriately
-     * scaled to hold the result.
+     * This vector is appropriately scaled to hold the result.
      *
-     * If any of the <tt>b[i]</tt> is
-     * zero, the result is
-     * undefined. No attempt is made
-     * to catch such situations.
+     * If any of the <tt>b[i]</tt> is zero, the result is undefined. No
+     * attempt is made to catch such situations.
      */
     void ratio (const VectorBase &a,
                 const VectorBase &b);
 
     /**
-     * Updates the ghost values of this
-     * vector. As ghosted vectors are now read-only and assignments
-     * from a non-ghosted vector update the ghost values automatically,
-     * this method does not need to be called in user code.
+     * Updates the ghost values of this vector. As ghosted vectors are now
+     * read-only and assignments from a non-ghosted vector update the ghost
+     * values automatically, this method does not need to be called in user
+     * code.
      * @deprecated: calling this method is no longer necessary.
      */
     void update_ghost_values() const DEAL_II_DEPRECATED;
 
 
     /**
-     * Prints the PETSc vector object values
-     * using PETSc internal vector viewer function
-     * <tt>VecView</tt>. The default format prints
-     * the vector's contents, including indices of
-     * vector elements. For other valid view formats,
-     * consult
-     * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecView.html
+     * Prints the PETSc vector object values using PETSc internal vector
+     * viewer function <tt>VecView</tt>. The default format prints the
+     * vector's contents, including indices of vector elements. For other
+     * valid view formats, consult http://www.mcs.anl.gov/petsc/petsc-
+     * current/docs/manualpages/Vec/VecView.html
      */
     void write_ascii (const PetscViewerFormat format = PETSC_VIEWER_DEFAULT) ;
 
     /**
-     * Print to a
-     * stream. @p precision denotes
-     * the desired precision with
-     * which values shall be printed,
-     * @p scientific whether
-     * scientific notation shall be
-     * used. If @p across is
-     * @p true then the vector is
-     * printed in a line, while if
-     * @p false then the elements
-     * are printed on a separate line
-     * each.
+     * Print to a stream. @p precision denotes the desired precision with
+     * which values shall be printed, @p scientific whether scientific
+     * notation shall be used. If @p across is @p true then the vector is
+     * printed in a line, while if @p false then the elements are printed on a
+     * separate line each.
      */
     void print (std::ostream       &out,
                 const unsigned int  precision  = 3,
@@ -831,90 +695,64 @@ namespace PETScWrappers
                 const bool          across     = true) const;
 
     /**
-     * Swap the contents of this
-     * vector and the other vector
-     * @p v. One could do this
-     * operation with a temporary
-     * variable and copying over the
-     * data elements, but this
-     * function is significantly more
-     * efficient since it only swaps
-     * the pointers to the data of
-     * the two vectors and therefore
-     * does not need to allocate
-     * temporary storage and move
-     * data around.
+     * Swap the contents of this vector and the other vector @p v. One could
+     * do this operation with a temporary variable and copying over the data
+     * elements, but this function is significantly more efficient since it
+     * only swaps the pointers to the data of the two vectors and therefore
+     * does not need to allocate temporary storage and move data around.
      *
-     * This function is analog to the
-     * the @p swap function of all C++
-     * standard containers. Also,
-     * there is a global function
-     * <tt>swap(u,v)</tt> that simply calls
-     * <tt>u.swap(v)</tt>, again in analogy
-     * to standard functions.
+     * This function is analog to the the @p swap function of all C++ standard
+     * containers. Also, there is a global function <tt>swap(u,v)</tt> that
+     * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
+     * functions.
      */
     void swap (VectorBase &v);
 
     /**
-     * Conversion operator to gain access
-     * to the underlying PETSc type. If you
-     * do this, you cut this class off some
-     * information it may need, so this
-     * conversion operator should only be
-     * used if you know what you do. In
-     * particular, it should only be used
-     * for read-only operations into the
+     * Conversion operator to gain access to the underlying PETSc type. If you
+     * do this, you cut this class off some information it may need, so this
+     * conversion operator should only be used if you know what you do. In
+     * particular, it should only be used for read-only operations into the
      * vector.
      */
     operator const Vec &() const;
 
     /**
-     * Estimate for the memory
-     * consumption (not implemented
-     * for this class).
+     * Estimate for the memory consumption (not implemented for this class).
      */
     std::size_t memory_consumption () const;
 
     /**
-     * Return a reference to the MPI
-     * communicator object in use with this
+     * Return a reference to the MPI communicator object in use with this
      * object.
      */
     virtual const MPI_Comm &get_mpi_communicator () const;
 
   protected:
     /**
-     * A generic vector object in
-     * PETSc. The actual type, a sequential
-     * vector, is set in the constructor.
+     * A generic vector object in PETSc. The actual type, a sequential vector,
+     * is set in the constructor.
      */
     Vec vector;
 
     /**
-     * Denotes if this vector has ghost
-     * indices associated with it. This
-     * means that at least one of the
-     * processes in a parallel programm has
-     * at least one ghost index.
+     * Denotes if this vector has ghost indices associated with it. This means
+     * that at least one of the processes in a parallel programm has at least
+     * one ghost index.
      */
     bool ghosted;
 
     /**
-     * This vector contains the global
-     * indices of the ghost values. The
-     * location in this vector denotes the
-     * local numbering, which is used in
+     * This vector contains the global indices of the ghost values. The
+     * location in this vector denotes the local numbering, which is used in
      * PETSc.
      */
     IndexSet ghost_indices;
 
     /**
-     * Store whether the last action was a
-     * write or add operation. This
-     * variable is @p mutable so that the
-     * accessor classes can write to it,
-     * even though the vector object they
-     * refer to is constant.
+     * Store whether the last action was a write or add operation. This
+     * variable is @p mutable so that the accessor classes can write to it,
+     * even though the vector object they refer to is constant.
      */
     mutable ::dealii::VectorOperation::values last_action;
 
@@ -924,20 +762,15 @@ namespace PETScWrappers
     friend class internal::VectorReference;
 
     /**
-     * Specifies if the vector is the owner
-     * of the PETSc Vec. This is true if it
-     * got created by this class and
-     * determines if it gets destructed in
+     * Specifies if the vector is the owner of the PETSc Vec. This is true if
+     * it got created by this class and determines if it gets destructed in
      * the destructor.
      */
     bool attained_ownership;
 
     /**
-     * Collective set or add
-     * operation: This function is
-     * invoked by the collective @p
-     * set and @p add with the
-     * @p add_values flag set to the
+     * Collective set or add operation: This function is invoked by the
+     * collective @p set and @p add with the @p add_values flag set to the
      * corresponding value.
      */
     void do_set_add_operation (const size_type    n_elements,
@@ -953,9 +786,9 @@ namespace PETScWrappers
 // ------------------- inline and template functions --------------
 
   /**
-   * Global function @p swap which overloads the default implementation
-   * of the C++ standard library which uses a temporary object. The
-   * function simply exchanges the data of the two vectors.
+   * Global function @p swap which overloads the default implementation of the
+   * C++ standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates PETScWrappers::VectorBase
    * @author Wolfgang Bangerth, 2004
index 31501b12ee222781acc2f4bf847529186a658a29..a3e38f66b9cdca4d544a613e429a78ce731d6727 100644 (file)
@@ -41,10 +41,10 @@ template <typename number> class TridiagonalMatrix;
  */
 
 /**
- * Abstract class for use in iterations.  This class provides the
- * interface required by LAC solver classes. It allows to use
- * different concrete matrix classes in the same context, as long as
- * they apply to the same vector class.
+ * Abstract class for use in iterations.  This class provides the interface
+ * required by LAC solver classes. It allows to use different concrete matrix
+ * classes in the same context, as long as they apply to the same vector
+ * class.
  *
  * @author Guido Kanschat, 2000, 2001, 2002
  */
@@ -53,26 +53,19 @@ class PointerMatrixBase : public Subscriptor
 {
 public:
   /**
-   * Value type of this
-   * matrix. since the matrix
-   * itself is unknown, we take the
-   * value type of the
-   * vector. Therefore, matrix
-   * entries must be convertible to
-   * vector entries.
+   * Value type of this matrix. since the matrix itself is unknown, we take
+   * the value type of the vector. Therefore, matrix entries must be
+   * convertible to vector entries.
    *
-   * This was defined to make this
-   * matrix a possible template
-   * argument to
+   * This was defined to make this matrix a possible template argument to
    * BlockMatrixArray.
    */
   typedef typename VECTOR::value_type value_type;
 
   /**
-   * Virtual destructor.  Does
-   * nothing except making sure that
-   * the destructor of any derived
-   * class is called whenever a pointer-to-base-class object is destroyed.
+   * Virtual destructor.  Does nothing except making sure that the destructor
+   * of any derived class is called whenever a pointer-to-base-class object is
+   * destroyed.
    */
   virtual ~PointerMatrixBase ();
 
@@ -94,15 +87,13 @@ public:
                        const VECTOR &src) const = 0;
 
   /**
-   * Matrix-vector product, adding to
-   * <tt>dst</tt>.
+   * Matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void vmult_add (VECTOR &dst,
                           const VECTOR &src) const = 0;
 
   /**
-   * Transposed matrix-vector product,
-   * adding to <tt>dst</tt>.
+   * Transposed matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
                            const VECTOR &src) const = 0;
@@ -110,12 +101,12 @@ public:
 
 
 /**
- * A pointer to be used as a matrix.  This class stores a pointer to a
- * matrix and can be used as a matrix itself in iterative methods.
+ * A pointer to be used as a matrix.  This class stores a pointer to a matrix
+ * and can be used as a matrix itself in iterative methods.
  *
- * The main purpose for the existence of this class is its base class,
- * which only has a vector as template argument. Therefore, this
- * interface provides an abstract base class for matrices.
+ * The main purpose for the existence of this class is its base class, which
+ * only has a vector as template argument. Therefore, this interface provides
+ * an abstract base class for matrices.
  *
  * @author Guido Kanschat 2000, 2001, 2002
  */
@@ -124,14 +115,11 @@ class PointerMatrix : public PointerMatrixBase<VECTOR>
 {
 public:
   /**
-   * Constructor.  The pointer in the
-   * argument is stored in this
-   * class. As usual, the lifetime of
-   * <tt>*M</tt> must be longer than the
-   * one of the PointerMatrix.
+   * Constructor.  The pointer in the argument is stored in this class. As
+   * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+   * PointerMatrix.
    *
-   * If <tt>M</tt> is zero, no
-   * matrix is stored.
+   * If <tt>M</tt> is zero, no matrix is stored.
    */
   PointerMatrix (const MATRIX *M=0);
 
@@ -139,28 +127,24 @@ public:
    * Constructor.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrix(const char *name);
 
   /**
-   * Constructor. <tt>M</tt> points
-   * to a matrix which must live
-   * longer than the
-   * PointerMatrix.
+   * Constructor. <tt>M</tt> points to a matrix which must live longer than
+   * the PointerMatrix.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrix(const MATRIX *M,
                 const char *name);
@@ -169,16 +153,13 @@ public:
   virtual void clear();
 
   /**
-   * Return whether the object is
-   * empty.
+   * Return whether the object is empty.
    */
   bool empty () const;
 
   /**
-   * Assign a new matrix
-   * pointer. Deletes the old pointer
-   * and releases its matrix.
-   * @see SmartPointer
+   * Assign a new matrix pointer. Deletes the old pointer and releases its
+   * matrix. @see SmartPointer
    */
   const PointerMatrix &operator= (const MATRIX *M);
 
@@ -195,15 +176,13 @@ public:
                        const VECTOR &src) const;
 
   /**
-   * Matrix-vector product, adding to
-   * <tt>dst</tt>.
+   * Matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void vmult_add (VECTOR &dst,
                           const VECTOR &src) const;
 
   /**
-   * Transposed matrix-vector product,
-   * adding to <tt>dst</tt>.
+   * Transposed matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
                            const VECTOR &src) const;
@@ -217,17 +196,16 @@ private:
 
 
 /**
- * A pointer to be used as a matrix.  This class stores a pointer to a
- * matrix and can be used as a matrix itself in iterative methods.
+ * A pointer to be used as a matrix.  This class stores a pointer to a matrix
+ * and can be used as a matrix itself in iterative methods.
  *
- * The main purpose for the existence of this class is its base class,
- * which only has a vector as template argument. Therefore, this
- * interface provides an abstract base class for matrices.
+ * The main purpose for the existence of this class is its base class, which
+ * only has a vector as template argument. Therefore, this interface provides
+ * an abstract base class for matrices.
  *
- * This class differs form PointerMatrix by its additional
- * VectorMemory object and by the fact that it implements the
- * functions vmult_add() and Tvmult_add() only using vmult() and
- * Tvmult() of the MATRIX.
+ * This class differs form PointerMatrix by its additional VectorMemory object
+ * and by the fact that it implements the functions vmult_add() and
+ * Tvmult_add() only using vmult() and Tvmult() of the MATRIX.
  *
  * @author Guido Kanschat 2006
  */
@@ -236,50 +214,40 @@ class PointerMatrixAux : public PointerMatrixBase<VECTOR>
 {
 public:
   /**
-   * Constructor.  The pointer in the
-   * argument is stored in this
-   * class. As usual, the lifetime of
-   * <tt>*M</tt> must be longer than the
-   * one of the PointerMatrixAux.
+   * Constructor.  The pointer in the argument is stored in this class. As
+   * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+   * PointerMatrixAux.
    *
-   * If <tt>M</tt> is zero, no
-   * matrix is stored.
+   * If <tt>M</tt> is zero, no matrix is stored.
    *
-   * If <tt>mem</tt> is zero, then
-   * GrowingVectorMemory
-   * is used.
+   * If <tt>mem</tt> is zero, then GrowingVectorMemory is used.
    */
   PointerMatrixAux (VectorMemory<VECTOR> *mem = 0,
                     const MATRIX *M=0);
 
   /**
-   * Constructor not using a
-   * matrix.
+   * Constructor not using a matrix.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrixAux(VectorMemory<VECTOR> *mem,
                    const char *name);
 
   /**
-   * Constructor. <tt>M</tt> points
-   * to a matrix which must live
-   * longer than the
-   * PointerMatrixAux.
+   * Constructor. <tt>M</tt> points to a matrix which must live longer than
+   * the PointerMatrixAux.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrixAux(VectorMemory<VECTOR> *mem,
                    const MATRIX *M,
@@ -289,23 +257,18 @@ public:
   virtual void clear();
 
   /**
-   * Return whether the object is
-   * empty.
+   * Return whether the object is empty.
    */
   bool empty () const;
 
   /**
-   * Assign a new VectorMemory
-   * object for getting auxiliary
-   * vectors.
+   * Assign a new VectorMemory object for getting auxiliary vectors.
    */
   void set_memory(VectorMemory<VECTOR> *mem);
 
   /**
-   * Assign a new matrix
-   * pointer. Deletes the old pointer
-   * and releases its matrix.
-   * @see SmartPointer
+   * Assign a new matrix pointer. Deletes the old pointer and releases its
+   * matrix. @see SmartPointer
    */
   const PointerMatrixAux &operator= (const MATRIX *M);
 
@@ -322,15 +285,13 @@ public:
                        const VECTOR &src) const;
 
   /**
-   * Matrix-vector product, adding to
-   * <tt>dst</tt>.
+   * Matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void vmult_add (VECTOR &dst,
                           const VECTOR &src) const;
 
   /**
-   * Transposed matrix-vector product,
-   * adding to <tt>dst</tt>.
+   * Transposed matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
                            const VECTOR &src) const;
@@ -342,8 +303,7 @@ private:
   mutable GrowingVectorMemory<VECTOR> my_memory;
 
   /**
-   * Object for getting the
-   * auxiliary vector.
+   * Object for getting the auxiliary vector.
    */
   mutable SmartPointer<VectorMemory<VECTOR>,PointerMatrixAux<MATRIX,VECTOR> > mem;
 
@@ -356,13 +316,12 @@ private:
 
 
 /**
- * Implement matrix multiplications for a vector using the
- * PointerMatrixBase functionality. Objects of this
- * class can be used in block matrices.
+ * Implement matrix multiplications for a vector using the PointerMatrixBase
+ * functionality. Objects of this class can be used in block matrices.
  *
- * Implements a matrix with image dimension 1 by using the scalar
- * product (#vmult()) and scalar multiplication (#Tvmult()) functions
- * of the Vector class.
+ * Implements a matrix with image dimension 1 by using the scalar product
+ * (#vmult()) and scalar multiplication (#Tvmult()) functions of the Vector
+ * class.
  *
  * @author Guido Kanschat, 2006
  */
@@ -371,14 +330,11 @@ class PointerMatrixVector : public PointerMatrixBase<Vector<number> >
 {
 public:
   /**
-   * Constructor.  The pointer in the
-   * argument is stored in this
-   * class. As usual, the lifetime of
-   * <tt>*M</tt> must be longer than the
-   * one of the PointerMatrix.
+   * Constructor.  The pointer in the argument is stored in this class. As
+   * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+   * PointerMatrix.
    *
-   * If <tt>M</tt> is zero, no
-   * matrix is stored.
+   * If <tt>M</tt> is zero, no matrix is stored.
    */
   PointerMatrixVector (const Vector<number> *M=0);
 
@@ -386,28 +342,24 @@ public:
    * Constructor.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrixVector (const char *name);
 
   /**
-   * Constructor. <tt>M</tt> points
-   * to a matrix which must live
-   * longer than the
-   * PointerMatrix.
+   * Constructor. <tt>M</tt> points to a matrix which must live longer than
+   * the PointerMatrix.
    *
    * This class internally stores a pointer to a matrix via a SmartPointer
-   * object. The SmartPointer class allows to associate a name with the
-   * object pointed to that identifies the object that has the pointer,
-   * in order to identify objects that still refer to the object pointed to.
-   * The @p name argument to this function
-   * is used to this end, i.e., you can in essence assign a name to
-   * the current PointerMatrix object.
+   * object. The SmartPointer class allows to associate a name with the object
+   * pointed to that identifies the object that has the pointer, in order to
+   * identify objects that still refer to the object pointed to. The @p name
+   * argument to this function is used to this end, i.e., you can in essence
+   * assign a name to the current PointerMatrix object.
    */
   PointerMatrixVector (const Vector<number> *M,
                        const char *name);
@@ -416,72 +368,50 @@ public:
   virtual void clear();
 
   /**
-   * Return whether the object is
-   * empty.
+   * Return whether the object is empty.
    */
   bool empty () const;
 
   /**
-   * Assign a new matrix
-   * pointer. Deletes the old pointer
-   * and releases its matrix.
-   * @see SmartPointer
+   * Assign a new matrix pointer. Deletes the old pointer and releases its
+   * matrix. @see SmartPointer
    */
   const PointerMatrixVector &operator= (const Vector<number> *M);
 
   /**
-   * Matrix-vector product,
-   * actually the scalar product of
-   * <tt>src</tt> and the vector
-   * representing this matrix.
+   * Matrix-vector product, actually the scalar product of <tt>src</tt> and
+   * the vector representing this matrix.
    *
-   * The dimension of <tt>dst</tt>
-   * is 1, while that of
-   * <tt>src</tt> is the size of
-   * the vector representing this
-   * matrix.
+   * The dimension of <tt>dst</tt> is 1, while that of <tt>src</tt> is the
+   * size of the vector representing this matrix.
    */
   virtual void vmult (Vector<number> &dst,
                       const Vector<number> &src) const;
 
   /**
-   * Transposed matrix-vector
-   * product, actually the
-   * multiplication of the vector
-   * representing this matrix with
-   * <tt>src(0)</tt>.
+   * Transposed matrix-vector product, actually the multiplication of the
+   * vector representing this matrix with <tt>src(0)</tt>.
    *
-   * The dimension of <tt>drc</tt>
-   * is 1, while that of
-   * <tt>dst</tt> is the size of
-   * the vector representing this
-   * matrix.
+   * The dimension of <tt>drc</tt> is 1, while that of <tt>dst</tt> is the
+   * size of the vector representing this matrix.
    */
   virtual void Tvmult (Vector<number> &dst,
                        const Vector<number> &src) const;
 
   /**
-   * Matrix-vector product, adding to
-   * <tt>dst</tt>.
+   * Matrix-vector product, adding to <tt>dst</tt>.
    *
-   * The dimension of <tt>dst</tt>
-   * is 1, while that of
-   * <tt>src</tt> is the size of
-   * the vector representing this
-   * matrix.
+   * The dimension of <tt>dst</tt> is 1, while that of <tt>src</tt> is the
+   * size of the vector representing this matrix.
    */
   virtual void vmult_add (Vector<number> &dst,
                           const Vector<number> &src) const;
 
   /**
-   * Transposed matrix-vector product,
-   * adding to <tt>dst</tt>.
+   * Transposed matrix-vector product, adding to <tt>dst</tt>.
    *
-   * The dimension of <tt>src</tt>
-   * is 1, while that of
-   * <tt>dst</tt> is the size of
-   * the vector representing this
-   * matrix.
+   * The dimension of <tt>src</tt> is 1, while that of <tt>dst</tt> is the
+   * size of the vector representing this matrix.
    */
   virtual void Tvmult_add (Vector<number> &dst,
                            const Vector<number> &src) const;
@@ -496,23 +426,21 @@ private:
 
 
 /**
- * This function helps you creating a PointerMatrixBase object if you
- * do not want to provide the full template arguments of
- * PointerMatrix or PointerMatrixAux.
+ * This function helps you creating a PointerMatrixBase object if you do not
+ * want to provide the full template arguments of PointerMatrix or
+ * PointerMatrixAux.
  *
- * Note that this function by default creates a PointerMatrixAux,
- * emulating the functions <tt>vmult_add</tt> and <tt>Tvmult_add</tt>,
- * using an auxiliary vector. It is overloaded for the library matrix
- * classes implementing these functions themselves. If you have such a
- * class, you should overload the function in order to save memory and
- * time.
+ * Note that this function by default creates a PointerMatrixAux, emulating
+ * the functions <tt>vmult_add</tt> and <tt>Tvmult_add</tt>, using an
+ * auxiliary vector. It is overloaded for the library matrix classes
+ * implementing these functions themselves. If you have such a class, you
+ * should overload the function in order to save memory and time.
  *
  * The result is a PointerMatrixBase* pointing to <tt>matrix</tt>. The
- * <TT>VECTOR</tt> argument is a dummy just used to determine the
- * template arguments.
+ * <TT>VECTOR</tt> argument is a dummy just used to determine the template
+ * arguments.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrixAux
+ * @relates PointerMatrixBase @relates PointerMatrixAux
  */
 template <class VECTOR, class MATRIX>
 inline
@@ -525,8 +453,7 @@ new_pointer_matrix_base(MATRIX &matrix, const VECTOR &, const char *name = "Poin
 /**
  * Specialized version for IdentityMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv>
 PointerMatrixBase<Vector<numberv> > *
@@ -539,8 +466,7 @@ new_pointer_matrix_base(const IdentityMatrix &matrix, const Vector<numberv> &, c
 /**
  * Specialized version for FullMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<Vector<numberv> > *
@@ -553,8 +479,7 @@ new_pointer_matrix_base(const FullMatrix<numberm> &matrix, const Vector<numberv>
 /**
  * Specialized version for LAPACKFullMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<Vector<numberv> > *
@@ -567,8 +492,7 @@ new_pointer_matrix_base(const LAPACKFullMatrix<numberm> &matrix, const Vector<nu
 /**
  * Specialized version for SparseMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<Vector<numberv> > *
@@ -581,8 +505,7 @@ new_pointer_matrix_base(const SparseMatrix<numberm> &matrix, const Vector<number
 /**
  * Specialized version for BlockSparseMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <class VECTOR, typename numberm>
 PointerMatrixBase<VECTOR> *
@@ -595,8 +518,7 @@ new_pointer_matrix_base(const BlockSparseMatrix<numberm> &matrix, const VECTOR &
 /**
  * Specialized version for SparseMatrixEZ.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<Vector<numberv> > *
@@ -609,8 +531,7 @@ new_pointer_matrix_base(const SparseMatrixEZ<numberm> &matrix, const Vector<numb
 /**
  * Specialized version for BlockSparseMatrixEZ.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <class VECTOR, typename numberm>
 PointerMatrixBase<VECTOR> *
@@ -623,8 +544,7 @@ new_pointer_matrix_base(const BlockSparseMatrixEZ<numberm> &matrix, const VECTOR
 /**
  * Specialized version for BlockMatrixArray.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<BlockVector<numberv> > *
@@ -637,8 +557,7 @@ new_pointer_matrix_base(const BlockMatrixArray<numberm> &matrix, const BlockVect
 /**
  * Specialized version for TridiagonalMatrix.
  *
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
  */
 template <typename numberv, typename numberm>
 PointerMatrixBase<Vector<numberv> > *
index 990f893fc7ca1e61d8f531eec37b19b7aab18174..9f665aa88c76c586a3325e9d21713d2d9b66bccd 100644 (file)
@@ -49,23 +49,22 @@ namespace parallel
 
 
 /**
- * No preconditioning.  This class helps you, if you want to use a
- * linear solver without preconditioning. All solvers in LAC require a
- * preconditioner. Therefore, you must use the identity provided here
- * to avoid preconditioning. It can be used in the following way:
+ * No preconditioning.  This class helps you, if you want to use a linear
+ * solver without preconditioning. All solvers in LAC require a
+ * preconditioner. Therefore, you must use the identity provided here to avoid
+ * preconditioning. It can be used in the following way:
  *
- @code
-  SolverControl           solver_control (1000, 1e-12);
-  SolverCG<>              cg (solver_control);
-  cg.solve (system_matrix, solution, system_rhs,
           PreconditionIdentity());
- @endcode
@code
* SolverControl           solver_control (1000, 1e-12);
* SolverCG<>              cg (solver_control);
* cg.solve (system_matrix, solution, system_rhs,
*          PreconditionIdentity());
@endcode
  *
- * See the step-3 tutorial program for an example and
- * additional explanations.
+ * See the step-3 tutorial program for an example and additional explanations.
  *
- * Alternatively, the IdentityMatrix class can be used to precondition
- * in this way.
+ * Alternatively, the IdentityMatrix class can be used to precondition in this
+ * way.
  *
  * @author Guido Kanschat, 1999
  */
@@ -128,14 +127,14 @@ public:
 
 
 /**
- * Preconditioning with Richardson's method. This preconditioner just
- * scales the vector with a constant relaxation factor provided by the
- * AdditionalData object.
+ * Preconditioning with Richardson's method. This preconditioner just scales
+ * the vector with a constant relaxation factor provided by the AdditionalData
+ * object.
  *
- * In Krylov-space methods, this preconditioner should not have any
- * effect. Using SolverRichardson, the two relaxation parameters will
- * be just multiplied. Still, this class is useful in multigrid
- * smoother objects (MGSmootherRelaxation).
+ * In Krylov-space methods, this preconditioner should not have any effect.
+ * Using SolverRichardson, the two relaxation parameters will be just
+ * multiplied. Still, this class is useful in multigrid smoother objects
+ * (MGSmootherRelaxation).
  *
  * @author Guido Kanschat, 2005
  */
@@ -223,15 +222,15 @@ private:
  * Preconditioner using a matrix-builtin function.  This class forms a
  * preconditioner suitable for the LAC solver classes. Since many
  * preconditioning methods are based on matrix entries, these have to be
- * implemented as member functions of the underlying matrix
- * implementation. This class now is intended to allow easy access to these
- * member functions from LAC solver classes.
+ * implemented as member functions of the underlying matrix implementation.
+ * This class now is intended to allow easy access to these member functions
+ * from LAC solver classes.
  *
- * It seems that all builtin preconditioners have a relaxation
- * parameter, so please use PreconditionRelaxation for these.
+ * It seems that all builtin preconditioners have a relaxation parameter, so
+ * please use PreconditionRelaxation for these.
  *
- * You will usually not want to create a named object of this type,
- * although possible. The most common use is like this:
+ * You will usually not want to create a named object of this type, although
+ * possible. The most common use is like this:
  * @code
  *    SolverGMRES<SparseMatrix<double>,
  *                Vector<double> >      gmres(control,memory,500);
@@ -240,16 +239,16 @@ private:
  *                 PreconditionUseMatrix<SparseMatrix<double>,Vector<double> >
  *                 (matrix,&SparseMatrix<double>::template precondition_Jacobi<double>));
  * @endcode
- * This creates an unnamed object to be passed as the fourth parameter to
- * the solver function of the SolverGMRES class. It assumes that the
- * SparseMatrix class has a function <tt>precondition_Jacobi</tt> taking two
- * vectors (source and destination) as parameters (Actually, there is no
- * function like that, the existing function takes a third parameter,
- * denoting the relaxation parameter; this example is therefore only meant to
- * illustrate the general idea).
+ * This creates an unnamed object to be passed as the fourth parameter to the
+ * solver function of the SolverGMRES class. It assumes that the SparseMatrix
+ * class has a function <tt>precondition_Jacobi</tt> taking two vectors
+ * (source and destination) as parameters (Actually, there is no function like
+ * that, the existing function takes a third parameter, denoting the
+ * relaxation parameter; this example is therefore only meant to illustrate
+ * the general idea).
  *
- * Note that due to the default template parameters, the above example
- * could be written shorter as follows:
+ * Note that due to the default template parameters, the above example could
+ * be written shorter as follows:
  * @code
  *    ...
  *    gmres.solve (matrix, solution, right_hand_side,
@@ -298,9 +297,9 @@ private:
 
 
 /**
- * Base class for other preconditioners.
- * Here, only some common features Jacobi, SOR and SSOR preconditioners
- * are implemented. For preconditioning, refer to derived classes.
+ * Base class for other preconditioners. Here, only some common features
+ * Jacobi, SOR and SSOR preconditioners are implemented. For preconditioning,
+ * refer to derived classes.
  *
  * @author Guido Kanschat, 2000
  */
@@ -353,9 +352,9 @@ protected:
 
 
 /**
- * Jacobi preconditioner using matrix built-in function.  The
- * <tt>MATRIX</tt> class used is required to have a function
- * <tt>precondition_Jacobi(VECTOR&, const VECTOR&, double</tt>)
+ * Jacobi preconditioner using matrix built-in function.  The <tt>MATRIX</tt>
+ * class used is required to have a function <tt>precondition_Jacobi(VECTOR&,
+ * const VECTOR&, double</tt>)
  *
  * @code
  *     // Declare related objects
@@ -412,25 +411,23 @@ public:
  * SOR preconditioner using matrix built-in function.
  *
  * Assuming the matrix <i>A = D + L + U</i> is split into its diagonal
- * <i>D</i> as well as the strict lower and upper triangles <i>L</i>
- * and <i>U</i>, then the SOR preconditioner with relaxation parameter
- * <i>r</i> is
+ * <i>D</i> as well as the strict lower and upper triangles <i>L</i> and
+ * <i>U</i>, then the SOR preconditioner with relaxation parameter <i>r</i> is
  * @f[
  *  P^{-1} = r (D+rL)^{-1}.
  * @f]
- * It is this operator <i>P<sup>-1</sup></i>, which is implemented by
- * vmult() through forward substitution. Analogously, Tvmult()
- * implements the operation of <i>r(D+rU)<sup>-1</sup></i>.
+ * It is this operator <i>P<sup>-1</sup></i>, which is implemented by vmult()
+ * through forward substitution. Analogously, Tvmult() implements the
+ * operation of <i>r(D+rU)<sup>-1</sup></i>.
  *
  * The SOR iteration itself can be directly written as
  * @f[
  *  x^{k+1} = x^k - r D^{-1} \bigl(L x^{k+1} + U x^k - b\bigr).
  * @f]
- * Using the right hand side <i>b</i> and the previous iterate
- * <i>x</i>, this is the operation implemented by step().
+ * Using the right hand side <i>b</i> and the previous iterate <i>x</i>, this
+ * is the operation implemented by step().
  *
- * The MATRIX
- * class used is required to have functions
+ * The MATRIX class used is required to have functions
  * <tt>precondition_SOR(VECTOR&, const VECTOR&, double)</tt> and
  * <tt>precondition_TSOR(VECTOR&, const VECTOR&, double)</tt>.
  *
@@ -486,9 +483,9 @@ public:
 
 
 /**
- * SSOR preconditioner using matrix built-in function.  The
- * <tt>MATRIX</tt> class used is required to have a function
- * <tt>precondition_SSOR(VECTOR&, const VECTOR&, double)</tt>
+ * SSOR preconditioner using matrix built-in function.  The <tt>MATRIX</tt>
+ * class used is required to have a function <tt>precondition_SSOR(VECTOR&,
+ * const VECTOR&, double)</tt>
  *
  * @code
  *     // Declare related objects
@@ -570,9 +567,9 @@ private:
 
 /**
  * Permuted SOR preconditioner using matrix built-in function.  The
- * <tt>MATRIX</tt> class used is required to have functions
- * <tt>PSOR(VECTOR&, const VECTOR&, double)</tt> and
- * <tt>TPSOR(VECTOR&, const VECTOR&, double)</tt>.
+ * <tt>MATRIX</tt> class used is required to have functions <tt>PSOR(VECTOR&,
+ * const VECTOR&, double)</tt> and <tt>TPSOR(VECTOR&, const VECTOR&,
+ * double)</tt>.
  *
  * @code
  *     // Declare related objects
@@ -650,25 +647,22 @@ private:
 
 
 /**
- * @deprecated This class has been superseded by IterativeInverse,
- * which is more flexible and easier to use.
+ * @deprecated This class has been superseded by IterativeInverse, which is
+ * more flexible and easier to use.
  *
- * Preconditioner using an iterative solver.  This preconditioner uses
- * a fully initialized LAC iterative solver for the approximate
- * inverse of the matrix. Naturally, this solver needs another
- * preconditionig method.
+ * Preconditioner using an iterative solver.  This preconditioner uses a fully
+ * initialized LAC iterative solver for the approximate inverse of the matrix.
+ * Naturally, this solver needs another preconditionig method.
  *
- * Usually, the use of ReductionControl is preferred over the use of
- * the basic SolverControl in defining this solver.
+ * Usually, the use of ReductionControl is preferred over the use of the basic
+ * SolverControl in defining this solver.
  *
- * Krylov space methods like SolverCG or SolverBicgstab
- * become inefficient if soution down to machine accuracy is
- * needed. This is due to the fact, that round-off errors spoil the
- * orthogonality of the vector sequences. Therefore, a nested
- * iteration of two methods is proposed: The outer method is
- * SolverRichardson, since it is robust with respect to round-of
- * errors. The inner loop is an appropriate Krylov space method, since
- * it is fast.
+ * Krylov space methods like SolverCG or SolverBicgstab become inefficient if
+ * soution down to machine accuracy is needed. This is due to the fact, that
+ * round-off errors spoil the orthogonality of the vector sequences.
+ * Therefore, a nested iteration of two methods is proposed: The outer method
+ * is SolverRichardson, since it is robust with respect to round-of errors.
+ * The inner loop is an appropriate Krylov space method, since it is fast.
  *
  * @code
  *     // Declare related objects
@@ -677,7 +671,7 @@ private:
  * Vector<double> x;
  * Vector<double> b;
  * GrowingVectorMemory<Vector<double> > mem;
-
+ *
  * ReductionControl inner_control (10, 1.e-30, 1.e-2)
  * SolverCG<Vector<double> > inner_iteration (inner_control, mem);
  * PreconditionSSOR <SparseMatrix<double> > inner_precondition;
@@ -692,11 +686,11 @@ private:
  * outer_iteration.solve (A, x, b, precondition);
  * @endcode
  *
- * Each time we call the inner loop, reduction of the residual by a
- * factor <tt>1.e-2</tt> is attempted. Since the right hand side vector of
- * the inner iteration is the residual of the outer loop, the relative
- * errors are far from machine accuracy, even if the errors of the
- * outer loop are in the range of machine accuracy.
+ * Each time we call the inner loop, reduction of the residual by a factor
+ * <tt>1.e-2</tt> is attempted. Since the right hand side vector of the inner
+ * iteration is the residual of the outer loop, the relative errors are far
+ * from machine accuracy, even if the errors of the outer loop are in the
+ * range of machine accuracy.
  *
  * @author Guido Kanschat, 1999
  */
@@ -745,13 +739,13 @@ private:
 /**
  * @deprecated Use ProductMatrix instead.
  *
- * Matrix with preconditioner.
- * Given a matrix $A$ and a preconditioner $P$, this class implements a new matrix
- * with the matrix-vector product $PA$. It needs an auxiliary vector for that.
+ * Matrix with preconditioner. Given a matrix $A$ and a preconditioner $P$,
+ * this class implements a new matrix with the matrix-vector product $PA$. It
+ * needs an auxiliary vector for that.
  *
- * By this time, this is considered a temporary object to be plugged
- * into eigenvalue solvers. Therefore, no SmartPointer is used for
- * <tt>A</tt> and <tt>P</tt>.
+ * By this time, this is considered a temporary object to be plugged into
+ * eigenvalue solvers. Therefore, no SmartPointer is used for <tt>A</tt> and
+ * <tt>P</tt>.
  *
  * @author Guido Kanschat, 2000
  */
@@ -800,13 +794,12 @@ private:
 
 
 /**
- * Preconditioning with a Chebyshev polynomial for symmetric positive
- * definite matrices. This preconditioner is similar to a Jacobi
- * preconditioner if the degree variable is set to one, otherwise some
- * higher order polynomial corrections are used. This preconditioner needs
- * access to the diagonal of the matrix its acts on and needs a respective
- * <tt>vmult</tt> implemention. However, it does not need to explicitly know
- * the matrix entries.
+ * Preconditioning with a Chebyshev polynomial for symmetric positive definite
+ * matrices. This preconditioner is similar to a Jacobi preconditioner if the
+ * degree variable is set to one, otherwise some higher order polynomial
+ * corrections are used. This preconditioner needs access to the diagonal of
+ * the matrix its acts on and needs a respective <tt>vmult</tt> implemention.
+ * However, it does not need to explicitly know the matrix entries.
  *
  * This class is useful e.g. in multigrid smoother objects, since it is
  * trivially %parallel (assuming that matrix-vector products are %parallel).
index fa0c8ec92255659623ba2aacad7db0fe6641e1db..ccf727e8c64bf0572d2ec4a7340cd9cd36bca7e0 100644 (file)
@@ -37,45 +37,42 @@ class PreconditionBlockJacobi;
 
 /**
  * Base class for actual block preconditioners. This class assumes the
- * <tt>MATRIX</tt> consisting of invertible blocks of @p blocksize on
- * the diagonal and provides the inversion of the diagonal blocks of
- * the matrix. It is not necessary for this class that the matrix be
- * block diagonal; rather, it applies to
- * matrices of arbitrary structure with the minimal property of having
- * invertible blocks on the diagonal. Still the matrix must have
- * access to single matrix entries. Therefore, BlockMatrixArray and similar
- * classes are not a possible matrix class template arguments.
+ * <tt>MATRIX</tt> consisting of invertible blocks of @p blocksize on the
+ * diagonal and provides the inversion of the diagonal blocks of the matrix.
+ * It is not necessary for this class that the matrix be block diagonal;
+ * rather, it applies to matrices of arbitrary structure with the minimal
+ * property of having invertible blocks on the diagonal. Still the matrix must
+ * have access to single matrix entries. Therefore, BlockMatrixArray and
+ * similar classes are not a possible matrix class template arguments.
  *
- * The block matrix structure used by this class is given, e.g., for
- * the DG method for the transport equation. For a downstream
- * numbering the matrices even have got a block lower left matrix
- * structure, i.e. the matrices are empty above the diagonal blocks.
+ * The block matrix structure used by this class is given, e.g., for the DG
+ * method for the transport equation. For a downstream numbering the matrices
+ * even have got a block lower left matrix structure, i.e. the matrices are
+ * empty above the diagonal blocks.
  *
- * @note This class is intended to be used for matrices whose structure
- * is given by local contributions from disjoint cells, such as for DG
- * methods. It is not intended for problems where the block structure
- * results from different physical variables such as in the Stokes
- * equations considered in step-22.
+ * @note This class is intended to be used for matrices whose structure is
+ * given by local contributions from disjoint cells, such as for DG methods.
+ * It is not intended for problems where the block structure results from
+ * different physical variables such as in the Stokes equations considered in
+ * step-22.
  *
- * For all matrices that are empty above and below the diagonal blocks
- * (i.e. for all block diagonal matrices) the @p BlockJacobi
- * preconditioner is a direct solver. For all matrices that are empty
- * only above the diagonal blocks (e.g. the matrices one gets by the
- * DG method with downstream numbering) @p BlockSOR is a direct
- * solver.
+ * For all matrices that are empty above and below the diagonal blocks (i.e.
+ * for all block diagonal matrices) the @p BlockJacobi preconditioner is a
+ * direct solver. For all matrices that are empty only above the diagonal
+ * blocks (e.g. the matrices one gets by the DG method with downstream
+ * numbering) @p BlockSOR is a direct solver.
  *
- * This first implementation of the @p PreconditionBlock assumes the
- * matrix has blocks each of the same block size. Varying block sizes
- * within the matrix must still be implemented if needed.
+ * This first implementation of the @p PreconditionBlock assumes the matrix
+ * has blocks each of the same block size. Varying block sizes within the
+ * matrix must still be implemented if needed.
  *
- * The first template parameter denotes the type of number
- * representation in the sparse matrix, the second denotes the type of
- * number representation in which the inverted diagonal block matrices
- * are stored within this class by <tt>invert_diagblocks()</tt>. If you
- * don't want to use the block inversion as an exact solver, but
- * rather as a preconditioner, you may probably want to store the
- * inverted blocks with less accuracy than the original matrix; for
- * example, <tt>number==double, inverse_type=float</tt> might be a viable
+ * The first template parameter denotes the type of number representation in
+ * the sparse matrix, the second denotes the type of number representation in
+ * which the inverted diagonal block matrices are stored within this class by
+ * <tt>invert_diagblocks()</tt>. If you don't want to use the block inversion
+ * as an exact solver, but rather as a preconditioner, you may probably want
+ * to store the inverted blocks with less accuracy than the original matrix;
+ * for example, <tt>number==double, inverse_type=float</tt> might be a viable
  * choice.
  *
  * @see @ref GlossBlockLA "Block (linear algebra)"
@@ -111,10 +108,8 @@ public:
   {
   public:
     /**
-     * Constructor. Block size
-     * must be given since there
-     * is no reasonable default
-     * parameter.
+     * Constructor. Block size must be given since there is no reasonable
+     * default parameter.
      */
     AdditionalData (const size_type block_size,
                     const double relaxation = 1.,
@@ -137,24 +132,18 @@ public:
     bool invert_diagonal;
 
     /**
-     * Assume all diagonal blocks
-     * are equal to save memory.
+     * Assume all diagonal blocks are equal to save memory.
      */
     bool same_diagonal;
     /**
-     * Choose the inversion
-     * method for the blocks.
+     * Choose the inversion method for the blocks.
      */
     typename PreconditionBlockBase<inverse_type>::Inversion inversion;
 
     /**
-     * The if #inversion is SVD,
-     * the threshold below which
-     * a singular value will be
-     * considered zero and thus
-     * not inverted. This
-     * parameter is used in the
-     * call to LAPACKFullMatrix::compute_inverse_svd().
+     * The if #inversion is SVD, the threshold below which a singular value
+     * will be considered zero and thus not inverted. This parameter is used
+     * in the call to LAPACKFullMatrix::compute_inverse_svd().
      */
     double threshold;
   };
@@ -171,42 +160,25 @@ public:
   ~PreconditionBlock();
 
   /**
-   * Initialize matrix and block
-   * size.  We store the matrix and
-   * the block size in the
-   * preconditioner object. In a
-   * second step, the inverses of
-   * the diagonal blocks may be
-   * computed.
+   * Initialize matrix and block size.  We store the matrix and the block size
+   * in the preconditioner object. In a second step, the inverses of the
+   * diagonal blocks may be computed.
    *
-   * Additionally, a relaxation
-   * parameter for derived classes
-   * may be provided.
+   * Additionally, a relaxation parameter for derived classes may be provided.
    */
   void initialize (const MATRIX &A,
                    const AdditionalData parameters);
 protected:
   /**
-   * Initialize matrix and block
-   * size for permuted
-   * preconditioning. Additionally
-   * to the parameters of the other
-   * initalize() function, we hand
-   * over two index vectors with
-   * the permutation and its
-   * inverse. For the meaning of
-   * these vectors see
-   * PreconditionBlockSOR.
+   * Initialize matrix and block size for permuted preconditioning.
+   * Additionally to the parameters of the other initalize() function, we hand
+   * over two index vectors with the permutation and its inverse. For the
+   * meaning of these vectors see PreconditionBlockSOR.
    *
-   * In a second step, the inverses
-   * of the diagonal blocks may be
-   * computed. Make sure you use
-   * invert_permuted_diagblocks()
-   * to yield consistent data.
+   * In a second step, the inverses of the diagonal blocks may be computed.
+   * Make sure you use invert_permuted_diagblocks() to yield consistent data.
    *
-   * Additionally, a relaxation
-   * parameter for derived classes
-   * may be provided.
+   * Additionally, a relaxation parameter for derived classes may be provided.
    */
   void initialize (const MATRIX &A,
                    const std::vector<size_type> &permutation,
@@ -214,70 +186,42 @@ protected:
                    const AdditionalData parameters);
 
   /**
-   * Set either the permutation of
-   * rows or the permutation of
-   * blocks, depending on the size
-   * of the vector.
+   * Set either the permutation of rows or the permutation of blocks,
+   * depending on the size of the vector.
    *
-   * If the size of the permutation
-   * vectors is equal to the
-   * dimension of the linear
-   * system, it is assumed that
-   * rows are permuted
-   * individually. In this case,
-   * set_permutation() must be
-   * called before initialize(),
-   * since the diagonal blocks are
-   * built from the permuted
-   * entries of the matrix.
+   * If the size of the permutation vectors is equal to the dimension of the
+   * linear system, it is assumed that rows are permuted individually. In this
+   * case, set_permutation() must be called before initialize(), since the
+   * diagonal blocks are built from the permuted entries of the matrix.
    *
-   * If the size of the permutation
-   * vector is not equal to the
-   * dimension of the system, the
-   * diagonal blocks are computed
-   * from the unpermuted
-   * entries. Instead, the
-   * relaxation methods step() and
-   * Tstep() are executed applying
-   * the blocks in the order given
-   * by the permutation
-   * vector. They will throw an
-   * exception if length of this
-   * vector is not equal to the
-   * number of blocks.
+   * If the size of the permutation vector is not equal to the dimension of
+   * the system, the diagonal blocks are computed from the unpermuted entries.
+   * Instead, the relaxation methods step() and Tstep() are executed applying
+   * the blocks in the order given by the permutation vector. They will throw
+   * an exception if length of this vector is not equal to the number of
+   * blocks.
    *
-   * @note Permutation of blocks
-   * can only be applied to the
-   * relaxation operators step()
-   * and Tstep(), not to the
-   * preconditioning operators
+   * @note Permutation of blocks can only be applied to the relaxation
+   * operators step() and Tstep(), not to the preconditioning operators
    * vmult() and Tvmult().
    *
-   * @note It is safe to call
-   * set_permutation() before
-   * initialize(), while the other
-   * order is only admissible for
-   * block permutation.
+   * @note It is safe to call set_permutation() before initialize(), while the
+   * other order is only admissible for block permutation.
    */
   void set_permutation(const std::vector<size_type> &permutation,
                        const std::vector<size_type> &inverse_permutation);
 
   /**
-   * Replacement of
-   * invert_diagblocks() for
-   * permuted preconditioning.
+   * Replacement of invert_diagblocks() for permuted preconditioning.
    */
   void invert_permuted_diagblocks(
     const std::vector<size_type> &permutation,
     const std::vector<size_type> &inverse_permutation);
 public:
   /**
-   * Deletes the inverse diagonal
-   * block matrices if existent,
-   * sets the blocksize to 0, hence
-   * leaves the class in the state
-   * that it had directly after
-   * calling the constructor.
+   * Deletes the inverse diagonal block matrices if existent, sets the
+   * blocksize to 0, hence leaves the class in the state that it had directly
+   * after calling the constructor.
    */
   void clear();
 
@@ -287,59 +231,39 @@ public:
   bool empty () const;
 
   /**
-   * Read-only access to entries.
-   * This function is only possible
-   * if the inverse diagonal blocks
-   * are stored.
+   * Read-only access to entries. This function is only possible if the
+   * inverse diagonal blocks are stored.
    */
   value_type el(size_type i,
                 size_type j) const;
 
   /**
-   * Stores the inverse of the
-   * diagonal blocks in
-   * @p inverse. This costs some
-   * additional memory - for DG
-   * methods about 1/3 (for double
-   * inverses) or 1/6 (for float
-   * inverses) of that used for the
-   * matrix - but it makes the
+   * Stores the inverse of the diagonal blocks in @p inverse. This costs some
+   * additional memory - for DG methods about 1/3 (for double inverses) or 1/6
+   * (for float inverses) of that used for the matrix - but it makes the
    * preconditioning much faster.
    *
-   * It is not allowed to call this
-   * function twice (will produce
-   * an error) before a call of
-   * <tt>clear(...)</tt>  because at the
-   * second time there already
-   * exist the inverse matrices.
+   * It is not allowed to call this function twice (will produce an error)
+   * before a call of <tt>clear(...)</tt>  because at the second time there
+   * already exist the inverse matrices.
    *
-   * After this function is called,
-   * the lock on the matrix given
-   * through the @p use_matrix
-   * function is released, i.e. you
-   * may overwrite of delete it.
-   * You may want to do this in
-   * case you use this matrix to
-   * precondition another matrix.
+   * After this function is called, the lock on the matrix given through the
+   * @p use_matrix function is released, i.e. you may overwrite of delete it.
+   * You may want to do this in case you use this matrix to precondition
+   * another matrix.
    */
   void invert_diagblocks();
 
   /**
-   * Perform one block relaxation
-   * step in forward numbering.
+   * Perform one block relaxation step in forward numbering.
    *
-   * Depending on the arguments @p
-   * dst and @p pref, this performs
-   * an SOR step (both reference
-   * the same vector) of a Jacobi
-   * step (botha different
-   * vectors). For the Jacobi step,
-   * the calling function must copy
-   * @p dst to @p pref after this.
+   * Depending on the arguments @p dst and @p pref, this performs an SOR step
+   * (both reference the same vector) of a Jacobi step (botha different
+   * vectors). For the Jacobi step, the calling function must copy @p dst to
+   * @p pref after this.
    *
-   * @note If a permutation is set,
-   * it is automatically honored by
-   * this function.
+   * @note If a permutation is set, it is automatically honored by this
+   * function.
    */
   template <typename number2>
   void forward_step (
@@ -349,21 +273,15 @@ public:
     const bool transpose_diagonal) const;
 
   /**
-   * Perform one block relaxation
-   * step in backward numbering.
+   * Perform one block relaxation step in backward numbering.
    *
-   * Depending on the arguments @p
-   * dst and @p pref, this performs
-   * an SOR step (both reference
-   * the same vector) of a Jacobi
-   * step (botha different
-   * vectors). For the Jacobi step,
-   * the calling function must copy
-   * @p dst to @p pref after this.
+   * Depending on the arguments @p dst and @p pref, this performs an SOR step
+   * (both reference the same vector) of a Jacobi step (botha different
+   * vectors). For the Jacobi step, the calling function must copy @p dst to
+   * @p pref after this.
    *
-   * @note If a permutation is set,
-   * it is automatically honored by
-   * this function.
+   * @note If a permutation is set, it is automatically honored by this
+   * function.
    */
   template <typename number2>
   void backward_step (
@@ -379,30 +297,26 @@ public:
   size_type block_size () const;
 
   /**
-   * @deprecated Use size()
-   * instead.
+   * @deprecated Use size() instead.
    *
-   * The number of blocks of the
-   * matrix.
+   * The number of blocks of the matrix.
    */
   unsigned int n_blocks() const DEAL_II_DEPRECATED;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
-   * For non-overlapping block
-   * preconditioners, the block
-   * size must divide the matrix
-   * size. If not, this exception
-   * gets thrown.
+   * For non-overlapping block preconditioners, the block size must divide the
+   * matrix size. If not, this exception gets thrown.
    */
   DeclException2 (ExcWrongBlockSize,
                   int, int,
@@ -419,28 +333,20 @@ public:
 
 protected:
   /**
-   * Size of the blocks. Each
-   * diagonal block is assumed to
-   * be of the same size.
+   * Size of the blocks. Each diagonal block is assumed to be of the same
+   * size.
    */
   size_type blocksize;
 
   /**
-   * Pointer to the matrix. Make
-   * sure that the matrix exists as
-   * long as this class needs it,
-   * i.e. until calling
-   * @p invert_diagblocks, or (if
-   * the inverse matrices should
-   * not be stored) until the last
-   * call of the preconditoining
-   * @p vmult function of the
-   * derived classes.
+   * Pointer to the matrix. Make sure that the matrix exists as long as this
+   * class needs it, i.e. until calling @p invert_diagblocks, or (if the
+   * inverse matrices should not be stored) until the last call of the
+   * preconditoining @p vmult function of the derived classes.
    */
   SmartPointer<const MATRIX,PreconditionBlock<MATRIX,inverse_type> > A;
   /**
-   * Relaxation parameter to be
-   * used by derived classes.
+   * Relaxation parameter to be used by derived classes.
    */
   double relaxation;
 
@@ -455,16 +361,15 @@ protected:
   std::vector<size_type> inverse_permutation;
 
   /**
-   * Flag for diagonal compression.
-   * @ref set_same_diagonal()
+   * Flag for diagonal compression. @ref set_same_diagonal()
    */
 };
 
 
 
 /**
- * Block Jacobi preconditioning.
- * See PreconditionBlock for requirements on the matrix.
+ * Block Jacobi preconditioning. See PreconditionBlock for requirements on the
+ * matrix.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -501,25 +406,19 @@ public:
     {
     public:
       /**
-       * Constructor. Since we use
-       * accessors only for read
-       * access, a const matrix
-       * pointer is sufficient.
+       * Constructor. Since we use accessors only for read access, a const
+       * matrix pointer is sufficient.
        */
       Accessor (const PreconditionBlockJacobi<MATRIX, inverse_type> *matrix,
                 const size_type row);
 
       /**
-       * Row number of the element
-       * represented by this
-       * object.
+       * Row number of the element represented by this object.
        */
       size_type row() const;
 
       /**
-       * Column number of the
-       * element represented by
-       * this object.
+       * Column number of the element represented by this object.
        */
       size_type column() const;
 
@@ -535,8 +434,7 @@ public:
       const PreconditionBlockJacobi<MATRIX, inverse_type> *matrix;
 
       /**
-       * Save block size here
-       * for further reference.
+       * Save block size here for further reference.
        */
       size_type bs;
 
@@ -556,8 +454,7 @@ public:
       typename FullMatrix<inverse_type>::const_iterator b_end;
 
       /**
-       * Make enclosing class a
-       * friend.
+       * Make enclosing class a friend.
        */
       friend class const_iterator;
     };
@@ -590,10 +487,7 @@ public:
     const Accessor *operator-> () const;
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const const_iterator &) const;
     /**
@@ -602,20 +496,14 @@ public:
     bool operator != (const const_iterator &) const;
 
     /**
-     * Comparison
-     * operator. Result is true
-     * if either the first row
-     * number is smaller or if
-     * the row numbers are
-     * equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      */
     bool operator < (const const_iterator &) const;
 
   private:
     /**
-     * Store an object of the
-     * accessor class.
+     * Store an object of the accessor class.
      */
     Accessor accessor;
   };
@@ -642,16 +530,11 @@ public:
   using PreconditionBlock<MATRIX, inverse_type>::set_permutation;
 
   /**
-   * Execute block Jacobi
-   * preconditioning.
+   * Execute block Jacobi preconditioning.
    *
-   * This function will
-   * automatically use the inverse
-   * matrices if they exist, if not
-   * then BlockJacobi will need
-   * much time inverting the
-   * diagonal block matrices in
-   * each preconditioning step.
+   * This function will automatically use the inverse matrices if they exist,
+   * if not then BlockJacobi will need much time inverting the diagonal block
+   * matrices in each preconditioning step.
    */
   template <typename number2>
   void vmult (Vector<number2> &, const Vector<number2> &) const;
@@ -662,44 +545,35 @@ public:
   template <typename number2>
   void Tvmult (Vector<number2> &, const Vector<number2> &) const;
   /**
-   * Execute block Jacobi
-   * preconditioning, adding to @p dst.
+   * Execute block Jacobi preconditioning, adding to @p dst.
    *
-   * This function will
-   * automatically use the inverse
-   * matrices if they exist, if not
-   * then BlockJacobi will need
-   * much time inverting the
-   * diagonal block matrices in
-   * each preconditioning step.
+   * This function will automatically use the inverse matrices if they exist,
+   * if not then BlockJacobi will need much time inverting the diagonal block
+   * matrices in each preconditioning step.
    */
   template <typename number2>
   void vmult_add (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Same as @p vmult_add, since
-   * Jacobi is symmetric.
+   * Same as @p vmult_add, since Jacobi is symmetric.
    */
   template <typename number2>
   void Tvmult_add (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Perform one step of the Jacobi
-   * iteration.
+   * Perform one step of the Jacobi iteration.
    */
   template <typename number2>
   void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
   /**
-   * Perform one step of the Jacobi
-   * iteration.
+   * Perform one step of the Jacobi iteration.
    */
   template <typename number2>
   void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
   /**
-   * STL-like iterator with the
-   * first entry.
+   * STL-like iterator with the first entry.
    */
   const_iterator begin () const;
 
@@ -709,8 +583,7 @@ public:
   const_iterator end () const;
 
   /**
-   * STL-like iterator with the
-   * first entry of row @p r.
+   * STL-like iterator with the first entry of row @p r.
    */
   const_iterator begin (const size_type r) const;
 
@@ -722,12 +595,10 @@ public:
 
 private:
   /**
-   * Actual implementation of the
-   * preconditioner.
+   * Actual implementation of the preconditioner.
    *
-   * Depending on @p adding, the
-   * result of preconditioning is
-   * added to the destination vector.
+   * Depending on @p adding, the result of preconditioning is added to the
+   * destination vector.
    */
   template <typename number2>
   void do_vmult (Vector<number2> &,
@@ -743,30 +614,26 @@ private:
 /**
  * Block SOR preconditioning.
  *
- * The functions @p vmult and @p Tvmult execute a (transposed)
- * block-SOR step, based on the blocks in PreconditionBlock. The
- * elements outside the diagonal blocks may be distributed
- * arbitrarily.
+ * The functions @p vmult and @p Tvmult execute a (transposed) block-SOR step,
+ * based on the blocks in PreconditionBlock. The elements outside the diagonal
+ * blocks may be distributed arbitrarily.
  *
- * See PreconditionBlock for requirements on the matrix. The blocks
- * used in this class must be contiguous and non-overlapping. An
- * overlapping Schwarz relaxation method can be found in
- * RelaxationBlockSOR; that class does not offer preconditioning,
- * though.
+ * See PreconditionBlock for requirements on the matrix. The blocks used in
+ * this class must be contiguous and non-overlapping. An overlapping Schwarz
+ * relaxation method can be found in RelaxationBlockSOR; that class does not
+ * offer preconditioning, though.
  *
  * <h3>Permutations</h3>
  *
- * Optionally, the entries of the source vector can be treated in the
- * order of the indices in the permutation vector set by
- * #set_permutation (or the opposite order for Tvmult()). The inverse
- * permutation is used for storing elements back into this
- * vector. This functionality is automatically enabled after a call to
- * set_permutation() with vectors of nonzero size.
+ * Optionally, the entries of the source vector can be treated in the order of
+ * the indices in the permutation vector set by #set_permutation (or the
+ * opposite order for Tvmult()). The inverse permutation is used for storing
+ * elements back into this vector. This functionality is automatically enabled
+ * after a call to set_permutation() with vectors of nonzero size.
  *
- * @note The diagonal blocks, like the matrix, are not permuted!
- * Therefore, the permutation vector can only swap whole blocks. It
- * may not change the order inside blocks or swap single indices
- * between blocks.
+ * @note The diagonal blocks, like the matrix, are not permuted! Therefore,
+ * the permutation vector can only swap whole blocks. It may not change the
+ * order inside blocks or swap single indices between blocks.
  *
  * <h3>Instantiations</h3>
  *
@@ -814,38 +681,25 @@ public:
   using PreconditionBlockBase<inverse_type>::log_statistics;
 
   /**
-   * Execute block SOR
-   * preconditioning.
+   * Execute block SOR preconditioning.
    *
-   * This function will
-   * automatically use the inverse
-   * matrices if they exist, if not
-   * then BlockSOR will waste much
-   * time inverting the diagonal
-   * block matrices in each
-   * preconditioning step.
+   * This function will automatically use the inverse matrices if they exist,
+   * if not then BlockSOR will waste much time inverting the diagonal block
+   * matrices in each preconditioning step.
    *
-   * For matrices which are empty
-   * above the diagonal blocks
-   * BlockSOR is a direct solver.
+   * For matrices which are empty above the diagonal blocks BlockSOR is a
+   * direct solver.
    */
   template <typename number2>
   void vmult (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Execute block SOR
-   * preconditioning.
+   * Execute block SOR preconditioning.
    *
-   * Warning: this function
-   * performs normal @p vmult
-   * without adding. The reason for
-   * its existence is that
-   * BlockMatrixArray
-   * requires the adding version by
-   * default. On the other hand,
-   * adding requires an additional
-   * auxiliary vector, which is not
-   * desirable.
+   * Warning: this function performs normal @p vmult without adding. The
+   * reason for its existence is that BlockMatrixArray requires the adding
+   * version by default. On the other hand, adding requires an additional
+   * auxiliary vector, which is not desirable.
    *
    * @see vmult
    */
@@ -855,34 +709,21 @@ public:
   /**
    * Backward application of vmult().
    *
-   * In the current implementation,
-   * this is not the transpose of
-   * vmult(). It is a
-   * transposed Gauss-Seidel
-   * algorithm applied to the whole
-   * matrix, but the diagonal
-   * blocks being inverted are not
-   * transposed. Therefore, it is
-   * the transposed, if the
-   * diagonal blocks are symmetric.
+   * In the current implementation, this is not the transpose of vmult(). It
+   * is a transposed Gauss-Seidel algorithm applied to the whole matrix, but
+   * the diagonal blocks being inverted are not transposed. Therefore, it is
+   * the transposed, if the diagonal blocks are symmetric.
    */
   template <typename number2>
   void Tvmult (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Execute backward block SOR
-   * preconditioning.
+   * Execute backward block SOR preconditioning.
    *
-   * Warning: this function
-   * performs normal @p vmult
-   * without adding. The reason for
-   * its existence is that
-   * BlockMatrixArray
-   * requires the adding version by
-   * default. On the other hand,
-   * adding requires an additional
-   * auxiliary vector, which is not
-   * desirable.
+   * Warning: this function performs normal @p vmult without adding. The
+   * reason for its existence is that BlockMatrixArray requires the adding
+   * version by default. On the other hand, adding requires an additional
+   * auxiliary vector, which is not desirable.
    *
    * @see vmult
    */
@@ -890,38 +731,31 @@ public:
   void Tvmult_add (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Perform one step of the SOR
-   * iteration.
+   * Perform one step of the SOR iteration.
    */
   template <typename number2>
   void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
   /**
-   * Perform one step of the
-   * transposed SOR iteration.
+   * Perform one step of the transposed SOR iteration.
    */
   template <typename number2>
   void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
 protected:
   /**
-   * Constructor to be used by
-   * PreconditionBlockSSOR.
+   * Constructor to be used by PreconditionBlockSSOR.
    */
   PreconditionBlockSOR(bool store);
 
   /**
-   * Implementation of the forward
-   * substitution loop called by
-   * vmult() and vmult_add().
+   * Implementation of the forward substitution loop called by vmult() and
+   * vmult_add().
    *
-   * If a #permutation is set by
-   * set_permutation(), it will
-   * automatically be honored by
-   * this function.
+   * If a #permutation is set by set_permutation(), it will automatically be
+   * honored by this function.
    *
-   * The parameter @p adding does
-   * not have any function, yet.
+   * The parameter @p adding does not have any function, yet.
    */
   template <typename number2>
   void forward (Vector<number2> &,
@@ -930,17 +764,13 @@ protected:
                 const bool adding) const;
 
   /**
-   * Implementation of the backward
-   * substitution loop called by
-   * Tvmult() and Tvmult_add().
+   * Implementation of the backward substitution loop called by Tvmult() and
+   * Tvmult_add().
    *
-   * If a #permutation is set by
-   * set_permutation(), it will
-   * automatically be honored by
-   * this function.
+   * If a #permutation is set by set_permutation(), it will automatically be
+   * honored by this function.
    *
-   * The parameter @p adding does
-   * not have any function, yet.
+   * The parameter @p adding does not have any function, yet.
    */
   template <typename number2>
   void backward (Vector<number2> &,
@@ -953,15 +783,14 @@ protected:
 /**
  * Block SSOR preconditioning.
  *
- * The functions @p vmult and @p Tvmult execute a block-SSOR step,
- * based on the implementation in PreconditionBlockSOR.  This
- * class requires storage of the diagonal blocks and their inverses.
+ * The functions @p vmult and @p Tvmult execute a block-SSOR step, based on
+ * the implementation in PreconditionBlockSOR.  This class requires storage of
+ * the diagonal blocks and their inverses.
  *
- * See PreconditionBlock for requirements on the matrix. The blocks
- * used in this class must be contiguous and non-overlapping. An
- * overlapping Schwarz relaxation method can be found in
- * RelaxationBlockSSOR; that class does not offer preconditioning,
- * though.
+ * See PreconditionBlock for requirements on the matrix. The blocks used in
+ * this class must be contiguous and non-overlapping. An overlapping Schwarz
+ * relaxation method can be found in RelaxationBlockSSOR; that class does not
+ * offer preconditioning, though.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -997,8 +826,7 @@ public:
   // which we want to keep
   // accessible.
   /**
-   * Make initialization function
-   * publicly available.
+   * Make initialization function publicly available.
    */
   using PreconditionBlockSOR<MATRIX,inverse_type>::initialize;
   using PreconditionBlockSOR<MATRIX,inverse_type>::clear;
@@ -1014,16 +842,11 @@ public:
   using PreconditionBlockSOR<MATRIX,inverse_type>::invert_diagblocks;
 
   /**
-   * Execute block SSOR
-   * preconditioning.
+   * Execute block SSOR preconditioning.
    *
-   * This function will
-   * automatically use the inverse
-   * matrices if they exist, if not
-   * then BlockSOR will waste much
-   * time inverting the diagonal
-   * block matrices in each
-   * preconditioning step.
+   * This function will automatically use the inverse matrices if they exist,
+   * if not then BlockSOR will waste much time inverting the diagonal block
+   * matrices in each preconditioning step.
    */
   template <typename number2>
   void vmult (Vector<number2> &, const Vector<number2> &) const;
@@ -1035,15 +858,13 @@ public:
   void Tvmult (Vector<number2> &, const Vector<number2> &) const;
 
   /**
-   * Perform one step of the SOR
-   * iteration.
+   * Perform one step of the SOR iteration.
    */
   template <typename number2>
   void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
   /**
-   * Perform one step of the
-   * transposed SOR iteration.
+   * Perform one step of the transposed SOR iteration.
    */
   template <typename number2>
   void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
index ee5f823aced91cef70eaa42a9cbdb5c0eb572e2e..e62d9831d3d2a11685fd1fae5be6c41483b2cde1 100644 (file)
@@ -33,20 +33,19 @@ template <typename number> class FullMatrix;
 template <typename number> class Vector;
 
 /**
- * A class storing the inverse diagonal blocks for block
- * preconditioners and block relaxation methods.
+ * A class storing the inverse diagonal blocks for block preconditioners and
+ * block relaxation methods.
  *
- * This class does the book keeping for preconditioners and relaxation
- * methods based on inverting blocks on the diagonal of a matrix.
- * It allows us to either store all diagonal blocks and their
- * inverses or the same block for each entry, and it keeps track of
- * the choice. Thus, after initializing it and filling the inverse
- * diagonal blocks correctly, a derived class can use inverse() with
- * an integer argument referring to the block number.
+ * This class does the book keeping for preconditioners and relaxation methods
+ * based on inverting blocks on the diagonal of a matrix. It allows us to
+ * either store all diagonal blocks and their inverses or the same block for
+ * each entry, and it keeps track of the choice. Thus, after initializing it
+ * and filling the inverse diagonal blocks correctly, a derived class can use
+ * inverse() with an integer argument referring to the block number.
  *
- * Additionally, it allows the storage of the original diagonal
- * blocks, not only the inverses. These are for instance used in the
- * intermediate step of the SSOR preconditioner.
+ * Additionally, it allows the storage of the original diagonal blocks, not
+ * only the inverses. These are for instance used in the intermediate step of
+ * the SSOR preconditioner.
  *
  * @author Guido Kanschat
  * @date 2010
@@ -61,33 +60,28 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Choose a method for inverting
-   * the blocks, and thus the data
-   * type for the inverses.
+   * Choose a method for inverting the blocks, and thus the data type for the
+   * inverses.
    */
   enum Inversion
   {
     /**
-     * Use the standard
-     * Gauss-Jacobi method
-     * implemented in FullMatrix::inverse().
+     * Use the standard Gauss-Jacobi method implemented in
+     * FullMatrix::inverse().
      */
     gauss_jordan,
     /**
-     * Use QR decomposition of
-     * the Householder class.
+     * Use QR decomposition of the Householder class.
      */
     householder,
     /**
-     * Use the singular value
-     * decomposition of LAPACKFullMatrix.
+     * Use the singular value decomposition of LAPACKFullMatrix.
      */
     svd
   };
 
   /**
-   * Constructor initializing
-   * default values.
+   * Constructor initializing default values.
    */
   PreconditionBlockBase(bool store_diagonals = false,
                         Inversion method = gauss_jordan);
@@ -98,62 +92,45 @@ public:
   ~PreconditionBlockBase();
 
   /**
-   * Deletes the inverse diagonal
-   * block matrices if existent hence
-   * leaves the class in the state
-   * that it had directly after
-   * calling the constructor.
+   * Deletes the inverse diagonal block matrices if existent hence leaves the
+   * class in the state that it had directly after calling the constructor.
    */
   void clear();
 
   /**
-   * Resize to this number of
-   * diagonal blocks with the given
-   * block size. If
-   * <tt>compress</tt> is true,
-   * then only one block will be
-   * stored.
+   * Resize to this number of diagonal blocks with the given block size. If
+   * <tt>compress</tt> is true, then only one block will be stored.
    */
   void reinit(unsigned int nblocks, size_type blocksize, bool compress,
               Inversion method = gauss_jordan);
 
   /**
-   * Tell the class that inverses
-   * are computed.
+   * Tell the class that inverses are computed.
    */
   void inverses_computed(bool are_they);
 
   /**
-   * Use only the inverse of the
-   * first diagonal block to save
-   * memory and computation time.
+   * Use only the inverse of the first diagonal block to save memory and
+   * computation time.
    *
-   * Possible applications:
-   * computing on a cartesian grid,
-   * all diagonal blocks are the
-   * same or all diagonal blocks
-   * are at least similar and
-   * inversion of one of them still
-   * yields a preconditioner.
+   * Possible applications: computing on a cartesian grid, all diagonal blocks
+   * are the same or all diagonal blocks are at least similar and inversion of
+   * one of them still yields a preconditioner.
    */
   void set_same_diagonal ();
 
   /**
-   * Does the matrix use only one
-   * diagonal block?
+   * Does the matrix use only one diagonal block?
    */
   bool same_diagonal () const;
 
   /**
-   * Check, whether diagonal blocks
-   * (not their inverses)
-   * should be stored.
+   * Check, whether diagonal blocks (not their inverses) should be stored.
    */
   bool store_diagonals() const;
 
   /**
-   * Return true, if inverses are
-   * ready for use.
+   * Return true, if inverses are ready for use.
    */
   bool inverses_ready () const;
 
@@ -168,107 +145,86 @@ public:
   unsigned int size() const;
 
   /**
-   * Read-only access to entries.
-   * This function is only possible
-   * if the inverse diagonal blocks
-   * are stored.
+   * Read-only access to entries. This function is only possible if the
+   * inverse diagonal blocks are stored.
    */
   number el(size_type i, size_type j) const;
 
   /**
-   * Multiply with the inverse
-   * block at position <tt>i</tt>.
+   * Multiply with the inverse block at position <tt>i</tt>.
    */
   template <typename number2>
   void inverse_vmult(size_type i, Vector<number2> &dst, const Vector<number2> &src) const;
 
   /**
-   * Multiply with the transposed inverse
-   * block at position <tt>i</tt>.
+   * Multiply with the transposed inverse block at position <tt>i</tt>.
    */
   template <typename number2>
   void inverse_Tvmult(size_type i, Vector<number2> &dst, const Vector<number2> &src) const;
 
   /**
-   * Access to the inverse diagonal
-   * blocks if Inversion is #gauss_jordan.
+   * Access to the inverse diagonal blocks if Inversion is #gauss_jordan.
    */
   FullMatrix<number> &inverse (size_type i);
 
   /**
-   * Access to the inverse diagonal
-   * blocks if Inversion is #householder.
+   * Access to the inverse diagonal blocks if Inversion is #householder.
    */
   Householder<number> &inverse_householder (size_type i);
 
   /**
-   * Access to the inverse diagonal
-   * blocks if Inversion is #householder.
+   * Access to the inverse diagonal blocks if Inversion is #householder.
    */
   LAPACKFullMatrix<number> &inverse_svd (size_type i);
 
   /**
-   * Access to the inverse diagonal
-   * blocks.
+   * Access to the inverse diagonal blocks.
    */
   const FullMatrix<number> &inverse (size_type i) const;
 
   /**
-   * Access to the inverse diagonal
-   * blocks if Inversion is #householder.
+   * Access to the inverse diagonal blocks if Inversion is #householder.
    */
   const Householder<number> &inverse_householder (size_type i) const;
 
   /**
-   * Access to the inverse diagonal
-   * blocks if Inversion is #householder.
+   * Access to the inverse diagonal blocks if Inversion is #householder.
    */
   const LAPACKFullMatrix<number> &inverse_svd (size_type i) const;
 
   /**
-   * Access to the diagonal
-   * blocks.
+   * Access to the diagonal blocks.
    */
   FullMatrix<number> &diagonal (size_type i);
 
   /**
-   * Access to the diagonal
-   * blocks.
+   * Access to the diagonal blocks.
    */
   const FullMatrix<number> &diagonal (size_type i) const;
 
   /**
-   * Print some statistics about
-   * the inverses to @p deallog. Output depends
-   * on #Inversion. It is richest
-   * for svd, where we obtain
-   * statistics on extremal
-   * singular values and condition
-   * numbers.
+   * Print some statistics about the inverses to @p deallog. Output depends on
+   * #Inversion. It is richest for svd, where we obtain statistics on extremal
+   * singular values and condition numbers.
    */
   void log_statistics () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-   * You are trying to access a
-   * diagonal block (not its
-   * inverse), but you decided not
-   * to store the diagonal blocks.
+   * You are trying to access a diagonal block (not its inverse), but you
+   * decided not to store the diagonal blocks.
    */
   DeclException0 (ExcDiagonalsNotStored);
 
   /**
-   * You are accessing a diagonal
-   * block, assuming that it has a certain
-   * type. But, the method used for
-   * inverting the diagonal blocks
-   * does not use this type
+   * You are accessing a diagonal block, assuming that it has a certain type.
+   * But, the method used for inverting the diagonal blocks does not use this
+   * type
    */
   DeclException0 (ExcInverseNotAvailable);
 
@@ -280,51 +236,31 @@ protected:
 
 private:
   /**
-   * The number of (inverse)
-   * diagonal blocks, if only one
-   * is stored.
+   * The number of (inverse) diagonal blocks, if only one is stored.
    */
   unsigned int n_diagonal_blocks;
 
   /**
-   * Storage of the inverse
-   * matrices of the diagonal
-   * blocks matrices as
-   * <tt>FullMatrix<number></tt>
-   * matrices, if Inversion
-   * #gauss_jordan is used. Using
-   * <tt>number=float</tt> saves
-   * memory in comparison with
-   * <tt>number=double</tt>, but
-   * may introduce numerical instability.
+   * Storage of the inverse matrices of the diagonal blocks matrices as
+   * <tt>FullMatrix<number></tt> matrices, if Inversion #gauss_jordan is used.
+   * Using <tt>number=float</tt> saves memory in comparison with
+   * <tt>number=double</tt>, but may introduce numerical instability.
    */
   std::vector<FullMatrix<number> > var_inverse_full;
 
   /**
-   * Storage of the inverse
-   * matrices of the diagonal
-   * blocks matrices as
-   * <tt>Householder</tt>
-   * matrices if Inversion
-   * #householder is used. Using
-   * <tt>number=float</tt> saves
-   * memory in comparison with
-   * <tt>number=double</tt>, but
-   * may introduce numerical instability.
+   * Storage of the inverse matrices of the diagonal blocks matrices as
+   * <tt>Householder</tt> matrices if Inversion #householder is used. Using
+   * <tt>number=float</tt> saves memory in comparison with
+   * <tt>number=double</tt>, but may introduce numerical instability.
    */
   std::vector<Householder<number> > var_inverse_householder;
 
   /**
-   * Storage of the inverse
-   * matrices of the diagonal
-   * blocks matrices as
-   * <tt>LAPACKFullMatrix</tt>
-   * matrices if Inversion
-   * #svd is used. Using
-   * <tt>number=float</tt> saves
-   * memory in comparison with
-   * <tt>number=double</tt>, but
-   * may introduce numerical instability.
+   * Storage of the inverse matrices of the diagonal blocks matrices as
+   * <tt>LAPACKFullMatrix</tt> matrices if Inversion #svd is used. Using
+   * <tt>number=float</tt> saves memory in comparison with
+   * <tt>number=double</tt>, but may introduce numerical instability.
    */
   std::vector<LAPACKFullMatrix<number> > var_inverse_svd;
 
@@ -337,21 +273,18 @@ private:
 
 
   /**
-   * This is true, if the field
-   * #var_diagonal is to be used.
+   * This is true, if the field #var_diagonal is to be used.
    */
   bool var_store_diagonals;
 
   /**
-   * This is true, if only one
-   * inverse is stored.
+   * This is true, if only one inverse is stored.
    */
   bool var_same_diagonal;
 
   /**
-   * The inverse matrices are
-   * usable. Set by the parent
-   * class via inverses_computed().
+   * The inverse matrices are usable. Set by the parent class via
+   * inverses_computed().
    */
   bool var_inverses_ready;
 };
index 4e173c0b8117d84e1d0a26ded75e7dc44f309c72..583d2b68f016783ec450089fc763cea6258e3d67 100644 (file)
@@ -32,21 +32,18 @@ template <class number> class SparseMatrix;
  */
 
 /**
- * Selects the preconditioner. The constructor of this class takes
- * the name of the preconditioning and the damping parameter
- * @p omega of the preconditioning and the @p use_matrix function takes
- * the matrix that is used
- * by the matrix-builtin precondition functions. Each time, the <tt>operator()</tt> function
- * is called, this preselected preconditioner, this matrix and
- * this @p omega is used
- * for the preconditioning. This class is designed for being used as
- * argument of the @p solve function of a @p Solver and it covers the
- * selection of all matrix-builtin precondition functions. The selection
- * of other preconditioners, like BlockSOR or ILU should be handled in
- * derived classes by the user.
+ * Selects the preconditioner. The constructor of this class takes the name of
+ * the preconditioning and the damping parameter @p omega of the
+ * preconditioning and the @p use_matrix function takes the matrix that is
+ * used by the matrix-builtin precondition functions. Each time, the
+ * <tt>operator()</tt> function is called, this preselected preconditioner,
+ * this matrix and this @p omega is used for the preconditioning. This class
+ * is designed for being used as argument of the @p solve function of a @p
+ * Solver and it covers the selection of all matrix-builtin precondition
+ * functions. The selection of other preconditioners, like BlockSOR or ILU
+ * should be handled in derived classes by the user.
  *
- * <h3>Usage</h3>
- * The simplest use of this class is the following:
+ * <h3>Usage</h3> The simplest use of this class is the following:
  * @code
  *                                  // generate a @p SolverControl and
  *                                  // a @p VectorMemory
@@ -84,10 +81,10 @@ template <class number> class SparseMatrix;
  *
  * solver_selector.solve(A,x,b,preconditioning);
  * @endcode
- * Now the use of the @p SolverSelector in combination with the @p PreconditionSelector
- * allows the user to select both, the solver and the preconditioner, at the
- * beginning of his program and each time the
- * solver is started (that is several times e.g. in a nonlinear iteration) this
+ * Now the use of the @p SolverSelector in combination with the @p
+ * PreconditionSelector allows the user to select both, the solver and the
+ * preconditioner, at the beginning of his program and each time the solver is
+ * started (that is several times e.g. in a nonlinear iteration) this
  * preselected solver and preconditioner is called.
  *
  * @author Ralf Hartmann, 1999
@@ -99,9 +96,8 @@ class PreconditionSelector : public Subscriptor
 public:
 
   /**
-   * Constructor. @p omega denotes
-   * the damping parameter of
-   * the preconditioning.
+   * Constructor. @p omega denotes the damping parameter of the
+   * preconditioning.
    */
   PreconditionSelector(const std::string                 &preconditioning,
                        const typename VECTOR::value_type &omega=1.);
@@ -112,28 +108,26 @@ public:
   virtual ~PreconditionSelector();
 
   /**
-   * Takes the matrix that is needed
-   * for preconditionings that involves a
-   * matrix. e.g. for @p precondition_jacobi,
-   * <tt>~_sor</tt>, <tt>~_ssor</tt>.
+   * Takes the matrix that is needed for preconditionings that involves a
+   * matrix. e.g. for @p precondition_jacobi, <tt>~_sor</tt>, <tt>~_ssor</tt>.
    */
   void use_matrix(const MATRIX &M);
 
   /**
-   * Precondition procedure. Calls the
-   * preconditioning that was specified in
+   * Precondition procedure. Calls the preconditioning that was specified in
    * the constructor.
    */
   virtual void vmult (VECTOR &dst, const VECTOR &src) const;
 
   /**
-   * Get the names of all implemented
-   * preconditionings.
+   * Get the names of all implemented preconditionings.
    */
   static std::string get_precondition_names();
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
 
   /**
@@ -145,22 +139,19 @@ public:
 protected:
 
   /**
-   * Stores the name of the
-   * preconditioning.
+   * Stores the name of the preconditioning.
    */
   std::string preconditioning;
 
 private:
   /**
-   * Matrix that is used for the
-   * matrix-builtin preconditioning function.
-   * cf. also @p PreconditionUseMatrix.
+   * Matrix that is used for the matrix-builtin preconditioning function. cf.
+   * also @p PreconditionUseMatrix.
    */
   SmartPointer<const MATRIX,PreconditionSelector<MATRIX,VECTOR> > A;
 
   /**
-   * Stores the damping parameter
-   * of the preconditioner.
+   * Stores the damping parameter of the preconditioner.
    */
   const typename VECTOR::value_type omega;
 };
index 54ccf304a332a4eb2fedadcca471451599183718..235bae1065fd097ab1b4ff3cca8ac85123844499 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * @warning The part of the interface based on BlockList may change in
- * future release.
+ * @warning The part of the interface based on BlockList may change in a
+ * future release.
  *
- * Base class for the implementation of overlapping, multiplicative
- * Schwarz relaxation methods and smoothers.
+ * Base class for the implementation of overlapping, multiplicative Schwarz
+ * relaxation methods and smoothers.
  *
- * This class uses the infrastructure provided by
- * PreconditionBlockBase. It adds functions to initialize with a block
- * list and to do the relaxation step. The actual relaxation method
- * with the interface expected by SolverRelaxation and
- * MGSmootherRelaxation is in the derived classes.
+ * This class uses the infrastructure provided by PreconditionBlockBase. It
+ * adds functions to initialize with a block list and to do the relaxation
+ * step. The actual relaxation method with the interface expected by
+ * SolverRelaxation and MGSmootherRelaxation is in the derived classes.
  *
  * This class allows for more general relaxation methods than
- * PreconditionBlock, since the index sets may be arbitrary and
- * overlapping, while there only contiguous, disjoint sets of equal
- * size are allowed. As a drawback, this class cannot be used as a
- * preconditioner, since its implementation relies on a straight
- * forward implementation of the Gauss-Seidel process.
+ * PreconditionBlock, since the index sets may be arbitrary and overlapping,
+ * while there only contiguous, disjoint sets of equal size are allowed. As a
+ * drawback, this class cannot be used as a preconditioner, since its
+ * implementation relies on a straight forward implementation of the Gauss-
+ * Seidel process.
  *
  * @ingroup Preconditioners
  * @author Guido Kanschat
@@ -110,31 +109,29 @@ public:
     typename PreconditionBlockBase<inverse_type>::Inversion inversion;
 
     /**
-     * The if #inversion is SVD, the threshold below which a singular
-     * value will be considered zero and thus not inverted. This
-     * parameter is used in the call to
-     * LAPACKFullMatrix::compute_inverse_svd().
+     * The if #inversion is SVD, the threshold below which a singular value
+     * will be considered zero and thus not inverted. This parameter is used
+     * in the call to LAPACKFullMatrix::compute_inverse_svd().
      */
     double threshold;
 
     /**
-     * The order in which blocks should be traversed. This vector can
-     * initiate several modes of execution:
+     * The order in which blocks should be traversed. This vector can initiate
+     * several modes of execution:
      *
      * <ol>
      *
-     * <li>If the length of the vector is zero, then the relaxation
-     * method will be executed from first to last block.</li>
+     * <li>If the length of the vector is zero, then the relaxation method
+     * will be executed from first to last block.</li>
      *
-     * <li> If the length is one, then the inner vector must have the
-     * same size as the number of blocks. The relaxation method is
-     * applied in the order given in this vector.</li>
+     * <li> If the length is one, then the inner vector must have the same
+     * size as the number of blocks. The relaxation method is applied in the
+     * order given in this vector.</li>
      *
-     * <li> If the outer vector has length greater one, then the
-     * relaxation method is applied several times, each time in the
-     * order given by the inner vector of the corresponding
-     * index. This mode can for instance be used for ADI methods and
-     * similar direction sweeps.</li>
+     * <li> If the outer vector has length greater one, then the relaxation
+     * method is applied several times, each time in the order given by the
+     * inner vector of the corresponding index. This mode can for instance be
+     * used for ADI methods and similar direction sweeps.</li>
      *
      * </ol>
      */
@@ -146,20 +143,19 @@ public:
   };
 
   /**
-   * Initialize matrix and block size.  We store the matrix and the
-   * block size in the preconditioner object. In a second step, the
-   * inverses of the diagonal blocks may be computed.
+   * Initialize matrix and block size.  We store the matrix and the block size
+   * in the preconditioner object. In a second step, the inverses of the
+   * diagonal blocks may be computed.
    *
-   * Additionally, a relaxation parameter for derived classes may be
-   * provided.
+   * Additionally, a relaxation parameter for derived classes may be provided.
    */
   void initialize (const MATRIX &A,
                    const AdditionalData &parameters);
 
   /**
    * Deletes the inverse diagonal block matrices if existent, sets the
-   * blocksize to 0, hence leaves the class in the state that it had
-   * directly after calling the constructor.
+   * blocksize to 0, hence leaves the class in the state that it had directly
+   * after calling the constructor.
    */
   void clear();
 
@@ -169,26 +165,26 @@ public:
   bool empty () const;
 
   /**
-   * Read-only access to entries.  This function is only possible if
-   * the inverse diagonal blocks are stored.
+   * Read-only access to entries.  This function is only possible if the
+   * inverse diagonal blocks are stored.
    */
   value_type el(size_type i,
                 size_type j) const;
 
   /**
-   * Stores the inverse of the diagonal blocks in @p inverse. This
-   * costs some additional memory - for DG methods about 1/3 (for
-   * double inverses) or 1/6 (for float inverses) of that used for the
-   * matrix - but it makes the preconditioning much faster.
+   * Stores the inverse of the diagonal blocks in @p inverse. This costs some
+   * additional memory - for DG methods about 1/3 (for double inverses) or 1/6
+   * (for float inverses) of that used for the matrix - but it makes the
+   * preconditioning much faster.
    *
-   * It is not allowed to call this function twice (will produce an
-   * error) before a call of <tt>clear(...)</tt> because at the second
-   * time there already exist the inverse matrices.
+   * It is not allowed to call this function twice (will produce an error)
+   * before a call of <tt>clear(...)</tt> because at the second time there
+   * already exist the inverse matrices.
    *
-   * After this function is called, the lock on the matrix given
-   * through the @p use_matrix function is released, i.e. you may
-   * overwrite of delete it.  You may want to do this in case you use
-   * this matrix to precondition another matrix.
+   * After this function is called, the lock on the matrix given through the
+   * @p use_matrix function is released, i.e. you may overwrite of delete it.
+   * You may want to do this in case you use this matrix to precondition
+   * another matrix.
    */
   void invert_diagblocks();
 
@@ -196,10 +192,10 @@ protected:
   /**
    * Perform one block relaxation step.
    *
-   * Depending on the arguments @p dst and @p pref, this performs an
-   * SOR step (both reference the same vector) of a Jacobi step (both
-   * are different vectors). For the Jacobi step, the calling function
-   * must copy @p dst to @p pref after this.
+   * Depending on the arguments @p dst and @p pref, this performs an SOR step
+   * (both reference the same vector) of a Jacobi step (both are different
+   * vectors). For the Jacobi step, the calling function must copy @p dst to
+   * @p pref after this.
    */
   template <typename number2>
   void do_step (
@@ -208,11 +204,10 @@ protected:
     const Vector<number2> &src,
     const bool backward) const;
   /**
-   * Pointer to the matrix. Make sure that the matrix exists as long
-   * as this class needs it, i.e. until calling @p invert_diagblocks,
-   * or (if the inverse matrices should not be stored) until the last
-   * call of the preconditoining @p vmult function of the derived
-   * classes.
+   * Pointer to the matrix. Make sure that the matrix exists as long as this
+   * class needs it, i.e. until calling @p invert_diagblocks, or (if the
+   * inverse matrices should not be stored) until the last call of the
+   * preconditoining @p vmult function of the derived classes.
    */
   SmartPointer<const MATRIX,RelaxationBlock<MATRIX,inverse_type> > A;
 
@@ -224,16 +219,14 @@ protected:
 
 
 /**
- * Block Jacobi (additive Schwarz) method with possibly overlapping
- * blocks.
+ * Block Jacobi (additive Schwarz) method with possibly overlapping blocks.
  *
  * This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform an additive
- * Schwarz method on the blocks provided in the BlockList of
- * AdditionalData. Differing from PreconditionBlockJacobi, these
- * blocks may be of varying size, non-contiguous, and overlapping. On
- * the other hand, this class does not implement the preconditioner
- * interface expected by Solver objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform an additive Schwarz
+ * method on the blocks provided in the BlockList of AdditionalData. Differing
+ * from PreconditionBlockJacobi, these blocks may be of varying size, non-
+ * contiguous, and overlapping. On the other hand, this class does not
+ * implement the preconditioner interface expected by Solver objects.
  *
  * @ingroup Preconditioners
  * @author Guido Kanschat
@@ -260,8 +253,7 @@ public:
   using typename RelaxationBlock<MATRIX,inverse_type>::AdditionalData;
 
   /**
-   * Make initialization function
-   * publicly available.
+   * Make initialization function publicly available.
    */
   using RelaxationBlock<MATRIX, inverse_type>::initialize;
 
@@ -292,8 +284,8 @@ public:
   using RelaxationBlock<MATRIX, inverse_type>::inverse_svd;
   using PreconditionBlockBase<inverse_type>::log_statistics;
   /**
-    * Perform one step of the Jacobi iteration.
-    */
+   * Perform one step of the Jacobi iteration.
+   */
   template <typename number2>
   void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
 
@@ -314,12 +306,11 @@ public:
  * Block Gauss-Seidel method with possibly overlapping blocks.
  *
  * This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform a
- * multiplicative Schwarz method on the blocks provided in the
- * BlockList of AdditionalData. Differing from PreconditionBlockSOR,
- * these blocks may be of varying size, non-contiguous, and
- * overlapping. On the other hand, this class does not implement the
- * preconditioner interface expected by Solver objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform a multiplicative
+ * Schwarz method on the blocks provided in the BlockList of AdditionalData.
+ * Differing from PreconditionBlockSOR, these blocks may be of varying size,
+ * non-contiguous, and overlapping. On the other hand, this class does not
+ * implement the preconditioner interface expected by Solver objects.
  *
  * @ingroup Preconditioners
  * @author Guido Kanschat
@@ -346,8 +337,7 @@ public:
   using typename RelaxationBlock<MATRIX,inverse_type>::AdditionalData;
 
   /**
-   * Make initialization function
-   * publicly available.
+   * Make initialization function publicly available.
    */
   using RelaxationBlock<MATRIX, inverse_type>::initialize;
 
@@ -395,13 +385,12 @@ public:
  * Symmetric block Gauss-Seidel method with possibly overlapping blocks.
  *
  * This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform a
- * multiplicative Schwarz method on the blocks provided in the
- * BlockList of AdditionalData in symmetric fashion. Differing from
- * PreconditionBlockSSOR, these blocks may be of varying size,
- * non-contiguous, and overlapping. On the other hand, this class does
- * not implement the preconditioner interface expected by Solver
- * objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform a multiplicative
+ * Schwarz method on the blocks provided in the BlockList of AdditionalData in
+ * symmetric fashion. Differing from PreconditionBlockSSOR, these blocks may
+ * be of varying size, non-contiguous, and overlapping. On the other hand,
+ * this class does not implement the preconditioner interface expected by
+ * Solver objects.
  *
  * @ingroup Preconditioners
  * @author Guido Kanschat
index dedbe4ddb3f1752e448b7553d0aee9d7a14d05fc..ee3738ba4f958ea8eebbfe912aaaab1e39c97486 100644 (file)
@@ -34,10 +34,10 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Schur complement of a block matrix.
  *
- * Given a non-singular matrix @p A (often positive definite) and a
- * positive semi-definite matrix @p C as well as matrices @p B and
- * @p Dt of full rank, this class implements a new matrix, the Schur
- * complement a the system of equations of the structure
+ * Given a non-singular matrix @p A (often positive definite) and a positive
+ * semi-definite matrix @p C as well as matrices @p B and @p Dt of full rank,
+ * this class implements a new matrix, the Schur complement a the system of
+ * equations of the structure
  *
  * @verbatim
  * /        \  /   \     /   \
@@ -54,35 +54,34 @@ DEAL_II_NAMESPACE_OPEN
  *
  * The data handed to the Schur matrix are as follows:
  *
- * @p A: the inverse of @p A is stored, instead of @p A. This
- * allows the application to use the most efficient form of inversion,
- * iterative or direct.
+ * @p A: the inverse of @p A is stored, instead of @p A. This allows the
+ * application to use the most efficient form of inversion, iterative or
+ * direct.
  *
  * @p B, @p C: these matrices are stored "as is".
  *
- * @p Dt: the computation of the Schur complement involves the
- * function @p Tvmult of the matrix @p Dt, not @p vmult! This way,
- * it is sufficient to build only one matrix @p B for the symmetric
- * Schur complement and use it twice.
+ * @p Dt: the computation of the Schur complement involves the function @p
+ * Tvmult of the matrix @p Dt, not @p vmult! This way, it is sufficient to
+ * build only one matrix @p B for the symmetric Schur complement and use it
+ * twice.
  *
- * All matrices involved are of arbitrary type and vectors are
- * BlockVectors. This way, @p SchurMatrix can be coupled with
- * any matrix classes providing @p vmult and @p Tvmult and can be
- * even nested. Since SmartPointers of matrices are stored, the
- * matrix blocks should be derived from Subscriptor.
+ * All matrices involved are of arbitrary type and vectors are BlockVectors.
+ * This way, @p SchurMatrix can be coupled with any matrix classes providing
+ * @p vmult and @p Tvmult and can be even nested. Since SmartPointers of
+ * matrices are stored, the matrix blocks should be derived from Subscriptor.
  *
- * Since the Schur complement of a matrix corresponds to a Gaussian
- * block elimination, the right hand side of the condensed system must
- * be preprocessed. Furthermore, the eliminated variable must be
- * reconstructed after solving.
+ * Since the Schur complement of a matrix corresponds to a Gaussian block
+ * elimination, the right hand side of the condensed system must be
+ * preprocessed. Furthermore, the eliminated variable must be reconstructed
+ * after solving.
  *
  * @verbatim
  *   g = g + B A-inverse f
  *   u = A-inverse (f - D-transpose p)
  * @endverbatim
  *
- * Applying these transformations, the solution of the system above by a
- * @p SchurMatrix @p schur is coded as follows:
+ * Applying these transformations, the solution of the system above by a @p
+ * SchurMatrix @p schur is coded as follows:
  *
  * @code
  *   schur.prepare_rhs (g, f);
@@ -99,17 +98,13 @@ class SchurMatrix : public Subscriptor
 public:
 
   /**
-   * Constructor. This constructor
-   * receives all the matrices
-   * needed. Furthermore, it gets a
-   * reference to a memory structure
-   * for obtaining block vectors.
+   * Constructor. This constructor receives all the matrices needed.
+   * Furthermore, it gets a reference to a memory structure for obtaining
+   * block vectors.
    *
-   * Optionally, the length of the
-   * @p u-vector can be provided.
+   * Optionally, the length of the @p u-vector can be provided.
    *
-   * For the meaning of the matrices
-   * see the class documentation.
+   * For the meaning of the matrices see the class documentation.
    */
   SchurMatrix(const MA_inverse &Ainv,
               const MB &B,
@@ -119,29 +114,20 @@ public:
               const std::vector<unsigned int> &signature = std::vector<unsigned int>(0));
 
   /**
-   * Do block elimination of the
-   * right hand side. Given right
-   * hand sides for both components
-   * of the block system, this
-   * function provides the right hand
-   * side for the Schur complement.
+   * Do block elimination of the right hand side. Given right hand sides for
+   * both components of the block system, this function provides the right
+   * hand side for the Schur complement.
    *
-   * The result is stored in the
-   * first argument, which is also
-   * part of the input data. If it is
-   * necessary to conserve the data,
-   * @p dst must be copied before
-   * calling this function. This is
-   * reasonable, since in many cases,
-   * only the pre-processed right
-   * hand side is needed.
+   * The result is stored in the first argument, which is also part of the
+   * input data. If it is necessary to conserve the data, @p dst must be
+   * copied before calling this function. This is reasonable, since in many
+   * cases, only the pre-processed right hand side is needed.
    */
   void prepare_rhs (BlockVector<double> &dst,
                     const BlockVector<double> &src) const;
 
   /**
-   * Multiplication with the Schur
-   * complement.
+   * Multiplication with the Schur complement.
    */
   void vmult (BlockVector<double> &dst,
               const BlockVector<double> &src) const;
@@ -149,29 +135,24 @@ public:
 //  void Tmult(BlockVector<double>& dst, const BlockVector<double>& src) const;
 
   /**
-   * Computation of the residual of
-   * the Schur complement.
+   * Computation of the residual of the Schur complement.
    */
   double residual (BlockVector<double> &dst,
                    const BlockVector<double> &src,
                    const BlockVector<double> &rhs) const;
 
   /**
-   * Compute the eliminated variable
-   * from the solution of the Schur
-   * complement problem.
+   * Compute the eliminated variable from the solution of the Schur complement
+   * problem.
    */
   void postprocess (BlockVector<double> &dst,
                     const BlockVector<double> &src,
                     const BlockVector<double> &rhs) const;
 
   /**
-   * Select debugging information for
-   * log-file.  Debug level 1 is
-   * defined and writes the norm of
-   * every vector before and after
-   * each operation. Debug level 0
-   * turns off debugging information.
+   * Select debugging information for log-file.  Debug level 1 is defined and
+   * writes the norm of every vector before and after each operation. Debug
+   * level 0 turns off debugging information.
    */
   void debug_level(unsigned int l);
 private:
index 9f26365432a7e53e7ef027f7bd57377edaeef81e..a2804fa57b3a76398964f26f2c83e52f83c65f0d 100644 (file)
@@ -29,9 +29,8 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Matrix with shifted diagonal values.
  *
- * Given a matrix <tt>A</tt>, this class implements a matrix-vector
- * product with <i>A+s I</i>, where <i>s</i> is a provided shift
- * parameter.
+ * Given a matrix <tt>A</tt>, this class implements a matrix-vector product
+ * with <i>A+s I</i>, where <i>s</i> is a provided shift parameter.
  *
  * @author Guido Kanschat, 2000, 2001
  */
@@ -40,8 +39,7 @@ class ShiftedMatrix
 {
 public:
   /**
-   * Constructor.  Provide the base
-   * matrix and a shift parameter.
+   * Constructor.  Provide the base matrix and a shift parameter.
    */
   ShiftedMatrix (const MATRIX &A, const double sigma);
 
@@ -86,7 +84,8 @@ private:
 
 
 /**
- * Matrix with shifted diagonal values with respect to a certain scalar product.
+ * Matrix with shifted diagonal values with respect to a certain scalar
+ * product.
  *
  * Given a matrix <tt>A</tt>, this class implements a matrix-vector product
  * with <i>A+s M</i>, where <i>s</i> is a provided shift parameter and
@@ -99,8 +98,7 @@ class ShiftedMatrixGeneralized
 {
 public:
   /**
-   * Constructor.
-   * Provide the base matrix and a shift parameter.
+   * Constructor. Provide the base matrix and a shift parameter.
    */
   ShiftedMatrixGeneralized (const MATRIX &A,
                             const MASSMATRIX &M,
index c84c4cdb53b8494d21020d8d0ebe2f44dcaa3b70..fc589ebf758a6a3dde23b56cd04327d79b1735af 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Base class for solver classes using the SLEPc solvers which are
- * selected based on flags passed to the eigenvalue problem solver
- * context. Derived classes set the right flags to set the right
- * solver. Note that: the <code>AdditionalData</code> structure is a
- * dummy structure that currently exists for backward/forward
- * compatibility only.
+ * Base class for solver classes using the SLEPc solvers which are selected
+ * based on flags passed to the eigenvalue problem solver context. Derived
+ * classes set the right flags to set the right solver. Note that: the
+ * <code>AdditionalData</code> structure is a dummy structure that currently
+ * exists for backward/forward compatibility only.
  *
- * The SLEPc solvers are intended to be used for solving the
- * generalized eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$;
- * where $A$ is a system matrix, $B$ is a mass matrix, and $\lambda,
- * x$ are a set of eigenvalues and eigenvectors respectively. The
- * emphasis is on methods and techniques appropriate for problems in
- * which the associated matrices are sparse. Most of the methods
- * offered by the SLEPc library are projection methods or other
- * methods with similar properties; and wrappers are provided to
- * interface to SLEPc solvers that handle both of these problem sets.
+ * The SLEPc solvers are intended to be used for solving the generalized
+ * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
+ * system matrix, $B$ is a mass matrix, and $\lambda, x$ are a set of
+ * eigenvalues and eigenvectors respectively. The emphasis is on methods and
+ * techniques appropriate for problems in which the associated matrices are
+ * sparse. Most of the methods offered by the SLEPc library are projection
+ * methods or other methods with similar properties; and wrappers are provided
+ * to interface to SLEPc solvers that handle both of these problem sets.
  *
- * SLEPcWrappers can be implemented in application codes in the
- * following way:
+ * SLEPcWrappers can be implemented in application codes in the following way:
  * @code
  *  SolverControl solver_control (1000, 1e-9);
  *  SolverArnoldi system (solver_control, mpi_communicator);
  *  system.solve (A, B, lambda, x, size_of_spectrum);
  * @endcode
- * for the generalized eigenvalue problem $Ax=B\lambda x$, where the
- * variable <code>const unsigned int size_of_spectrum</code> tells
- * SLEPc the number of eigenvector/eigenvalue pairs to solve
- * for. Additional options and solver parameters can be passed to the
- * SLEPc solvers before calling <code>solve()</code>. For example, if
- * the matrices of the general eigenspectrum problem are not hermitian
- * and the lower eigenvalues are wanted only, the following code can
- * be implemented before calling <code>solve()</code>:
+ * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
+ * <code>const unsigned int size_of_spectrum</code> tells SLEPc the number of
+ * eigenvector/eigenvalue pairs to solve for. Additional options and solver
+ * parameters can be passed to the SLEPc solvers before calling
+ * <code>solve()</code>. For example, if the matrices of the general
+ * eigenspectrum problem are not hermitian and the lower eigenvalues are
+ * wanted only, the following code can be implemented before calling
+ * <code>solve()</code>:
  * @code
  *  system.set_problem_type (EPS_NHEP);
  *  system.set_which_eigenpairs (EPS_SMALLEST_REAL);
@@ -74,46 +71,45 @@ DEAL_II_NAMESPACE_OPEN
  *
  * See also <code>step-36</code> for a hands-on example.
  *
- * An alternative implementation to the one above is to use the API
- * internals directly within the application code. In this way the
- * calling sequence requires calling several of SolverBase functions
- * rather than just one. This freedom is intended for use of the
- * SLEPcWrappers that require a greater handle on the eigenvalue
- * problem solver context. See also the API of, for example:
- @code
-  template <typename OutputVector>
-  void
-  SolverBase::solve (const PETScWrappers::MatrixBase &A,
                    const PETScWrappers::MatrixBase &B,
                    std::vector<PetscScalar>        &eigenvalues,
                    std::vector<OutputVector>       &eigenvectors,
                    const unsigned int               n_eigenpairs)
-  { ... }
- @endcode
+ * An alternative implementation to the one above is to use the API internals
+ * directly within the application code. In this way the calling sequence
+ * requires calling several of SolverBase functions rather than just one. This
+ * freedom is intended for use of the SLEPcWrappers that require a greater
+ * handle on the eigenvalue problem solver context. See also the API of, for
+ * example:
@code
* template <typename OutputVector>
* void
* SolverBase::solve (const PETScWrappers::MatrixBase &A,
*                   const PETScWrappers::MatrixBase &B,
*                   std::vector<PetscScalar>        &eigenvalues,
*                   std::vector<OutputVector>       &eigenvectors,
*                   const unsigned int               n_eigenpairs)
* { ... }
@endcode
  * as an example on how to do this.
  *
- * For further information and explanations on handling the @ref
- * SLEPcWrappers "SLEPcWrappers", see also the @ref PETScWrappers
- * "PETScWrappers", on which they depend.
+ * For further information and explanations on handling the @ref SLEPcWrappers
+ * "SLEPcWrappers", see also the @ref PETScWrappers "PETScWrappers", on which
+ * they depend.
  *
  * @ingroup SLEPcWrappers
  *
- * @author Toby D. Young 2008, 2009, 2010, 2011, 2013; and Rickard
- * Armiento 2008.
+ * @author Toby D. Young 2008, 2009, 2010, 2011, 2013; and Rickard Armiento
+ * 2008.
  *
- * @note Various tweaks and enhancments contributed by Eloy Romero and
- * Jose E. Roman 2009, 2010.
+ * @note Various tweaks and enhancments contributed by Eloy Romero and Jose E.
+ * Roman 2009, 2010.
  */
 namespace SLEPcWrappers
 {
 
   /**
-   * Base class for solver classes using the SLEPc solvers. Since
-   * solvers in SLEPc are selected based on flags passed to a generic
-   * solver object, basically all the actual solver calls happen in
-   * this class, and derived classes simply set the right flags to
-   * select one solver or another, or to set certain parameters for
-   * individual solvers.
+   * Base class for solver classes using the SLEPc solvers. Since solvers in
+   * SLEPc are selected based on flags passed to a generic solver object,
+   * basically all the actual solver calls happen in this class, and derived
+   * classes simply set the right flags to select one solver or another, or to
+   * set certain parameters for individual solvers.
    */
   class SolverBase
   {
@@ -131,24 +127,22 @@ namespace SLEPcWrappers
     virtual ~SolverBase ();
 
     /**
-     * Composite method that solves the eigensystem $Ax=\lambda
-     * x$. The eigenvector sent in has to have at least one element
-     * that we can use as a template when resizing, since we do not
-     * know the parameters of the specific vector class used
-     * (i.e. local_dofs for MPI vectors). However, while copying
-     * eigenvectors, at least twice the memory size of
-     * <tt>eigenvectors</tt> is being used (and can be more). To avoid
-     * doing this, the fairly standard calling sequence executed here
-     * is used: Initialise; Set up matrices for solving; Actually
-     * solve the system; Gather the solution(s); and reset.
+     * Composite method that solves the eigensystem $Ax=\lambda x$. The
+     * eigenvector sent in has to have at least one element that we can use as
+     * a template when resizing, since we do not know the parameters of the
+     * specific vector class used (i.e. local_dofs for MPI vectors). However,
+     * while copying eigenvectors, at least twice the memory size of
+     * <tt>eigenvectors</tt> is being used (and can be more). To avoid doing
+     * this, the fairly standard calling sequence executed here is used:
+     * Initialise; Set up matrices for solving; Actually solve the system;
+     * Gather the solution(s); and reset.
      *
-     * @note Note that the number of converged eigenvectors can be
-     * larger than the number of eigenvectors requested; this is due
-     * to a round off error (success) of the eigenproblem solver
-     * context. If this is found to be the case we simply do not
-     * bother with more eigenpairs than requested, but handle that it
-     * may be more than specified by ignoring any extras. By default
-     * one eigenvector/eigenvalue pair is computed.
+     * @note Note that the number of converged eigenvectors can be larger than
+     * the number of eigenvectors requested; this is due to a round off error
+     * (success) of the eigenproblem solver context. If this is found to be
+     * the case we simply do not bother with more eigenpairs than requested,
+     * but handle that it may be more than specified by ignoring any extras.
+     * By default one eigenvector/eigenvalue pair is computed.
      */
     template <typename OutputVector>
     void
@@ -158,9 +152,9 @@ namespace SLEPcWrappers
            const unsigned int               n_eigenpairs = 1);
 
     /**
-     * Same as above, but here a composite method for solving the
-     * system $A x=\lambda B x$, for real matrices, vectors, and
-     * values $A, B, x, \lambda$.
+     * Same as above, but here a composite method for solving the system $A
+     * x=\lambda B x$, for real matrices, vectors, and values $A, B, x,
+     * \lambda$.
      */
     template <typename OutputVector>
     void
@@ -171,9 +165,9 @@ namespace SLEPcWrappers
            const unsigned int               n_eigenpairs = 1);
 
     /**
-     * Same as above, but here a composite method for solving the
-     * system $A x=\lambda B x$ with real matrices $A, B$ and
-     * imaginary eigenpairs $x, \lambda$.
+     * Same as above, but here a composite method for solving the system $A
+     * x=\lambda B x$ with real matrices $A, B$ and imaginary eigenpairs $x,
+     * \lambda$.
      */
     template <typename OutputVector>
     void
@@ -199,15 +193,15 @@ namespace SLEPcWrappers
     set_transformation (SLEPcWrappers::TransformationBase &this_transformation);
 
     /**
-     * Set target eigenvalues in the spectrum to be computed. By
-     * default, no target is set.
+     * Set target eigenvalues in the spectrum to be computed. By default, no
+     * target is set.
      */
     void
     set_target_eigenvalue (const PetscScalar &this_target);
 
     /**
-     * Indicate which part of the spectrum is to be computed. By
-     * default largest magnitude eigenvalues are computed.
+     * Indicate which part of the spectrum is to be computed. By default
+     * largest magnitude eigenvalues are computed.
      *
      * @note For other allowed values see the SLEPc documentation.
      */
@@ -215,10 +209,10 @@ namespace SLEPcWrappers
     set_which_eigenpairs (EPSWhich set_which);
 
     /**
-     * Specify the type of the eigenspectrum problem. This can be used
-     * to exploit known symmetries of the matrices that make up the
-     * standard/generalized eigenspectrum problem.  By default a
-     * non-Hermitian problem is assumed.
+     * Specify the type of the eigenspectrum problem. This can be used to
+     * exploit known symmetries of the matrices that make up the
+     * standard/generalized eigenspectrum problem.  By default a non-Hermitian
+     * problem is assumed.
      *
      * @note For other allowed values see the SLEPc documentation.
      */
@@ -227,8 +221,8 @@ namespace SLEPcWrappers
 
     /**
      * Take the information provided from SLEPc and checks it against
-     * deal.II's own SolverControl objects to see if convergence has
-     * been reached.
+     * deal.II's own SolverControl objects to see if convergence has been
+     * reached.
      */
     void
     get_solver_state (const SolverControl::State state);
@@ -262,8 +256,8 @@ namespace SLEPcWrappers
   protected:
 
     /**
-     * Reference to the object that controls convergence of the
-     * iterative solver.
+     * Reference to the object that controls convergence of the iterative
+     * solver.
      */
     SolverControl &solver_control;
 
@@ -273,9 +267,8 @@ namespace SLEPcWrappers
     const MPI_Comm mpi_communicator;
 
     /**
-     * Function that takes an Eigenvalue Problem Solver context
-     * object, and sets the type of solver that is requested by the
-     * derived class.
+     * Function that takes an Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is requested by the derived class.
      */
     virtual void set_solver_type (EPS &eps) const = 0;
 
@@ -291,19 +284,18 @@ namespace SLEPcWrappers
     EPS *get_eps ();
 
     /**
-     * Solve the linear system for <code>n_eigenpairs</code>
-     * eigenstates. Parameter <code>n_converged</code> contains the
-     * actual number of eigenstates that have  converged; this can
-     * be both fewer or more than n_eigenpairs, depending on the
-     * SLEPc eigensolver used.
+     * Solve the linear system for <code>n_eigenpairs</code> eigenstates.
+     * Parameter <code>n_converged</code> contains the actual number of
+     * eigenstates that have  converged; this can be both fewer or more than
+     * n_eigenpairs, depending on the SLEPc eigensolver used.
      */
     void
     solve (const unsigned int n_eigenpairs,
            unsigned int *n_converged);
 
     /**
-     * Access the real parts of solutions for a solved eigenvector
-     * problem, pair index solutions, $\text{index}\,\in\,0\hdots
+     * Access the real parts of solutions for a solved eigenvector problem,
+     * pair index solutions, $\text{index}\,\in\,0\hdots
      * \text{n\_converged}-1$.
      */
     void
@@ -313,8 +305,8 @@ namespace SLEPcWrappers
 
     /**
      * Access the real and imaginary parts of solutions for a solved
-     * eigenvector problem, pair index solutions,
-     * $\text{index}\,\in\,0\hdots \text{n\_converged}-1$.
+     * eigenvector problem, pair index solutions, $\text{index}\,\in\,0\hdots
+     * \text{n\_converged}-1$.
      */
     void
     get_eigenpair (const unsigned int         index,
@@ -324,15 +316,15 @@ namespace SLEPcWrappers
                    PETScWrappers::VectorBase &imag_eigenvectors);
 
     /**
-     * Initialize solver for the linear system $Ax=\lambda x$. (Note:
-     * this is required before calling solve ())
+     * Initialize solver for the linear system $Ax=\lambda x$. (Note: this is
+     * required before calling solve ())
      */
     void
     set_matrices (const PETScWrappers::MatrixBase &A);
 
     /**
-     * Same as above, but here initialize solver for the linear system
-     * $A x=\lambda B x$.
+     * Same as above, but here initialize solver for the linear system $A
+     * x=\lambda B x$.
      */
     void
     set_matrices (const PETScWrappers::MatrixBase &A,
@@ -356,15 +348,13 @@ namespace SLEPcWrappers
   private:
 
     /**
-     * The matrix $A$ of the generalized eigenvalue problem
-     * $Ax=B\lambda x$, or the standard eigenvalue problem $Ax=\lambda
-     * x$.
+     * The matrix $A$ of the generalized eigenvalue problem $Ax=B\lambda x$,
+     * or the standard eigenvalue problem $Ax=\lambda x$.
      */
     const PETScWrappers::MatrixBase *opA;
 
     /**
-     * The matrix $B$ of the generalized eigenvalue problem
-     * $Ax=B\lambda x$.
+     * The matrix $B$ of the generalized eigenvalue problem $Ax=B\lambda x$.
      */
     const PETScWrappers::MatrixBase *opB;
 
@@ -374,8 +364,8 @@ namespace SLEPcWrappers
     const PETScWrappers::VectorBase *initial_vector;
 
     /**
-     * Pointer to an an object that describes transformations that can
-     * be applied to the eigenvalue problem.
+     * Pointer to an an object that describes transformations that can be
+     * applied to the eigenvalue problem.
      */
     SLEPcWrappers::TransformationBase *transformation;
 
@@ -395,12 +385,11 @@ namespace SLEPcWrappers
                       void        *solver_control);
 
     /**
-     * Objects of this type are explicitly created, but are destroyed
-     * when the surrounding solver object goes out of scope, or when
-     * we assign a new value to the pointer to this object. The
-     * respective Destroy functions are therefore written into the
-     * destructor of this object, even though the object does not have
-     * a constructor.
+     * Objects of this type are explicitly created, but are destroyed when the
+     * surrounding solver object goes out of scope, or when we assign a new
+     * value to the pointer to this object. The respective Destroy functions
+     * are therefore written into the destructor of this object, even though
+     * the object does not have a constructor.
      */
     struct SolverData
     {
@@ -428,9 +417,8 @@ namespace SLEPcWrappers
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc
-   * Krylov-Schur solver. Usage: All spectrum, all problem types,
-   * complex.
+   * An implementation of the solver interface using the SLEPc Krylov-Schur
+   * solver. Usage: All spectrum, all problem types, complex.
    *
    * @ingroup SLEPcWrappers
    *
@@ -441,17 +429,16 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverKrylovSchur (SolverControl        &cn,
                        const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -465,15 +452,15 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc Arnoldi
-   * solver. Usage: All spectrum, all problem types, complex.
+   * An implementation of the solver interface using the SLEPc Arnoldi solver.
+   * Usage: All spectrum, all problem types, complex.
    *
    * @ingroup SLEPcWrappers
    *
@@ -483,8 +470,8 @@ namespace SLEPcWrappers
   {
   public:
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {
@@ -501,10 +488,9 @@ namespace SLEPcWrappers
     };
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverArnoldi (SolverControl        &cn,
                    const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -518,15 +504,15 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc Lanczos
-   * solver. Usage: All spectrum, all problem types, complex.
+   * An implementation of the solver interface using the SLEPc Lanczos solver.
+   * Usage: All spectrum, all problem types, complex.
    *
    * @ingroup SLEPcWrappers
    *
@@ -536,17 +522,16 @@ namespace SLEPcWrappers
   {
   public:
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverLanczos (SolverControl        &cn,
                    const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -560,16 +545,15 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc Power
-   * solver. Usage: Largest values of spectrum only, all problem
-   * types, complex.
+   * An implementation of the solver interface using the SLEPc Power solver.
+   * Usage: Largest values of spectrum only, all problem types, complex.
    *
    * @ingroup SLEPcWrappers
    *
@@ -579,17 +563,16 @@ namespace SLEPcWrappers
   {
   public:
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverPower (SolverControl        &cn,
                  const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -603,15 +586,15 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc
-   * Davidson solver. Usage (incomplete/untested): All problem types.
+   * An implementation of the solver interface using the SLEPc Davidson
+   * solver. Usage (incomplete/untested): All problem types.
    *
    * @ingroup SLEPcWrappers
    *
@@ -621,17 +604,16 @@ namespace SLEPcWrappers
   {
   public:
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverGeneralizedDavidson (SolverControl        &cn,
                                const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -645,15 +627,15 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   /**
-   * An implementation of the solver interface using the SLEPc
-   * Jacobi-Davidson solver. Usage: All problem types.
+   * An implementation of the solver interface using the SLEPc Jacobi-Davidson
+   * solver. Usage: All problem types.
    *
    * @ingroup SLEPcWrappers
    *
@@ -663,17 +645,16 @@ namespace SLEPcWrappers
   {
   public:
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverJacobiDavidson (SolverControl        &cn,
                           const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -687,16 +668,16 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
 
   /**
-   * An implementation of the solver interface using the SLEPc LAPACK
-   * direct solver.
+   * An implementation of the solver interface using the SLEPc LAPACK direct
+   * solver.
    *
    * @ingroup SLEPcWrappers
    *
@@ -707,17 +688,16 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to pipe additional data to the solver,
-     * should it be needed.
+     * Standardized data struct to pipe additional data to the solver, should
+     * it be needed.
      */
     struct AdditionalData
     {};
 
     /**
-     * SLEPc solvers will want to have an MPI communicator context
-     * over which computations are parallelized. By default, this
-     * carries the same behaviour has the PETScWrappers, but you can
-     * change that.
+     * SLEPc solvers will want to have an MPI communicator context over which
+     * computations are parallelized. By default, this carries the same
+     * behaviour has the PETScWrappers, but you can change that.
      */
     SolverLAPACK (SolverControl        &cn,
                   const MPI_Comm       &mpi_communicator = PETSC_COMM_SELF,
@@ -731,16 +711,16 @@ namespace SLEPcWrappers
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Eigenvalue Problem Solver context object,
-     * and sets the type of solver that is appropriate for this class.
+     * Function that takes a Eigenvalue Problem Solver context object, and
+     * sets the type of solver that is appropriate for this class.
      */
     virtual void set_solver_type (EPS &eps) const;
   };
 
   // --------------------------- inline and template functions -----------
   /**
-   * This is declared here to make it possible to take a std::vector
-   * of different PETScWrappers vector types
+   * This is declared here to make it possible to take a std::vector of
+   * different PETScWrappers vector types
    */
   // todo: The logic of these functions can be simplified without breaking backward compatibility...
 
index 6bf9a4c13bed0eb317b00c78c8e7498b23444f27..05ff466946fe1d4f49e7fd78d2b6eff8a449e258 100644 (file)
@@ -35,15 +35,13 @@ namespace SLEPcWrappers
 {
 
   /**
-   * Base class for spectral transformation classes using the SLEPc
-   * solvers which are selected based on flags passed to the spectral
-   * transformation.
+   * Base class for spectral transformation classes using the SLEPc solvers
+   * which are selected based on flags passed to the spectral transformation.
    *
-   * <code>SLEPcWrappers::TransformationXXX</code>, where
-   * <code>XXX</code> is your favourite transformation type, can then
-   * be implemented in application codes in the following way for
-   * <code>XXX=INVERT</code> with the solver object
-   * <code>eigensolver</code>:
+   * <code>SLEPcWrappers::TransformationXXX</code>, where <code>XXX</code> is
+   * your favourite transformation type, can then be implemented in
+   * application codes in the following way for <code>XXX=INVERT</code> with
+   * the solver object <code>eigensolver</code>:
    * @code
    *  // Set a transformation, this one shifts the eigenspectrum by 3.142..
    *  SLEPcWrappers::TransformationShift::AdditionalData additional_data (3.142);
@@ -61,7 +59,7 @@ namespace SLEPcWrappers
    *
    * @ingroup SLEPcWrappers
    * @author Toby D. Young 2009, 2013
-   **/
+   */
   class TransformationBase
   {
   public:
@@ -77,19 +75,17 @@ namespace SLEPcWrappers
     virtual ~TransformationBase ();
 
     /**
-     * Record the EPS object that is associated
-     * to the spectral transformation
+     * Record the EPS object that is associated to the spectral transformation
      */
     void set_context (EPS &eps);
 
     /**
-     * Set a flag to indicate how the
-     * transformed matrices are being stored in
+     * Set a flag to indicate how the transformed matrices are being stored in
      * the spectral transformations.
      *
-     * The possible values are given by the
-     * enumerator STMatMode in the SLEPc library
-     * http://www.grycap.upv.es/slepc/documentation/current/docs/manualpages/ST/STMatMode.html
+     * The possible values are given by the enumerator STMatMode in the SLEPc
+     * library http://www.grycap.upv.es/slepc/documentation/current/docs/manua
+     * lpages/ST/STMatMode.html
      */
     void set_matrix_mode(const STMatMode mode);
 
@@ -100,17 +96,11 @@ namespace SLEPcWrappers
   private:
 
     /**
-     * Objects of this type are
-     * explicitly created, but are
-     * destroyed when the surrounding
-     * solver object goes out of scope,
-     * or when we assign a new value to
-     * the pointer to this object. The
-     * respective Destroy functions are
-     * therefore written into the
-     * destructor of this object, even
-     * though the object does not have
-     * a constructor.
+     * Objects of this type are explicitly created, but are destroyed when the
+     * surrounding solver object goes out of scope, or when we assign a new
+     * value to the pointer to this object. The respective Destroy functions
+     * are therefore written into the destructor of this object, even though
+     * the object does not have a constructor.
      */
     struct TransformationData
     {
@@ -121,8 +111,7 @@ namespace SLEPcWrappers
       ~TransformationData ();
 
       /**
-       * Objects for Eigenvalue Problem
-       * Solver.
+       * Objects for Eigenvalue Problem Solver.
        */
       ST st;
     };
@@ -133,8 +122,7 @@ namespace SLEPcWrappers
   };
 
   /**
-   * An implementation of the transformation interface using the SLEPc
-   * Shift.
+   * An implementation of the transformation interface using the SLEPc Shift.
    *
    * @ingroup SLEPcWrappers
    * @author Toby D. Young 2009
@@ -144,16 +132,13 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
 
       /**
-       * Constructor. By default, set the
-       * shift parameter to zero.
+       * Constructor. By default, set the shift parameter to zero.
        */
       AdditionalData (const double shift_parameter = 0);
 
@@ -173,24 +158,20 @@ namespace SLEPcWrappers
   protected:
 
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Spectral
-     * Transformation context object,
-     * and sets the type of spectral
-     * transformationthat is
-     * appropriate for this class.
+     * Function that takes a Spectral Transformation context object, and sets
+     * the type of spectral transformationthat is appropriate for this class.
      */
     virtual void set_transformation_type (ST &st) const;
   };
 
   /**
-   * An implementation of the transformation interface using the SLEPc
-   * Shift and Invert.
+   * An implementation of the transformation interface using the SLEPc Shift
+   * and Invert.
    *
    * @ingroup SLEPcWrappers
    * @author Toby D. Young 2009
@@ -200,15 +181,12 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default, set the
-       * shift parameter to zero.
+       * Constructor. By default, set the shift parameter to zero.
        */
       AdditionalData (const double shift_parameter = 0);
 
@@ -227,25 +205,21 @@ namespace SLEPcWrappers
   protected:
 
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Spectral
-     * Transformation context object,
-     * and sets the type of spectral
-     * transformationthat is
-     * appropriate for this class.
+     * Function that takes a Spectral Transformation context object, and sets
+     * the type of spectral transformationthat is appropriate for this class.
      */
     virtual void set_transformation_type (ST &st) const;
   };
 
   /**
    * An implementation of the transformation interface using the SLEPc
-   * Spectrum Folding. This transformation type has been removed in
-   * SLEPc 3.5.0 and thus cannot be used in the newer versions.
+   * Spectrum Folding. This transformation type has been removed in SLEPc
+   * 3.5.0 and thus cannot be used in the newer versions.
    *
    * @ingroup SLEPcWrappers
    * @author Toby D. Young 2009
@@ -255,15 +229,12 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. By default, set the
-       * shift parameter to zero.
+       * Constructor. By default, set the shift parameter to zero.
        */
       AdditionalData (const double shift_parameter = 0);
 
@@ -282,24 +253,19 @@ namespace SLEPcWrappers
   protected:
 
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Spectral
-     * Transformation context object,
-     * and sets the type of spectral
-     * transformationthat is
-     * appropriate for this class.
+     * Function that takes a Spectral Transformation context object, and sets
+     * the type of spectral transformationthat is appropriate for this class.
      */
     virtual void set_transformation_type (ST &st) const;
   };
 
   /**
-   * An implementation of the transformation interface using the SLEPc
-   * Cayley.
+   * An implementation of the transformation interface using the SLEPc Cayley.
    *
    * @ingroup SLEPcWrappers
    * @author Toby D. Young 2009
@@ -309,14 +275,12 @@ namespace SLEPcWrappers
   public:
 
     /**
-     * Standardized data struct to pipe
-     * additional data to the solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
     struct AdditionalData
     {
       /**
-       * Constructor. Requires two shift
-       * parameters
+       * Constructor. Requires two shift parameters
        */
       AdditionalData (const double shift_parameter     = 0,
                       const double antishift_parameter = 0);
@@ -338,17 +302,13 @@ namespace SLEPcWrappers
   protected:
 
     /**
-     * Store a copy of the flags for this
-     * particular solver.
+     * Store a copy of the flags for this particular solver.
      */
     const AdditionalData additional_data;
 
     /**
-     * Function that takes a Spectral
-     * Transformation context object,
-     * and sets the type of spectral
-     * transformationthat is
-     * appropriate for this class.
+     * Function that takes a Spectral Transformation context object, and sets
+     * the type of spectral transformationthat is appropriate for this class.
      */
     virtual void set_transformation_type (ST &st) const;
   };
index 8bcd2344ec903e9085dd4fe5e99fe5860bb588ec..df14ed30553e66422a9062eba6d3d49ec6f6e051 100644 (file)
@@ -28,29 +28,28 @@ DEAL_II_NAMESPACE_OPEN
 template <typename number> class Vector;
 
 /**
- * A base class for iterative linear solvers. This class
- * provides interfaces to a memory pool and the objects that
- * determine whether a solver has converged.
+ * A base class for iterative linear solvers. This class provides interfaces
+ * to a memory pool and the objects that determine whether a solver has
+ * converged.
  *
  *
  * <h3>Requirements common to derived solver classes</h3>
  *
- * Since iterative solvers do not rely on any special structure of
- * matrices or the format of storage but only require that matrices
- * and vectors define certain operations such as matrix-vector
- * products, or scalar products between vectors, this class as well as
- * the derived classes and their member functions implementing concrete
- * linear solvers are templated on the types of matrices and vectors.
- * However, there are some common requirements a matrix or vector type
- * must fulfill to qualify as an acceptable type for the solvers in this
- * hierarchy. These requirements are listed below.
- *
- * The classes we show below are not any concrete class. Rather, they are intended to
- * form a `signature' which a concrete class has to conform to. Note
- * that the matrix and vector classes within this library of course
- * conform to this interface; therefore, SparseMatrix and Vector are
- * good examples for these classes as they provide the necessary
- * signatures of member functions.
+ * Since iterative solvers do not rely on any special structure of matrices or
+ * the format of storage but only require that matrices and vectors define
+ * certain operations such as matrix-vector products, or scalar products
+ * between vectors, this class as well as the derived classes and their member
+ * functions implementing concrete linear solvers are templated on the types
+ * of matrices and vectors. However, there are some common requirements a
+ * matrix or vector type must fulfill to qualify as an acceptable type for the
+ * solvers in this hierarchy. These requirements are listed below.
+ *
+ * The classes we show below are not any concrete class. Rather, they are
+ * intended to form a `signature' which a concrete class has to conform to.
+ * Note that the matrix and vector classes within this library of course
+ * conform to this interface; therefore, SparseMatrix and Vector are good
+ * examples for these classes as they provide the necessary signatures of
+ * member functions.
  *
  * @code
  * class Matrix
@@ -118,23 +117,25 @@ template <typename number> class Vector;
  * @endcode
  *
  * In addition, for some solvers there has to be a global function
- * <tt>swap(VECTOR &a, VECTOR &b)</tt> that exchanges the values of the two vectors.
+ * <tt>swap(VECTOR &a, VECTOR &b)</tt> that exchanges the values of the two
+ * vectors.
  *
- * The preconditioners used must have the same interface as matrices,
- * i.e. in particular they have to provide a member function @p vmult
- * which denotes the application of the preconditioner.
+ * The preconditioners used must have the same interface as matrices, i.e. in
+ * particular they have to provide a member function @p vmult which denotes
+ * the application of the preconditioner.
  *
  *
  * <h3>AdditionalData</h3>
  *
  * Several solvers need additional data, like the damping parameter @p omega
- * of the @p SolverRichardson class or the maximum number of temporary
- * vectors of @p SolverGMRES.  To have a standardized way of constructing solvers,
- * each solver class has a <tt>struct AdditionalData</tt> as a member, and constructors
- * of all solver classes take such an argument. Some solvers need no additional data,
- * or may not at the current time. For these solvers the struct @p AdditionalData is
- * empty and calling the constructor may be done without giving the additional
- * structure as an argument as a default @p AdditionalData is set by default.
+ * of the @p SolverRichardson class or the maximum number of temporary vectors
+ * of @p SolverGMRES.  To have a standardized way of constructing solvers,
+ * each solver class has a <tt>struct AdditionalData</tt> as a member, and
+ * constructors of all solver classes take such an argument. Some solvers need
+ * no additional data, or may not at the current time. For these solvers the
+ * struct @p AdditionalData is empty and calling the constructor may be done
+ * without giving the additional structure as an argument as a default @p
+ * AdditionalData is set by default.
  *
  * With this, creating a solver looks like
  * @code
@@ -150,83 +151,76 @@ template <typename number> class Vector;
  * SolverCG solver_cg (solver_control, vector_memory);
  * @endcode
  *
- * Using a unified constructor parameter list for all solvers supports
- * the @p SolverSelector class; the unified interface
- * enables us to use this class unchanged even if the number of types of
- * parameters to a certain solver changes and it is still possible in a simple
- * way to give these additional data to the @p SolverSelector object for each
- * solver which it may use.
+ * Using a unified constructor parameter list for all solvers supports the @p
+ * SolverSelector class; the unified interface enables us to use this class
+ * unchanged even if the number of types of parameters to a certain solver
+ * changes and it is still possible in a simple way to give these additional
+ * data to the @p SolverSelector object for each solver which it may use.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The Solver class, being the base class for all of the iterative solvers such
- * as SolverCG, SolverGMRES, etc, provides the facilities by which actual solver
- * implementations determine whether the iteration is converged, not yet
- * converged, or has failed. Typically, this is done using an object of type
- * SolverControl that is passed to the solver classes's constructors and from
- * them down to the constructor of this base class. Every one of the tutorial
- * programs that solves a linear problem (starting with step-3) uses this
- * method and it is described in detail there. However, the underlying mechanism
- * is more general and allows for many other uses to observe how the linear
- * solver iterations progress.
+ * The Solver class, being the base class for all of the iterative solvers
+ * such as SolverCG, SolverGMRES, etc, provides the facilities by which actual
+ * solver implementations determine whether the iteration is converged, not
+ * yet converged, or has failed. Typically, this is done using an object of
+ * type SolverControl that is passed to the solver classes's constructors and
+ * from them down to the constructor of this base class. Every one of the
+ * tutorial programs that solves a linear problem (starting with step-3) uses
+ * this method and it is described in detail there. However, the underlying
+ * mechanism is more general and allows for many other uses to observe how the
+ * linear solver iterations progress.
  *
  * The basic approach is that the iterative solvers invoke a <i>signal</i> at
- * the end of each iteration to determine whether the solution is converged.
- * signal is a class that has, conceptually, a list of pointers to functions
+ * the end of each iteration to determine whether the solution is converged. A
+ * signal is a class that has, conceptually, a list of pointers to functions
  * and every time the signal is invoked, each of these functions are called.
  * In the language of signals, the functions called are called <i>slots</i>
- * and one can attach any number of slots to a signal.
- * (The implementation of signals and slots we use here is the one from the
- * BOOST.signals2 library.) A number of details may clarify what is happening
- * underneath:
- * - In reality, the signal object does not store pointers to functions, but
- *   function objects as slots. Each slot must conform to a particular
- *   signature: here, it is an object that can be called with three arguments
- *   (the number of the current linear iteration, the current residual, and
- *   the current iterate; more specifics are discussed in the documentation of
- *   the connect() function). A pointer to a function with this argument list
- *   satisfies the requirements, but you can also pass a member function
- *   whose <code>this</code> argument has been bound using the
- *   <code>std_cxx11::bind</code> mechanism (see the example below).
- * - Each of the slots will return a value that indicates whether
- *   the iteration should continue, should stop because it has succeeded,
- *   or stop because it has failed. The return type of slots is therefore
- *   of type SolverControl::State. The returned values from all of the
- *   slots will then have to be combined before they are returned to the
- *   iterative solver that invoked the signal. The way this works is that
- *   if at least one slot returned SolverControl::failure, then the
- *   combined value is SolverControl::failure; otherwise, if at least
- *   one slot returned SolverControl::iterate, then this is going to be
- *   the return value of the signal; finally, only if all slots return
- *   SolverControl::success will the signal's return value be
- *   SolverControl::success.
- * - It may of course be that a particular
- *   slot has been connected to the signal only to observe how the
- *   solution or a specific part of it converges, but has no particular
- *   opinion on whether the iteration should continue or not. In such
- *   cases, the slot should just return SolverControl::success, which
- *   is the weakest of all return values according to the rules laid
- *   out above.
- *
- * Given all this, it should now be obvious how the SolverControl
- * object fits into this scheme: when a SolverControl object is passed
- * to the constructor of the current class, we simply connect the
- * SolverControl::check() function of that object as a slot to the
- * signal we maintain here. In other words, since a Solver object
- * is always constructed using a SolverControl object, there is
- * always at least one slot associated with the signal, namely the
+ * and one can attach any number of slots to a signal. (The implementation of
+ * signals and slots we use here is the one from the BOOST.signals2 library.)
+ * A number of details may clarify what is happening underneath: - In reality,
+ * the signal object does not store pointers to functions, but function
+ * objects as slots. Each slot must conform to a particular signature: here,
+ * it is an object that can be called with three arguments (the number of the
+ * current linear iteration, the current residual, and the current iterate;
+ * more specifics are discussed in the documentation of the connect()
+ * function). A pointer to a function with this argument list satisfies the
+ * requirements, but you can also pass a member function whose
+ * <code>this</code> argument has been bound using the
+ * <code>std_cxx11::bind</code> mechanism (see the example below). - Each of
+ * the slots will return a value that indicates whether the iteration should
+ * continue, should stop because it has succeeded, or stop because it has
+ * failed. The return type of slots is therefore of type SolverControl::State.
+ * The returned values from all of the slots will then have to be combined
+ * before they are returned to the iterative solver that invoked the signal.
+ * The way this works is that if at least one slot returned
+ * SolverControl::failure, then the combined value is SolverControl::failure;
+ * otherwise, if at least one slot returned SolverControl::iterate, then this
+ * is going to be the return value of the signal; finally, only if all slots
+ * return SolverControl::success will the signal's return value be
+ * SolverControl::success. - It may of course be that a particular slot has
+ * been connected to the signal only to observe how the solution or a specific
+ * part of it converges, but has no particular opinion on whether the
+ * iteration should continue or not. In such cases, the slot should just
+ * return SolverControl::success, which is the weakest of all return values
+ * according to the rules laid out above.
+ *
+ * Given all this, it should now be obvious how the SolverControl object fits
+ * into this scheme: when a SolverControl object is passed to the constructor
+ * of the current class, we simply connect the SolverControl::check() function
+ * of that object as a slot to the signal we maintain here. In other words,
+ * since a Solver object is always constructed using a SolverControl object,
+ * there is always at least one slot associated with the signal, namely the
  * one that determines convergence.
  *
- * On the other hand, using the connect() member function, it is
- * possible to connect any number of other slots to the signal to
- * observe whatever it is you want to observe. The connect() function
- * also returns an object that describes the connection from the
- * signal to the slot, and the corresponding BOOST functions then allow
- * you to disconnect the slot if you want.
+ * On the other hand, using the connect() member function, it is possible to
+ * connect any number of other slots to the signal to observe whatever it is
+ * you want to observe. The connect() function also returns an object that
+ * describes the connection from the signal to the slot, and the corresponding
+ * BOOST functions then allow you to disconnect the slot if you want.
  *
- * An example may illuminate these issues. In the step-3 tutorial
- * program, let us add a member function as follows to the main class:
+ * An example may illuminate these issues. In the step-3 tutorial program, let
+ * us add a member function as follows to the main class:
  * @code
  *  SolverControl::State
  *  Step3::write_intermediate_solution (const unsigned int    iteration,
@@ -245,15 +239,14 @@ template <typename number> class Vector;
  *      return SolverControl::success;
  *    }
  * @endcode
- * The function satisfies the signature necessary to be a slot for the
- * signal discussed above, with the exception that it is a member
- * function and consequently requires a <code>this</code> pointer.
- * What the function does is to take the vector given as last
- * argument and write it into a file in VTU format with a file
- * name derived from the number of the iteration.
- *
- * This function can then be hooked into the CG solver by modifying
- * the <code>Step3::solve()</code> function as follows:
+ * The function satisfies the signature necessary to be a slot for the signal
+ * discussed above, with the exception that it is a member function and
+ * consequently requires a <code>this</code> pointer. What the function does
+ * is to take the vector given as last argument and write it into a file in
+ * VTU format with a file name derived from the number of the iteration.
+ *
+ * This function can then be hooked into the CG solver by modifying the
+ * <code>Step3::solve()</code> function as follows:
  * @code
  * void Step3::solve ()
  * {
@@ -269,122 +262,89 @@ template <typename number> class Vector;
  *                 PreconditionIdentity());
  * }
  * @endcode
- * The use of <code>std_cxx11::bind</code> here ensures that we convert
- * the member function with its three arguments plus the <code>this</code>
- * pointer, to a function that only takes three arguments, by fixing
- * the implicit <code>this</code> argument of the function to the
+ * The use of <code>std_cxx11::bind</code> here ensures that we convert the
+ * member function with its three arguments plus the <code>this</code>
+ * pointer, to a function that only takes three arguments, by fixing the
+ * implicit <code>this</code> argument of the function to the
  * <code>this</code> pointer in the current function.
  *
- * It is well understood that the CG method is a smoothing iteration (in
- * the same way as the more commonly used Jacobi or SSOR iterations are
+ * It is well understood that the CG method is a smoothing iteration (in the
+ * same way as the more commonly used Jacobi or SSOR iterations are
  * smoothers). The code above therefore allows to observe how the solution
- * becomes smoother and smoother in every iteration. This is best
- * observed by initializing the solution vector with randomly distributed
- * numbers in $[-1,1]$, using code such as
+ * becomes smoother and smoother in every iteration. This is best observed by
+ * initializing the solution vector with randomly distributed numbers in
+ * $[-1,1]$, using code such as
  * @code
  *   for (unsigned int i=0; i<solution.size(); ++i)
  *     solution(i) = 2.*rand()/RAND_MAX-1;
  * @endcode
- * Using this, the slot will then generate files that when visualized
- * look like this over the course of iterations zero to five:
- * <table>
- * <tr>
- *   <td>
- *     @image html "cg-monitor-smoothing-0.png"
- *   </td>
- *   <td>
- *     @image html "cg-monitor-smoothing-1.png"
- *   </td>
- *   <td>
- *     @image html "cg-monitor-smoothing-2.png"
- *   </td>
- * </tr>
- * <tr>
- *   <td>
- *     @image html "cg-monitor-smoothing-3.png"
- *   </td>
- *   <td>
- *     @image html "cg-monitor-smoothing-4.png"
- *   </td>
- *   <td>
- *     @image html "cg-monitor-smoothing-5.png"
- *   </td>
- * </tr>
- * </table>
+ * Using this, the slot will then generate files that when visualized look
+ * like this over the course of iterations zero to five: <table> <tr> <td>
+ * @image html "cg-monitor-smoothing-0.png" </td> <td> @image html "cg-
+ * monitor-smoothing-1.png" </td> <td> @image html "cg-monitor-
+ * smoothing-2.png" </td> </tr> <tr> <td> @image html "cg-monitor-
+ * smoothing-3.png" </td> <td> @image html "cg-monitor-smoothing-4.png" </td>
+ * <td> @image html "cg-monitor-smoothing-5.png" </td> </tr> </table>
  *
  * @ingroup Solvers
- * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1997-2001, 2005, 2014
+ * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1997-2001, 2005,
+ * 2014
  */
 template <class VECTOR = Vector<double> >
 class Solver : public Subscriptor
 {
 public:
   /**
-   * Constructor. Takes a control
-   * object which evaluates the
-   * conditions for convergence,
-   * and an object that allows solvers to allocate
-   * memory for temporary objects.
+   * Constructor. Takes a control object which evaluates the conditions for
+   * convergence, and an object that allows solvers to allocate memory for
+   * temporary objects.
    *
-   * Of both objects, a reference is
-   * stored, so it is the user's
-   * responsibility to guarantee that the
-   * lifetime of the two arguments is at
-   * least as long as that of the solver
-   * object.
+   * Of both objects, a reference is stored, so it is the user's
+   * responsibility to guarantee that the lifetime of the two arguments is at
+   * least as long as that of the solver object.
    */
   Solver (SolverControl        &solver_control,
           VectorMemory<VECTOR> &vector_memory);
 
   /**
-   * Constructor. Takes a control
-   * object which evaluates the
-   * conditions for convergence. In
-   * contrast to the other
-   * constructor, this constructor
-   * designates an internal object of
-   * type GrowingVectorMemory to
-   * allocate memory.
+   * Constructor. Takes a control object which evaluates the conditions for
+   * convergence. In contrast to the other constructor, this constructor
+   * designates an internal object of type GrowingVectorMemory to allocate
+   * memory.
    *
-   * A reference to the control
-   * object is stored, so it is the
-   * user's responsibility to
-   * guarantee that the lifetime of
-   * the argument is at least
-   * as long as that of the solver
-   * object.
+   * A reference to the control object is stored, so it is the user's
+   * responsibility to guarantee that the lifetime of the argument is at least
+   * as long as that of the solver object.
    */
   Solver (SolverControl &solver_control);
 
   /**
    * Connect a function object that will be called periodically within
-   * iterative solvers. This function is used to attach monitors to
-   * iterative solvers, either to determine when convergence has happened,
-   * or simply to observe the progress of an iteration. See the documentation
-   * of this class for more information.
+   * iterative solvers. This function is used to attach monitors to iterative
+   * solvers, either to determine when convergence has happened, or simply to
+   * observe the progress of an iteration. See the documentation of this class
+   * for more information.
    *
-   * @param slot A function object specified here will, with
-   *   each call, receive the number of the current iteration,
-   *   the value that is used to check for convergence (typically the residual
-   *   of the current iterate with respect to the linear system to be solved)
-   *   and the currently best available guess for the current iterate.
-   *   Note that some solvers do not update the approximate solution in every
-   *   iteration but only after convergence or failure has been determined
-   *   (GMRES is an example); in such cases, the vector passed as the last
-   *   argument to the signal is simply the best approximate at the time
-   *   the signal is called, but not the vector that will be returned if
-   *   the signal's return value indicates that the iteration should be
-   *   terminated. The function object must return a SolverControl::State
-   *   value that indicates whether the iteration should continue, has
-   *   failed, or has succeeded. The results of all connected functions
-   *   will then be combined to determine what should happen with the
-   *   iteration.
+   * @param slot A function object specified here will, with each call,
+   * receive the number of the current iteration, the value that is used to
+   * check for convergence (typically the residual of the current iterate with
+   * respect to the linear system to be solved) and the currently best
+   * available guess for the current iterate. Note that some solvers do not
+   * update the approximate solution in every iteration but only after
+   * convergence or failure has been determined (GMRES is an example); in such
+   * cases, the vector passed as the last argument to the signal is simply the
+   * best approximate at the time the signal is called, but not the vector
+   * that will be returned if the signal's return value indicates that the
+   * iteration should be terminated. The function object must return a
+   * SolverControl::State value that indicates whether the iteration should
+   * continue, has failed, or has succeeded. The results of all connected
+   * functions will then be combined to determine what should happen with the
+   * iteration.
    *
    * @return A connection object that represents the connection from the
-   *   signal to the function object. It can be used to disconnect the
-   *   function object again from the signal. See the documentation of
-   *   the BOOST Signals2 library for more information on connection
-   *   management.
+   * signal to the function object. It can be used to disconnect the function
+   * object again from the signal. See the documentation of the BOOST Signals2
+   * library for more information on connection management.
    */
   boost::signals2::connection
   connect (const std_cxx11::function<SolverControl::State (const unsigned int iteration,
@@ -395,10 +355,8 @@ public:
 
 protected:
   /**
-   * A static vector memory object
-   * to be used whenever no such
-   * object has been given to the
-   * constructor.
+   * A static vector memory object to be used whenever no such object has been
+   * given to the constructor.
    */
   mutable GrowingVectorMemory<VECTOR> static_vector_memory;
 
@@ -409,13 +367,11 @@ protected:
 
 private:
   /**
-   * A class whose operator() combines two states indicating whether
-   * we should continue iterating or stop, and returns a state that
-   * dominates. The rules are:
-   * - If one of the two states indicates failure, return failure.
-   * - Otherwise, if one of the two states indicates to continue
-   *   iterating, then continue iterating.
-   * - Otherwise, return success.
+   * A class whose operator() combines two states indicating whether we should
+   * continue iterating or stop, and returns a state that dominates. The rules
+   * are: - If one of the two states indicates failure, return failure. -
+   * Otherwise, if one of the two states indicates to continue iterating, then
+   * continue iterating. - Otherwise, return success.
    */
   struct StateCombiner
   {
@@ -431,26 +387,24 @@ private:
 
 protected:
   /**
-   * A signal that iterative solvers can execute at the end of every
-   * iteration (or in an otherwise periodic fashion) to find out whether
-   * we should continue iterating or not. The signal may call one or
-   * more slots that each will make this determination by themselves,
-   * and the result over all slots (function calls) will be determined
-   * by the StateCombiner object.
+   * A signal that iterative solvers can execute at the end of every iteration
+   * (or in an otherwise periodic fashion) to find out whether we should
+   * continue iterating or not. The signal may call one or more slots that
+   * each will make this determination by themselves, and the result over all
+   * slots (function calls) will be determined by the StateCombiner object.
    *
    * The arguments passed to the signal are (i) the number of the current
-   * iteration; (ii) the value that is used to determine convergence (oftentimes
-   * the residual, but in other cases other quantities may be used as long
-   * as they converge to zero as the iterate approaches the solution of
-   * the linear system); and (iii) a vector that corresponds to the current
-   * best guess for the solution at the point where the signal is called.
-   * Note that some solvers do not update the approximate solution in every
+   * iteration; (ii) the value that is used to determine convergence
+   * (oftentimes the residual, but in other cases other quantities may be used
+   * as long as they converge to zero as the iterate approaches the solution
+   * of the linear system); and (iii) a vector that corresponds to the current
+   * best guess for the solution at the point where the signal is called. Note
+   * that some solvers do not update the approximate solution in every
    * iteration but only after convergence or failure has been determined
    * (GMRES is an example); in such cases, the vector passed as the last
-   * argument to the signal is simply the best approximate at the time
-   * the signal is called, but not the vector that will be returned if
-   * the signal's return value indicates that the iteration should be
-   * terminated.
+   * argument to the signal is simply the best approximate at the time the
+   * signal is called, but not the vector that will be returned if the
+   * signal's return value indicates that the iteration should be terminated.
    */
   boost::signals2::signal<SolverControl::State (const unsigned int iteration,
                                                 const double        check_value,
index 0f68bf44d44a4cfe365368161908c01fdf19184b..9c9815adefe987495065c0e6d36f65f860684087 100644 (file)
@@ -32,42 +32,40 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Bicgstab algorithm by van der Vorst.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
  *
- * The Bicgstab-method has two additional parameters: the first is a
- * boolean, deciding whether to compute the actual residual in each step (@p
- * true) or to use the length of the computed orthogonal residual (@p
- * false). Note that computing the residual causes a third
- * matrix-vector-multiplication, though no additional preconditioning, in
- * each step. The reason for doing this is, that the size of the
- * orthogonalized residual computed during the iteration may be larger by
- * orders of magnitude than the true residual. This is due to numerical
- * instabilities related to badly conditioned matrices. Since this
+ * The Bicgstab-method has two additional parameters: the first is a boolean,
+ * deciding whether to compute the actual residual in each step (@p true) or
+ * to use the length of the computed orthogonal residual (@p false). Note that
+ * computing the residual causes a third matrix-vector-multiplication, though
+ * no additional preconditioning, in each step. The reason for doing this is,
+ * that the size of the orthogonalized residual computed during the iteration
+ * may be larger by orders of magnitude than the true residual. This is due to
+ * numerical instabilities related to badly conditioned matrices. Since this
  * instability results in a bad stopping criterion, the default for this
  * parameter is @p true. Whenever the user knows that the estimated residual
- * works reasonably as well, the flag should be set to @p false in order
- * to increase the performance of the solver.
+ * works reasonably as well, the flag should be set to @p false in order to
+ * increase the performance of the solver.
  *
- * The second parameter is the size of a breakdown criterion. It is
- * difficult to find a general good criterion, so if things do not
- * work for you, try to change this value.
+ * The second parameter is the size of a breakdown criterion. It is difficult
+ * to find a general good criterion, so if things do not work for you, try to
+ * change this value.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  */
 template <class VECTOR = Vector<double> >
@@ -234,8 +232,8 @@ private:
   SolverControl::State start(const MATRIX &A);
 
   /**
-   * A structure returned by the iterate() function representing
-   * what it found is happening during the iteration.
+   * A structure returned by the iterate() function representing what it found
+   * is happening during the iteration.
    */
   struct IterationResult
   {
@@ -251,8 +249,8 @@ private:
   };
 
   /**
-   * The iteration loop itself. The function returns a structure
-   * indicating what happened in this function.
+   * The iteration loop itself. The function returns a structure indicating
+   * what happened in this function.
    */
   template<class MATRIX, class PRECONDITIONER>
   IterationResult
index 4949414bbc804079a2beb86aa0493b3556d5a960..72455efcc5635f33a22f4fcf736a3359939563a5 100644 (file)
@@ -45,46 +45,44 @@ class PreconditionIdentity;
  * solution vector must be passed as template argument, and defaults to
  * dealii::Vector<double>.
  *
- * Like all other solver classes, this class has a local structure
- * called @p AdditionalData which is used to pass additional
- * parameters to the solver. For this class, there is (among other things)
- * a switch allowing for additional output for the computation of
- * eigenvalues of the matrix.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver.
+ * For this class, there is (among other things) a switch allowing for
+ * additional output for the computation of eigenvalues of the matrix.
  *
- * @note This version of CG is taken from D. Braess's book "Finite
- * Elements". It requires a symmetric preconditioner (i.e., for example, SOR
- * is not a possible choice).
+ * @note This version of CG is taken from D. Braess's book "Finite Elements".
+ * It requires a symmetric preconditioner (i.e., for example, SOR is not a
+ * possible choice).
  *
  *
  * <h3>Eigenvalue computation</h3>
  *
  * The cg-method performs an orthogonal projection of the original
- * preconditioned linear system to another system of smaller
- * dimension. Furthermore, the projected matrix @p T is
- * tri-diagonal. Since the projection is orthogonal, the eigenvalues
- * of @p T approximate those of the original preconditioned matrix
- * @p PA. In fact, after @p n steps, where @p n is the dimension of
- * the original system, the eigenvalues of both matrices are
- * equal. But, even for small numbers of iteration steps, the
- * condition number of @p T is a good estimate for the one of @p PA.
+ * preconditioned linear system to another system of smaller dimension.
+ * Furthermore, the projected matrix @p T is tri-diagonal. Since the
+ * projection is orthogonal, the eigenvalues of @p T approximate those of the
+ * original preconditioned matrix @p PA. In fact, after @p n steps, where @p n
+ * is the dimension of the original system, the eigenvalues of both matrices
+ * are equal. But, even for small numbers of iteration steps, the condition
+ * number of @p T is a good estimate for the one of @p PA.
  *
- * With the coefficients @p alpha and @p beta written to the log
- * file if <tt>AdditionalData::log_coefficients = true</tt>, the matrix
- * @p T_m after @p m steps is the tri-diagonal matrix with diagonal
- * elements <tt>1/alpha_0</tt>, <tt>1/alpha_1 + beta_0/alpha_0</tt>, ...,
+ * With the coefficients @p alpha and @p beta written to the log file if
+ * <tt>AdditionalData::log_coefficients = true</tt>, the matrix @p T_m after
+ * @p m steps is the tri-diagonal matrix with diagonal elements
+ * <tt>1/alpha_0</tt>, <tt>1/alpha_1 + beta_0/alpha_0</tt>, ...,
  * <tt>1/alpha_{m-1</tt>+beta_{m-2}/alpha_{m-2}} and off-diagonal elements
  * <tt>sqrt(beta_0)/alpha_0</tt>, ..., <tt>sqrt(beta_{m-2</tt>)/alpha_{m-2}}.
  * The eigenvalues of this matrix can be computed by postprocessing.
  *
- * @see Y. Saad: "Iterative methods for Sparse Linear Systems", section
- * 6.7.3 for details.
+ * @see Y. Saad: "Iterative methods for Sparse Linear Systems", section 6.7.3
+ * for details.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @author W. Bangerth, G. Kanschat, R. Becker and F.-T. Suttmeier
@@ -99,48 +97,39 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Standardized data struct to pipe
-   * additional data to the solver.
+   * Standardized data struct to pipe additional data to the solver.
    */
   struct AdditionalData
   {
     /**
-     * Write coefficients alpha and beta
-     * to the log file for later use in
+     * Write coefficients alpha and beta to the log file for later use in
      * eigenvalue estimates.
      */
     bool log_coefficients;
 
     /**
-     * Compute the condition
-     * number of the projected
-     * matrix.
+     * Compute the condition number of the projected matrix.
      *
      * @note Requires LAPACK support.
      */
     bool compute_condition_number;
 
     /**
-     * Compute the condition
-     * number of the projected
-     * matrix in each step.
+     * Compute the condition number of the projected matrix in each step.
      *
      * @note Requires LAPACK support.
      */
     bool compute_all_condition_numbers;
 
     /**
-     * Compute all eigenvalues of
-     * the projected matrix.
+     * Compute all eigenvalues of the projected matrix.
      *
      * @note Requires LAPACK support.
      */
     bool compute_eigenvalues;
 
     /**
-     * Constructor. Initialize data
-     * fields.  Confer the description of
-     * those.
+     * Constructor. Initialize data fields.  Confer the description of those.
      */
     AdditionalData (const bool log_coefficients = false,
                     const bool compute_condition_number = false,
@@ -156,9 +145,8 @@ public:
             const AdditionalData &data = AdditionalData());
 
   /**
-   * Constructor. Use an object of
-   * type GrowingVectorMemory as
-   * a default to allocate memory.
+   * Constructor. Use an object of type GrowingVectorMemory as a default to
+   * allocate memory.
    */
   SolverCG (SolverControl        &cn,
             const AdditionalData &data=AdditionalData());
@@ -169,8 +157,7 @@ public:
   virtual ~SolverCG ();
 
   /**
-   * Solve the linear system $Ax=b$
-   * for x.
+   * Solve the linear system $Ax=b$ for x.
    */
   template <class MATRIX, class PRECONDITIONER>
   void
@@ -181,21 +168,15 @@ public:
 
 protected:
   /**
-   * Implementation of the computation of
-   * the norm of the residual. This can be
-   * replaced by a more problem oriented
-   * functional in a derived class.
+   * Implementation of the computation of the norm of the residual. This can
+   * be replaced by a more problem oriented functional in a derived class.
    */
   virtual double criterion();
 
   /**
-   * Interface for derived class.
-   * This function gets the current
-   * iteration vector, the residual
-   * and the update vector in each
-   * step. It can be used for a
-   * graphical output of the
-   * convergence history.
+   * Interface for derived class. This function gets the current iteration
+   * vector, the residual and the update vector in each step. It can be used
+   * for a graphical output of the convergence history.
    */
   virtual void print_vectors(const unsigned int step,
                              const VECTOR &x,
@@ -203,24 +184,18 @@ protected:
                              const VECTOR &d) const;
 
   /**
-   * Temporary vectors, allocated through
-   * the @p VectorMemory object at the start
-   * of the actual solution process and
-   * deallocated at the end.
+   * Temporary vectors, allocated through the @p VectorMemory object at the
+   * start of the actual solution process and deallocated at the end.
    */
   VECTOR *Vr;
   VECTOR *Vp;
   VECTOR *Vz;
 
   /**
-   * Within the iteration loop, the
-   * square of the residual vector is
-   * stored in this variable. The
-   * function @p criterion uses this
-   * variable to compute the convergence
-   * value, which in this class is the
-   * norm of the residual vector and thus
-   * the square root of the @p res2 value.
+   * Within the iteration loop, the square of the residual vector is stored in
+   * this variable. The function @p criterion uses this variable to compute
+   * the convergence value, which in this class is the norm of the residual
+   * vector and thus the square root of the @p res2 value.
    */
   double res2;
 
index f0f3da521408aa57094f76acb00fda1367f747a8..a8e3c644fcb3b89659cc52736a24ae3a4ae60bd4 100644 (file)
@@ -32,32 +32,31 @@ class ParameterHandler;
 /**
  * Control class to determine convergence of iterative solvers.
  *
- * Used by iterative methods to determine whether the iteration should
- * be continued. To this end, the virtual function <tt>check()</tt> is
- * called in each iteration with the current iteration step and the
- * value indicating convergence (usually the residual).
+ * Used by iterative methods to determine whether the iteration should be
+ * continued. To this end, the virtual function <tt>check()</tt> is called in
+ * each iteration with the current iteration step and the value indicating
+ * convergence (usually the residual).
  *
  * After the iteration has terminated, the functions last_value() and
- * last_step() can be used to obtain information about the final state
- * of the iteration.
+ * last_step() can be used to obtain information about the final state of the
+ * iteration.
  *
- * check() can be replaced in derived classes to allow for more
- * sophisticated tests.
+ * check() can be replaced in derived classes to allow for more sophisticated
+ * tests.
  *
  *
- * <h3>State</h3>
- * The return states of the check function are of type #State,
- * which is an enum local to this class. It indicates the state the
- * solver is in.
+ * <h3>State</h3> The return states of the check function are of type #State,
+ * which is an enum local to this class. It indicates the state the solver is
+ * in.
  *
  * The possible values of State are
  * <ul>
  * <li> <tt>iterate = 0</tt>: continue the iteration.
  * <li> @p success: the goal is reached, the iterative method can terminate
- *       successfully.
- * <li> @p failure: the iterative method should stop because convergence
- *       could not be achieved or at least was not achieved within the given
- *       maximal number of iterations.
+ * successfully.
+ * <li> @p failure: the iterative method should stop because convergence could
+ * not be achieved or at least was not achieved within the given maximal
+ * number of iterations.
  * </ul>
  *
  * @author Guido Kanschat
@@ -83,9 +82,9 @@ public:
 
 
   /**
-   * Class to be thrown upon failing convergence of an iterative solver,
-   * when either the number of iterations exceeds the limit or the residual
-   * fails to reach the desired limit, e.g. in the case of a break-down.
+   * Class to be thrown upon failing convergence of an iterative solver, when
+   * either the number of iterations exceeds the limit or the residual fails
+   * to reach the desired limit, e.g. in the case of a break-down.
    *
    * The residual in the last iteration, as well as the iteration number of
    * the last step are stored in this object and can be recovered upon
@@ -138,14 +137,14 @@ public:
 
   /**
    * Constructor. The parameters @p n and @p tol are the maximum number of
-   * iteration steps before failure and the tolerance to determine success
-   * of the iteration.
+   * iteration steps before failure and the tolerance to determine success of
+   * the iteration.
    *
    * @p log_history specifies whether the history (i.e. the value to be
    * checked and the number of the iteration step) shall be printed to @p
    * deallog stream.  Default is: do not print. Similarly, @p log_result
-   * specifies the whether the final result is logged to @p deallog.
-   * Default is yes.
+   * specifies the whether the final result is logged to @p deallog. Default
+   * is yes.
    */
   SolverControl (const unsigned int n           = 100,
                  const double       tol         = 1.e-10,
@@ -169,26 +168,25 @@ public:
   void parse_parameters (ParameterHandler &param);
 
   /**
-   * Decide about success or failure of an iteration.  This function gets
-   * the current iteration step to determine, whether the allowed number of
-   * steps has been exceeded and returns @p failure in this case. If @p
-   * check_value is below the prescribed tolerance, it returns @p success.
-   * In all other cases @p iterate is returned to suggest continuation of
-   * the iterative procedure.
+   * Decide about success or failure of an iteration.  This function gets the
+   * current iteration step to determine, whether the allowed number of steps
+   * has been exceeded and returns @p failure in this case. If @p check_value
+   * is below the prescribed tolerance, it returns @p success. In all other
+   * cases @p iterate is returned to suggest continuation of the iterative
+   * procedure.
    *
    * The iteration is also aborted if the residual becomes a denormalized
-   * value (@p NaN). Note, however, that this check is only performed if
-   * the @p isnan function is provided by the operating system, which is
-   * not always true. The @p configure scripts checks for this and sets the
-   * flag @p HAVE_ISNAN in the file <tt>Make.global_options</tt> if this
-   * function was found.
+   * value (@p NaN). Note, however, that this check is only performed if the
+   * @p isnan function is provided by the operating system, which is not
+   * always true. The @p configure scripts checks for this and sets the flag
+   * @p HAVE_ISNAN in the file <tt>Make.global_options</tt> if this function
+   * was found.
    *
-   * <tt>check()</tt> additionally preserves @p step and @p check_value.
-   * These values are accessible by <tt>last_value()</tt> and
-   * <tt>last_step()</tt>.
+   * <tt>check()</tt> additionally preserves @p step and @p check_value. These
+   * values are accessible by <tt>last_value()</tt> and <tt>last_step()</tt>.
    *
-   * Derived classes may overload this function, e.g. to log the
-   * convergence indicators (@p check_value) or to do other computations.
+   * Derived classes may overload this function, e.g. to log the convergence
+   * indicators (@p check_value) or to do other computations.
    */
   virtual State check (const unsigned int step,
                        const double   check_value);
@@ -248,8 +246,7 @@ public:
   double set_tolerance (const double);
 
   /**
-   * Enables writing residuals of each step into a vector for later
-   * analysis.
+   * Enables writing residuals of each step into a vector for later analysis.
    */
   void enable_history_data();
 
@@ -300,9 +297,9 @@ public:
   bool log_result () const;
 
   /**
-   * This exception is thrown if a function operating on the vector of
-   * history data of a SolverControl object id called, but storage of
-   * history data was not enabled by enable_history_data().
+   * This exception is thrown if a function operating on the vector of history
+   * data of a SolverControl object id called, but storage of history data was
+   * not enabled by enable_history_data().
    */
   DeclException0(ExcHistoryDataRequired);
 
@@ -374,14 +371,13 @@ protected:
   bool         m_log_result;
 
   /**
-   * Control over the storage of history data. Set by
-   * enable_history_data().
+   * Control over the storage of history data. Set by enable_history_data().
    */
   bool         history_data_enabled;
 
   /**
-   * Vector storing the result after each iteration step for later
-   * statistical analysis.
+   * Vector storing the result after each iteration step for later statistical
+   * analysis.
    *
    * Use of this vector is enabled by enable_history_data().
    */
@@ -390,16 +386,15 @@ protected:
 
 
 /**
- * Specialization of @p SolverControl which returns @p success if either
- * the specified tolerance is achieved or if the initial residual (or
- * whatever criterion was chosen by the solver class) is reduced by a
- * given factor. This is useful in cases where you don't want to solve
- * exactly, but rather want to gain two digits or if the maximal
- * number of iterations is achieved.  For example: The maximal number
- * of iterations is 20, the reduction factor is 1% und the tolerance
- * is 0.1%. The initial residual is 2.5. The process will break if 20
- * iteration are comleted or the new residual is less then 2.5*1% or
- * if it is less then 0.1%.
+ * Specialization of @p SolverControl which returns @p success if either the
+ * specified tolerance is achieved or if the initial residual (or whatever
+ * criterion was chosen by the solver class) is reduced by a given factor.
+ * This is useful in cases where you don't want to solve exactly, but rather
+ * want to gain two digits or if the maximal number of iterations is achieved.
+ * For example: The maximal number of iterations is 20, the reduction factor
+ * is 1% und the tolerance is 0.1%. The initial residual is 2.5. The process
+ * will break if 20 iteration are comleted or the new residual is less then
+ * 2.5*1% or if it is less then 0.1%.
  *
  * @author Guido Kanschat
  */
@@ -407,9 +402,9 @@ class ReductionControl : public SolverControl
 {
 public:
   /**
-   * Constructor.  Provide the reduction factor in addition to arguments
-   * that have the same meaning as those of the constructor of the
-   * SolverControl constructor.
+   * Constructor.  Provide the reduction factor in addition to arguments that
+   * have the same meaning as those of the constructor of the SolverControl
+   * constructor.
    */
   ReductionControl (const unsigned int maxiter = 100,
                     const double   tolerance   = 1.e-10,
@@ -446,9 +441,9 @@ public:
   void parse_parameters (ParameterHandler &param);
 
   /**
-   * Decide about success or failure of an iteration.  This function calls
-   * the one in the base class, but sets the tolerance to <tt>reduction *
-   * initial value</tt> upon the first iteration.
+   * Decide about success or failure of an iteration.  This function calls the
+   * one in the base class, but sets the tolerance to <tt>reduction * initial
+   * value</tt> upon the first iteration.
    */
   virtual State check (const unsigned int step,
                        const double   check_value);
@@ -470,22 +465,21 @@ protected:
   double reduce;
 
   /**
-   * Reduced tolerance. Stop iterations if either this value is achieved or
-   * if the base class indicates success.
+   * Reduced tolerance. Stop iterations if either this value is achieved or if
+   * the base class indicates success.
    */
   double reduced_tol;
 };
 
 /**
  * Specialization of @p SolverControl which returns @p success if a given
- * number of iteration was performed, irrespective of the actual
- * residual. This is useful in cases where you don't want to solve exactly,
- * but rather want to perform a fixed number of iterations, e.g. in an inner
- * solver. The arguments given to this class are exactly the same as for the
- * SolverControl class and the solver terminates similarly when one of the
- * given tolerance or the maximum iteration count were reached. The only
- * difference to SolverControl is that the solver returns success in the
- * latter case.
+ * number of iteration was performed, irrespective of the actual residual.
+ * This is useful in cases where you don't want to solve exactly, but rather
+ * want to perform a fixed number of iterations, e.g. in an inner solver. The
+ * arguments given to this class are exactly the same as for the SolverControl
+ * class and the solver terminates similarly when one of the given tolerance
+ * or the maximum iteration count were reached. The only difference to
+ * SolverControl is that the solver returns success in the latter case.
  *
  * @author Martin Kronbichler
  */
index 963b7dbea2798b914bb01bdef75af558e95d4667..6174d269015ed467d6fc265d7d1007c31b865a27 100644 (file)
@@ -102,62 +102,56 @@ namespace internal
 }
 
 /**
- * Implementation of the Restarted Preconditioned Direct Generalized
- * Minimal Residual Method. The stopping criterion is the norm of the
- * residual.
+ * Implementation of the Restarted Preconditioned Direct Generalized Minimal
+ * Residual Method. The stopping criterion is the norm of the residual.
  *
- * The AdditionalData structure contains the number of temporary
- * vectors used. The size of the Arnoldi basis is this number minus
- * three. Additionally, it allows you to choose between right or left
- * preconditioning. The default is left preconditioning. Finally it
- * includes a flag indicating whether or not the default residual is
- * used as stopping criterion.
+ * The AdditionalData structure contains the number of temporary vectors used.
+ * The size of the Arnoldi basis is this number minus three. Additionally, it
+ * allows you to choose between right or left preconditioning. The default is
+ * left preconditioning. Finally it includes a flag indicating whether or not
+ * the default residual is used as stopping criterion.
  *
  *
  * <h3>Left versus right preconditioning</h3>
  *
  * @p AdditionalData allows you to choose between left and right
- * preconditioning. As expected, this switches between solving for the
- * systems <i>P<sup>-1</sup>A</i> and <i>AP<sup>-1</sup></i>,
- * respectively.
+ * preconditioning. As expected, this switches between solving for the systems
+ * <i>P<sup>-1</sup>A</i> and <i>AP<sup>-1</sup></i>, respectively.
  *
- * A second consequence is the type of residual which is used to
- * measure convergence. With left preconditioning, this is the
- * <b>preconditioned</b> residual, while with right preconditioning,
- * it is the residual of the unpreconditioned system.
+ * A second consequence is the type of residual which is used to measure
+ * convergence. With left preconditioning, this is the <b>preconditioned</b>
+ * residual, while with right preconditioning, it is the residual of the
+ * unpreconditioned system.
  *
  * Optionally, this behavior can be overridden by using the flag
- * AdditionalData::use_default_residual. A <tt>true</tt> value refers
- * to the behavior described in the previous paragraph, while
- * <tt>false</tt> reverts it. Be aware though that additional
- * residuals have to be computed in this case, impeding the overall
- * performance of the solver.
+ * AdditionalData::use_default_residual. A <tt>true</tt> value refers to the
+ * behavior described in the previous paragraph, while <tt>false</tt> reverts
+ * it. Be aware though that additional residuals have to be computed in this
+ * case, impeding the overall performance of the solver.
  *
  *
  * <h3>The size of the Arnoldi basis</h3>
  *
- * The maximal basis size is controlled by
- * AdditionalData::max_n_tmp_vectors, and it is this number minus 2.
- * If the number of iteration steps exceeds this number, all basis
- * vectors are discarded and the iteration starts anew from the
- * approximation obtained so far.
+ * The maximal basis size is controlled by AdditionalData::max_n_tmp_vectors,
+ * and it is this number minus 2. If the number of iteration steps exceeds
+ * this number, all basis vectors are discarded and the iteration starts anew
+ * from the approximation obtained so far.
  *
- * Note that the minimizing property of GMRes only pertains to the
- * Krylov space spanned by the Arnoldi basis. Therefore, restarted
- * GMRes is <b>not</b> minimizing anymore. The choice of the basis
- * length is a trade-off between memory consumption and convergence
- * speed, since a longer basis means minimization over a larger
- * space.
+ * Note that the minimizing property of GMRes only pertains to the Krylov
+ * space spanned by the Arnoldi basis. Therefore, restarted GMRes is
+ * <b>not</b> minimizing anymore. The choice of the basis length is a trade-
+ * off between memory consumption and convergence speed, since a longer basis
+ * means minimization over a larger space.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann.
@@ -174,8 +168,8 @@ public:
     /**
      * Constructor. By default, set the number of temporary vectors to 30,
      * i.e. do a restart every 28 iterations. Also set preconditioning from
-     * left, the residual of the stopping criterion to the default
-     * residual, and re-orthogonalization only if necessary.
+     * left, the residual of the stopping criterion to the default residual,
+     * and re-orthogonalization only if necessary.
      */
     AdditionalData (const unsigned int max_n_tmp_vectors = 30,
                     const bool right_preconditioning = false,
@@ -205,8 +199,8 @@ public:
     bool use_default_residual;
 
     /**
-     * Flag to force re-orthogonalization of orthonormal basis in every
-     * step. If set to false, the solver automatically checks for loss of
+     * Flag to force re-orthogonalization of orthonormal basis in every step.
+     * If set to false, the solver automatically checks for loss of
      * orthogonality every 5 iterations and enables re-orthogonalization only
      * if necessary.
      */
@@ -275,12 +269,12 @@ protected:
 
   /**
    * Orthogonalize the vector @p vv against the @p dim (orthogonal) vectors
-   * given by the first argument using the modified Gram-Schmidt
-   * algorithm. The factors used for orthogonalization are stored in @p h. The
-   * boolean @p re_orthogonalize specifies whether the modified Gram-Schmidt
-   * algorithm should be applied twice. The algorithm checks loss of
-   * orthogonality in the procedure every fifth step and sets the flag to true
-   * in that case. All subsequent iterations use re-orthogonalization.
+   * given by the first argument using the modified Gram-Schmidt algorithm.
+   * The factors used for orthogonalization are stored in @p h. The boolean @p
+   * re_orthogonalize specifies whether the modified Gram-Schmidt algorithm
+   * should be applied twice. The algorithm checks loss of orthogonality in
+   * the procedure every fifth step and sets the flag to true in that case.
+   * All subsequent iterations use re-orthogonalization.
    */
   static double
   modified_gram_schmidt (const internal::SolverGMRES::TmpVectors<VECTOR> &orthogonal_vectors,
@@ -313,17 +307,16 @@ private:
  * preconditioning method.
  *
  * This version of the GMRES method allows for the use of a different
- * preconditioner in each iteration step. Therefore, it is also more
- * robust with respect to inaccurate evaluation of the
- * preconditioner. An important application is also the use of a
- * Krylov space method inside the preconditioner.
+ * preconditioner in each iteration step. Therefore, it is also more robust
+ * with respect to inaccurate evaluation of the preconditioner. An important
+ * application is also the use of a Krylov space method inside the
+ * preconditioner.
  *
- * FGMRES needs two vectors in each iteration steps yielding a total
- * of <tt>2 * SolverFGMRESAdditionalData::max_basis_size+1</tt>
- * auxiliary vectors.
+ * FGMRES needs two vectors in each iteration steps yielding a total of <tt>2
+ * * SolverFGMRESAdditionalData::max_basis_size+1</tt> auxiliary vectors.
  *
- * Caveat: documentation of this class is not up to date. There are
- * also a few parameters of GMRES we would like to introduce here.
+ * Caveat: documentation of this class is not up to date. There are also a few
+ * parameters of GMRES we would like to introduce here.
  *
  * @author Guido Kanschat, 2003
  */
index f919bf3cfe737be9ba663d4be5320cfb6e733fc0..130be5c134cbb14e05a17ed4c839e7464e3c8865 100644 (file)
@@ -32,35 +32,34 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Minimal residual method for symmetric matrices.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
  *
- * However, since the MinRes method does not need additional data, the respective
- * structure is empty and does not offer any functionality. The constructor
- * has a default argument, so you may call it without the additional
- * parameter.
+ * However, since the MinRes method does not need additional data, the
+ * respective structure is empty and does not offer any functionality. The
+ * constructor has a default argument, so you may call it without the
+ * additional parameter.
  *
  * The preconditioner has to be positive definite and symmetric
  *
- * The algorithm is taken from the Master thesis of Astrid Battermann
- * with some changes. The full text can be found at
+ * The algorithm is taken from the Master thesis of Astrid Battermann with
+ * some changes. The full text can be found at
  * http://scholar.lib.vt.edu/theses/public/etd-12164379662151/etd-title.html
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @author Thomas Richter, 2000, Luca Heltai, 2006
@@ -70,10 +69,8 @@ class SolverMinRes : public Solver<VECTOR>
 {
 public:
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver. This solver does not
-   * need additional data yet.
+   * Standardized data struct to pipe additional data to the solver. This
+   * solver does not need additional data yet.
    */
   struct AdditionalData
   {
@@ -87,9 +84,8 @@ public:
                 const AdditionalData &data=AdditionalData());
 
   /**
-   * Constructor. Use an object of
-   * type GrowingVectorMemory as
-   * a default to allocate memory.
+   * Constructor. Use an object of type GrowingVectorMemory as a default to
+   * allocate memory.
    */
   SolverMinRes (SolverControl        &cn,
                 const AdditionalData &data=AdditionalData());
@@ -100,8 +96,7 @@ public:
   virtual ~SolverMinRes ();
 
   /**
-   * Solve the linear system $Ax=b$
-   * for x.
+   * Solve the linear system $Ax=b$ for x.
    */
   template<class MATRIX, class PRECONDITIONER>
   void
@@ -110,8 +105,10 @@ public:
          const VECTOR         &b,
          const PRECONDITIONER &precondition);
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -121,18 +118,13 @@ public:
 
 protected:
   /**
-   * Implementation of the computation of
-   * the norm of the residual.
+   * Implementation of the computation of the norm of the residual.
    */
   virtual double criterion();
   /**
-   * Interface for derived class.
-   * This function gets the current
-   * iteration vector, the residual
-   * and the update vector in each
-   * step. It can be used for a
-   * graphical output of the
-   * convergence history.
+   * Interface for derived class. This function gets the current iteration
+   * vector, the residual and the update vector in each step. It can be used
+   * for a graphical output of the convergence history.
    */
   virtual void print_vectors(const unsigned int step,
                              const VECTOR &x,
@@ -140,24 +132,18 @@ protected:
                              const VECTOR &d) const;
 
   /**
-   * Temporary vectors, allocated through
-   * the @p VectorMemory object at the start
-   * of the actual solution process and
-   * deallocated at the end.
+   * Temporary vectors, allocated through the @p VectorMemory object at the
+   * start of the actual solution process and deallocated at the end.
    */
   VECTOR *Vu0, *Vu1, *Vu2;
   VECTOR *Vm0, *Vm1, *Vm2;
   VECTOR *Vv;
 
   /**
-   * Within the iteration loop, the
-   * square of the residual vector is
-   * stored in this variable. The
-   * function @p criterion uses this
-   * variable to compute the convergence
-   * value, which in this class is the
-   * norm of the residual vector and thus
-   * the square root of the @p res2 value.
+   * Within the iteration loop, the square of the residual vector is stored in
+   * this variable. The function @p criterion uses this variable to compute
+   * the convergence value, which in this class is the norm of the residual
+   * vector and thus the square root of the @p res2 value.
    */
   double res2;
 };
index 743e665dc4d6a455264a53979e2458ee36ed8f17..9b0c040a79298aaa72d75124eab43910b5182bd6 100644 (file)
@@ -33,39 +33,36 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Quasi-minimal residual method for symmetric matrices.
  *
- * The QMRS method is supposed to solve symmetric indefinite linear
- * systems with symmetric, not necessarily definite preconditioners.
- * This version of QMRS is adapted from
- * Freund/Nachtigal: Software for simplified Lanczos and QMR
- * algorithms, Appl. Num. Math. 19 (1995), pp. 319-341
+ * The QMRS method is supposed to solve symmetric indefinite linear systems
+ * with symmetric, not necessarily definite preconditioners. This version of
+ * QMRS is adapted from Freund/Nachtigal: Software for simplified Lanczos and
+ * QMR algorithms, Appl. Num. Math. 19 (1995), pp. 319-341
  *
  * This version is for right preconditioning only, since then only the
- * preconditioner is used: left preconditioning seems to require the
- * inverse.
+ * preconditioner is used: left preconditioning seems to require the inverse.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
  *
- * However, since the QMRS method does not need additional data, the respective
- * structure is empty and does not offer any functionality. The constructor
- * has a default argument, so you may call it without the additional
- * parameter.
+ * However, since the QMRS method does not need additional data, the
+ * respective structure is empty and does not offer any functionality. The
+ * constructor has a default argument, so you may call it without the
+ * additional parameter.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @author Guido Kanschat, 1999
@@ -75,33 +72,23 @@ class SolverQMRS : public Solver<VECTOR>
 {
 public:
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver.
+   * Standardized data struct to pipe additional data to the solver.
    *
-   * There are two possibilities to compute
-   * the residual: one is an estimate using
-   * the computed value @p tau. The other
-   * is exact computation using another matrix
-   * vector multiplication.
+   * There are two possibilities to compute the residual: one is an estimate
+   * using the computed value @p tau. The other is exact computation using
+   * another matrix vector multiplication.
    *
-   * QMRS, is susceptible to
-   * breakdowns, so we need a
-   * parameter telling us, which
-   * numbers are considered
-   * zero. The proper breakdown
-   * criterion is very unclear, so
-   * experiments may be necessary
-   * here.
+   * QMRS, is susceptible to breakdowns, so we need a parameter telling us,
+   * which numbers are considered zero. The proper breakdown criterion is very
+   * unclear, so experiments may be necessary here.
    */
   struct AdditionalData
   {
     /**
      * Constructor.
      *
-     * The default is no exact residual
-     * computation and breakdown
-     * parameter 1e-16.
+     * The default is no exact residual computation and breakdown parameter
+     * 1e-16.
      */
     AdditionalData(bool exact_residual = false,
                    double breakdown=1.e-16) :
@@ -128,16 +115,14 @@ public:
               const AdditionalData &data=AdditionalData());
 
   /**
-   * Constructor. Use an object of
-   * type GrowingVectorMemory as
-   * a default to allocate memory.
+   * Constructor. Use an object of type GrowingVectorMemory as a default to
+   * allocate memory.
    */
   SolverQMRS (SolverControl        &cn,
               const AdditionalData &data=AdditionalData());
 
   /**
-   * Solve the linear system $Ax=b$
-   * for x.
+   * Solve the linear system $Ax=b$ for x.
    */
   template<class MATRIX, class PRECONDITIONER>
   void
@@ -147,13 +132,9 @@ public:
          const PRECONDITIONER &precondition);
 
   /**
-   * Interface for derived class.
-   * This function gets the current
-   * iteration vector, the residual
-   * and the update vector in each
-   * step. It can be used for a
-   * graphical output of the
-   * convergence history.
+   * Interface for derived class. This function gets the current iteration
+   * vector, the residual and the update vector in each step. It can be used
+   * for a graphical output of the convergence history.
    */
   virtual void print_vectors(const unsigned int step,
                              const VECTOR &x,
@@ -161,16 +142,13 @@ public:
                              const VECTOR &d) const;
 protected:
   /**
-   * Implementation of the computation of
-   * the norm of the residual.
+   * Implementation of the computation of the norm of the residual.
    */
   virtual double criterion();
 
   /**
-   * Temporary vectors, allocated through
-   * the @p VectorMemory object at the start
-   * of the actual solution process and
-   * deallocated at the end.
+   * Temporary vectors, allocated through the @p VectorMemory object at the
+   * start of the actual solution process and deallocated at the end.
    */
   VECTOR *Vv;
   VECTOR *Vp;
@@ -187,14 +165,10 @@ protected:
   const VECTOR *Vb;
 
   /**
-   * Within the iteration loop, the
-   * square of the residual vector is
-   * stored in this variable. The
-   * function @p criterion uses this
-   * variable to compute the convergence
-   * value, which in this class is the
-   * norm of the residual vector and thus
-   * the square root of the @p res2 value.
+   * Within the iteration loop, the square of the residual vector is stored in
+   * this variable. The function @p criterion uses this variable to compute
+   * the convergence value, which in this class is the norm of the residual
+   * vector and thus the square root of the @p res2 value.
    */
   double res2;
 
@@ -206,8 +180,8 @@ protected:
 private:
 
   /**
-   * A structure returned by the iterate() function representing
-   * what it found is happening during the iteration.
+   * A structure returned by the iterate() function representing what it found
+   * is happening during the iteration.
    */
   struct IterationResult
   {
@@ -220,8 +194,8 @@ private:
 
 
   /**
-   * The iteration loop itself. The function returns a structure
-   * indicating what happened in this function.
+   * The iteration loop itself. The function returns a structure indicating
+   * what happened in this function.
    */
   template<class MATRIX, class PRECONDITIONER>
   IterationResult
index 2f38c8c8e9e30700a990527a8a1d839eed8dbc70..5b5b276a865f40d6003c828d839fe38e6de7ad2d 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * Implementation of an iterative solver based on relaxation
- * methods. The stopping criterion is the norm of the residual.
+ * Implementation of an iterative solver based on relaxation methods. The
+ * stopping criterion is the norm of the residual.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes. AdditionalData of this class currently does not
- * contain any data.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
+ * AdditionalData of this class currently does not contain any data.
  *
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @ingroup Solvers
@@ -59,10 +58,8 @@ class SolverRelaxation : public Solver<VECTOR>
 {
 public:
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver. There is no data in
-   * here for relaxation methods.
+   * Standardized data struct to pipe additional data to the solver. There is
+   * no data in here for relaxation methods.
    */
   struct AdditionalData {};
 
@@ -78,11 +75,9 @@ public:
   virtual ~SolverRelaxation ();
 
   /**
-   * Solve the system $Ax = b$
-   * using the relaxation method
-   * $x_{k+1} = R(x_k,b)$. The
-   * amtrix <i>A</i> itself is only
-   * used to compute the residual.
+   * Solve the system $Ax = b$ using the relaxation method $x_{k+1} =
+   * R(x_k,b)$. The amtrix <i>A</i> itself is only used to compute the
+   * residual.
    */
   template<class MATRIX, class RELAXATION>
   void
index 8e389ef04cf6fd1ab85500085c82d5c051f804f3..ec1040b0964bc05d1a37f068e9121f5c8c0d321f 100644 (file)
@@ -29,20 +29,19 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Implementation of the preconditioned Richardson iteration method. The stopping criterion
- * is the norm of the residual.
+ * Implementation of the preconditioned Richardson iteration method. The
+ * stopping criterion is the norm of the residual.
  *
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
  *
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
  *
  * For the Richardson method, the additional data is the damping parameter,
  * which is the only content of the @p AdditionalData structure. By default,
@@ -51,9 +50,9 @@ DEAL_II_NAMESPACE_OPEN
  *
  * <h3>Observing the progress of linear solver iterations</h3>
  *
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
  *
  *
  * @author Ralf Hartmann
@@ -63,16 +62,12 @@ class SolverRichardson : public Solver<VECTOR>
 {
 public:
   /**
-   * Standardized data struct to
-   * pipe additional data to the
-   * solver.
+   * Standardized data struct to pipe additional data to the solver.
    */
   struct AdditionalData
   {
     /**
-     * Constructor. By default,
-     * set the damping parameter
-     * to one.
+     * Constructor. By default, set the damping parameter to one.
      */
     AdditionalData (const double omega                       = 1,
                     const bool   use_preconditioned_residual = false);
@@ -97,9 +92,8 @@ public:
                     const AdditionalData &data=AdditionalData());
 
   /**
-   * Constructor. Use an object of
-   * type GrowingVectorMemory as
-   * a default to allocate memory.
+   * Constructor. Use an object of type GrowingVectorMemory as a default to
+   * allocate memory.
    */
   SolverRichardson (SolverControl        &cn,
                     const AdditionalData &data=AdditionalData());
@@ -110,8 +104,7 @@ public:
   virtual ~SolverRichardson ();
 
   /**
-   * Solve the linear system $Ax=b$
-   * for x.
+   * Solve the linear system $Ax=b$ for x.
    */
   template<class MATRIX, class PRECONDITIONER>
   void
@@ -131,19 +124,14 @@ public:
           const PRECONDITIONER &precondition);
 
   /**
-   * Set the damping-coefficient.
-   * Default is 1., i.e. no damping.
+   * Set the damping-coefficient. Default is 1., i.e. no damping.
    */
   void set_omega (const double om=1.);
 
   /**
-   * Interface for derived class.
-   * This function gets the current
-   * iteration vector, the residual
-   * and the update vector in each
-   * step. It can be used for a
-   * graphical output of the
-   * convergence history.
+   * Interface for derived class. This function gets the current iteration
+   * vector, the residual and the update vector in each step. It can be used
+   * for a graphical output of the convergence history.
    */
   virtual void print_vectors(const unsigned int step,
                              const VECTOR &x,
@@ -152,26 +140,19 @@ public:
 
 protected:
   /**
-   * Implementation of the computation of
-   * the norm of the residual.
+   * Implementation of the computation of the norm of the residual.
    */
   virtual typename VECTOR::value_type criterion();
 
   /**
-   * Residual. Temporary vector allocated through
-   * the VectorMemory object at the start
-   * of the actual solution process and
-   * deallocated at the end.
+   * Residual. Temporary vector allocated through the VectorMemory object at
+   * the start of the actual solution process and deallocated at the end.
    */
   VECTOR *Vr;
   /**
-   * Preconditioned
-   * residual. Temporary vector
-   * allocated through the
-   * VectorMemory object at the
-   * start of the actual solution
-   * process and deallocated at the
-   * end.
+   * Preconditioned residual. Temporary vector allocated through the
+   * VectorMemory object at the start of the actual solution process and
+   * deallocated at the end.
    */
   VECTOR *Vd;
 
@@ -181,14 +162,10 @@ protected:
   AdditionalData additional_data;
 
   /**
-   * Within the iteration loop, the
-   * norm of the residual is
-   * stored in this variable. The
-   * function @p criterion uses this
-   * variable to compute the convergence
-   * value, which in this class is the
-   * norm of the residual vector and thus
-   * the square root of the @p res2 value.
+   * Within the iteration loop, the norm of the residual is stored in this
+   * variable. The function @p criterion uses this variable to compute the
+   * convergence value, which in this class is the norm of the residual vector
+   * and thus the square root of the @p res2 value.
    */
   typename VECTOR::value_type res;
 };
index 3074e24977f07ebdedbf6ebdbc8e8e9979d64f5a..d482b530268bbb283590ce96ef9e3ab02fda598c 100644 (file)
@@ -40,12 +40,11 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * Selects a solver by changing a parameter.
  *
- * By calling the @p solve function of this @p SolverSelector, it selects
- * the @p solve function of that @p Solver that was specified in the constructor
+ * By calling the @p solve function of this @p SolverSelector, it selects the
+ * @p solve function of that @p Solver that was specified in the constructor
  * of this class.
  *
- * <h3>Usage</h3>
- * The simplest use of this class is the following:
+ * <h3>Usage</h3> The simplest use of this class is the following:
  * @code
  *                                  // generate a @p SolverControl and
  *                                  // a @p VectorMemory
@@ -65,10 +64,9 @@ DEAL_II_NAMESPACE_OPEN
  *                                  // preconditioning as last argument
  * solver_selector.solve(A,x,b,preconditioning);
  * @endcode
- * But the full usefulness of the @p SolverSelector class is not
- * clear until the presentation of the following example that assumes
- * the user using the @p ParameterHandler class and having declared a
- * "solver" entry, e.g. with
+ * But the full usefulness of the @p SolverSelector class is not clear until
+ * the presentation of the following example that assumes the user using the
+ * @p ParameterHandler class and having declared a "solver" entry, e.g. with
  * @code
  * Parameter_Handler prm;
  * prm.declare_entry ("solver", "none",
@@ -76,9 +74,9 @@ DEAL_II_NAMESPACE_OPEN
  * ...
  * @endcode
  * Assuming that in the users parameter file there exists the line
- @verbatim
- set solver = cg
- @endverbatim
@verbatim
set solver = cg
@endverbatim
  * then `Line 3' of the above example reads
  * @code
  * SolverSelector<SparseMatrix<double>, Vector<double> >
@@ -102,19 +100,15 @@ class SolverSelector : public Subscriptor
 public:
 
   /**
-   * Constructor, filling in
-   * default values
+   * Constructor, filling in default values
    */
   SolverSelector ();
 
   /**
-   * @deprecated Use the default
-   * constructor, set_control() and select().
+   * @deprecated Use the default constructor, set_control() and select().
    *
-   * Constructor. Use the arguments
-   * to initialize actual solver
-   * objects. The VectorMemory
-   * argument is ignored.
+   * Constructor. Use the arguments to initialize actual solver objects. The
+   * VectorMemory argument is ignored.
    */
   SolverSelector (const std::string    &solvername,
                   SolverControl        &control,
@@ -126,10 +120,8 @@ public:
   ~SolverSelector();
 
   /**
-   * Solver procedure. Calls the @p solve
-   * function
-   * of the @p solver whose @p SolverName
-   * was specified in the constructor.
+   * Solver procedure. Calls the @p solve function of the @p solver whose @p
+   * SolverName was specified in the constructor.
    *
    */
   template<class Matrix, class Preconditioner>
@@ -139,63 +131,54 @@ public:
              const Preconditioner &precond) const;
 
   /**
-   * Select a new solver. Note that
-   * all solver names used in this
-   * class are all lower case.
+   * Select a new solver. Note that all solver names used in this class are
+   * all lower case.
    */
   void select(const std::string &name);
 
   /**
-   * Set a new SolverControl. This needs to
-   * be set before solving.
+   * Set a new SolverControl. This needs to be set before solving.
    */
   void set_control(SolverControl &ctrl);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverRichardson<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverCG<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverMinRes<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverBicgstab<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverGMRES<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Set the additional data. For more
-   * info see the @p Solver class.
+   * Set the additional data. For more info see the @p Solver class.
    */
   void set_data(const typename SolverFGMRES<VECTOR>
                 ::AdditionalData &data);
 
   /**
-   * Get the names of all implemented
-   * solvers.
+   * Get the names of all implemented solvers.
    */
   static std::string get_solver_names ();
 
@@ -210,10 +193,8 @@ public:
 
 protected:
   /**
-   * Stores the @p SolverControl that is
-   * needed in the constructor of each @p
-   * Solver class. This can be changed with
-   * @p set_control().
+   * Stores the @p SolverControl that is needed in the constructor of each @p
+   * Solver class. This can be changed with @p set_control().
    */
   SmartPointer< SolverControl, SolverSelector< VECTOR > >     control;
 
index d2af7d194c83305e7408a97b7e3d4a32a956a238..f5288d31cb8b9fa9eb954e7e1e644bdcb5142aa1 100644 (file)
@@ -28,40 +28,38 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * Abstract base class for incomplete decompositions of a sparse matrix
- * into sparse factors. This class can't be used by itself, but
- * only as the base class of derived classes that actually implement
- * particular decompositions such as SparseILU or SparseMIC.
+ * Abstract base class for incomplete decompositions of a sparse matrix into
+ * sparse factors. This class can't be used by itself, but only as the base
+ * class of derived classes that actually implement particular decompositions
+ * such as SparseILU or SparseMIC.
  *
- * The decomposition is stored as a sparse matrix which is why this
- * class is derived from the SparseMatrix. Since it is not a matrix in
- * the usual sense (the stored entries are not those of a matrix, but
- * of two different matrix factors), the derivation is
- * <tt>protected</tt> rather than <tt>public</tt>.
+ * The decomposition is stored as a sparse matrix which is why this class is
+ * derived from the SparseMatrix. Since it is not a matrix in the usual sense
+ * (the stored entries are not those of a matrix, but of two different matrix
+ * factors), the derivation is <tt>protected</tt> rather than <tt>public</tt>.
  *
  *
  * <h3>Fill-in</h3>
  *
- * Sparse decompositions are frequently used with additional
- * fill-in, i.e., the sparsity structure of the decomposition is denser
- * than that of the matrix to be decomposed. The initialize()
- * function of this class allows this fill-in via the AdditionalData
- * object as long as all entries
- * present in the original matrix are present in the decomposition
- * also, i.e. the sparsity pattern of the decomposition is a superset
- * of the sparsity pattern in the original matrix.
+ * Sparse decompositions are frequently used with additional fill-in, i.e.,
+ * the sparsity structure of the decomposition is denser than that of the
+ * matrix to be decomposed. The initialize() function of this class allows
+ * this fill-in via the AdditionalData object as long as all entries present
+ * in the original matrix are present in the decomposition also, i.e. the
+ * sparsity pattern of the decomposition is a superset of the sparsity pattern
+ * in the original matrix.
  *
- * Such fill-in can be accomplished by various ways, one of which is a
- * copy-constructor of the SparsityPattern class which allows the addition
- * of side-diagonals to a given sparsity structure.
+ * Such fill-in can be accomplished by various ways, one of which is a copy-
+ * constructor of the SparsityPattern class which allows the addition of side-
+ * diagonals to a given sparsity structure.
  *
  *
  * <h3>Unified use of preconditioners</h3>
  *
- * While objects of this class can not be used directly (this class is
- * only a base class for others implementing actual decompositions),
- * derived classes such as SparseILU and SparseMIC can be used in the
- * usual form as preconditioners. For example, this works:
+ * While objects of this class can not be used directly (this class is only a
+ * base class for others implementing actual decompositions), derived classes
+ * such as SparseILU and SparseMIC can be used in the usual form as
+ * preconditioners. For example, this works:
  * @code
  * SparseILU<double> ilu;
  * ilu.initialize(matrix, SparseILU<double>::AdditionalData(...));
@@ -69,25 +67,24 @@ DEAL_II_NAMESPACE_OPEN
  * somesolver.solve (A, x, f, ilu);
  * @endcode
  *
- * Through the AdditionalData object it is possible to specify
- * additional parameters of the LU decomposition.
+ * Through the AdditionalData object it is possible to specify additional
+ * parameters of the LU decomposition.
  *
  * 1/ The matrix diagonals can be strengthened by adding
- * <tt>strengthen_diagonal</tt> times the sum of the absolute row entries
- * of each row to the respective diagonal entries. By default no
- * strengthening is performed.
+ * <tt>strengthen_diagonal</tt> times the sum of the absolute row entries of
+ * each row to the respective diagonal entries. By default no strengthening is
+ * performed.
  *
- * 2/ By default, each initialize() function call creates its own
- * sparsity. For that, it copies the sparsity of <tt>matrix</tt> and adds a
- * specific number of extra off diagonal entries specified by
+ * 2/ By default, each initialize() function call creates its own sparsity.
+ * For that, it copies the sparsity of <tt>matrix</tt> and adds a specific
+ * number of extra off diagonal entries specified by
  * <tt>extra_off_diagonals</tt>.
  *
  * 3/ By setting <tt>use_previous_sparsity=true</tt> the sparsity is not
- * recreated but the sparsity of the previous initialize() call is
- * reused (recycled). This might be useful when several linear
- * problems on the same sparsity need to solved, as for example
- * several Newton iteration steps on the same triangulation. The
- * default is <tt>false</tt>.
+ * recreated but the sparsity of the previous initialize() call is reused
+ * (recycled). This might be useful when several linear problems on the same
+ * sparsity need to solved, as for example several Newton iteration steps on
+ * the same triangulation. The default is <tt>false</tt>.
  *
  * 4/ It is possible to give a user defined sparsity to
  * <tt>use_this_sparsity</tt>. Then, no sparsity is created but
@@ -97,44 +94,41 @@ DEAL_II_NAMESPACE_OPEN
  *
  * <h3>State management</h3>
  *
- * The state management simply requires the initialize() function to
- * be called before the object is used as preconditioner.
+ * The state management simply requires the initialize() function to be called
+ * before the object is used as preconditioner.
  *
- * <b>Obsolete:</b>
- * In order to prevent users from applying decompositions before the
- * decomposition itself has been built, and to introduce some
- * optimization of common "sparse idioms", this class introduces a
- * simple state management.  A SparseLUdecomposition instance is
- * considered not decomposed if the decompose method has not yet
- * been invoked since the last time the underlying SparseMatrix
- * had changed. The underlying sparse matrix is considered changed
- * when one of this class reinit methods, constructors or destructors
- * are invoked.  The not-decomposed state is indicated by a false
- * value returned by is_decomposed() method.  It is illegal to apply
- * this decomposition (vmult() method) in not decomposed state; in
- * this case, the vmult() method throws an <tt>ExcInvalidState</tt>
- * exception. This object turns into decomposed state immediately
- * after its decompose() method is invoked. The decomposed
- * state is indicated by true value returned by is_decomposed()
- * method. It is legal to apply this decomposition (vmult() method) in
- * decomposed state.
+ * <b>Obsolete:</b> In order to prevent users from applying decompositions
+ * before the decomposition itself has been built, and to introduce some
+ * optimization of common "sparse idioms", this class introduces a simple
+ * state management.  A SparseLUdecomposition instance is considered not
+ * decomposed if the decompose method has not yet been invoked since the last
+ * time the underlying SparseMatrix had changed. The underlying sparse matrix
+ * is considered changed when one of this class reinit methods, constructors
+ * or destructors are invoked.  The not-decomposed state is indicated by a
+ * false value returned by is_decomposed() method.  It is illegal to apply
+ * this decomposition (vmult() method) in not decomposed state; in this case,
+ * the vmult() method throws an <tt>ExcInvalidState</tt> exception. This
+ * object turns into decomposed state immediately after its decompose() method
+ * is invoked. The decomposed state is indicated by true value returned by
+ * is_decomposed() method. It is legal to apply this decomposition (vmult()
+ * method) in decomposed state.
  *
  * <h3>Particular implementations</h3>
  *
- * It is enough to override the initialize() and vmult() methods to
- * implement particular LU decompositions, like the true LU, or the
- * Cholesky decomposition. Additionally, if that decomposition needs
- * fine tuned diagonal strengthening on a per row basis, it may override the
- * get_strengthen_diagonal() method. You should invoke the non-abstract
- * base class method to employ the state management. Implementations
- * may choose more restrictive definition of what is legal or illegal
- * state; but they must conform to the is_decomposed() method
- * specification above.
+ * It is enough to override the initialize() and vmult() methods to implement
+ * particular LU decompositions, like the true LU, or the Cholesky
+ * decomposition. Additionally, if that decomposition needs fine tuned
+ * diagonal strengthening on a per row basis, it may override the
+ * get_strengthen_diagonal() method. You should invoke the non-abstract base
+ * class method to employ the state management. Implementations may choose
+ * more restrictive definition of what is legal or illegal state; but they
+ * must conform to the is_decomposed() method specification above.
  *
- * If an exception is thrown by method other than vmult(), this
- * object may be left in an inconsistent state.
+ * If an exception is thrown by method other than vmult(), this object may be
+ * left in an inconsistent state.
  *
- * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003
+ * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation
+ * by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003
  */
 template <typename number>
 class SparseLUDecomposition : protected SparseMatrix<number>,
@@ -144,20 +138,16 @@ protected:
   /**
    * Constructor. Does nothing.
    *
-   * Call the initialize()
-   * function before using this
-   * object as preconditioner
+   * Call the initialize() function before using this object as preconditioner
    * (vmult()).
    */
   SparseLUDecomposition ();
 
   /**
-   * @deprecated This method is deprecated, and
-   * left for backward
-   * compatibility. It will be removed
-   * in later versions.
-   * Instead, pass the sparsity pattern that you want used for
-   * the decomposition in the AdditionalData structure.
+   * @deprecated This method is deprecated, and left for backward
+   * compatibility. It will be removed in later versions. Instead, pass the
+   * sparsity pattern that you want used for the decomposition in the
+   * AdditionalData structure.
    */
   SparseLUDecomposition (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
 
@@ -168,33 +158,25 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Destruction. Mark the
-   * destructor pure to ensure that
-   * this class isn't used
-   * directly, but only its derived
-   * classes.
+   * Destruction. Mark the destructor pure to ensure that this class isn't
+   * used directly, but only its derived classes.
    */
   virtual ~SparseLUDecomposition () = 0;
 
   /**
-   * Deletes all member
-   * variables. Leaves the class in
-   * the state that it had directly
-   * after calling the constructor
+   * Deletes all member variables. Leaves the class in the state that it had
+   * directly after calling the constructor
    */
   virtual void clear();
 
   /**
-   * Parameters for
-   * SparseDecomposition.
+   * Parameters for SparseDecomposition.
    */
   class AdditionalData
   {
   public:
     /**
-     * Constructor. For the
-     * parameters' description,
-     * see below.
+     * Constructor. For the parameters' description, see below.
      */
     AdditionalData (const double strengthen_diagonal=0,
                     const unsigned int extra_off_diagonals=0,
@@ -202,124 +184,77 @@ public:
                     const SparsityPattern *use_this_sparsity=0);
 
     /**
-     * <tt>strengthen_diag</tt> times
-     * the sum of absolute row
-     * entries is added to the
-     * diagonal entries.
+     * <tt>strengthen_diag</tt> times the sum of absolute row entries is added
+     * to the diagonal entries.
      *
-     * Per default, this value is
-     * zero, i.e. the diagonal is
-     * not strengthened.
+     * Per default, this value is zero, i.e. the diagonal is not strengthened.
      */
     double strengthen_diagonal;
 
     /**
-     * By default, the
-     * <tt>initialize(matrix,
-     * data)</tt> function creates
-     * its own sparsity. This
-     * sparsity has the same
-     * SparsityPattern as
-     * <tt>matrix</tt> with some extra
-     * off diagonals the number
-     * of which is specified by
-     * <tt>extra_off_diagonals</tt>.
+     * By default, the <tt>initialize(matrix, data)</tt> function creates its
+     * own sparsity. This sparsity has the same SparsityPattern as
+     * <tt>matrix</tt> with some extra off diagonals the number of which is
+     * specified by <tt>extra_off_diagonals</tt>.
      *
-     * The user can give a
-     * SparsityPattern to
-     * <tt>use_this_sparsity</tt>. Then
-     * this sparsity is used and
-     * the
-     * <tt>extra_off_diagonals</tt>
-     * argument is ignored.
+     * The user can give a SparsityPattern to <tt>use_this_sparsity</tt>. Then
+     * this sparsity is used and the <tt>extra_off_diagonals</tt> argument is
+     * ignored.
      */
     unsigned int extra_off_diagonals;
 
     /**
-     * If this flag is true the
-     * initialize() function uses
-     * the same sparsity that was
-     * used during the previous
-     * initialize() call.
+     * If this flag is true the initialize() function uses the same sparsity
+     * that was used during the previous initialize() call.
      *
-     * This might be useful when
-     * several linear problems on
-     * the same sparsity need to
-     * solved, as for example
-     * several Newton iteration
-     * steps on the same
-     * triangulation.
+     * This might be useful when several linear problems on the same sparsity
+     * need to solved, as for example several Newton iteration steps on the
+     * same triangulation.
      */
     bool use_previous_sparsity;
 
     /**
-     * When a
-     * SparsityPattern is
-     * given to this argument,
-     * the initialize()
-     * function calls
-     * <tt>reinit(*use_this_sparsity)</tt>
-     * causing this sparsity to
-     * be used.
+     * When a SparsityPattern is given to this argument, the initialize()
+     * function calls <tt>reinit(*use_this_sparsity)</tt> causing this
+     * sparsity to be used.
      *
-     * Note that the sparsity structures
-     * of <tt>*use_this_sparsity</tt> and
-     * the matrix passed to the
-     * initialize function need not be
-     * equal. Fill-in is allowed, as well
-     * as filtering out some elements in
-     * the matrix.
+     * Note that the sparsity structures of <tt>*use_this_sparsity</tt> and
+     * the matrix passed to the initialize function need not be equal. Fill-in
+     * is allowed, as well as filtering out some elements in the matrix.
      */
     const SparsityPattern *use_this_sparsity;
   };
 
   /**
-   * This function needs to be
-   * called before an object of
-   * this class is used as
-   * preconditioner.
+   * This function needs to be called before an object of this class is used
+   * as preconditioner.
    *
-   * For more detail about possible
-   * parameters, see the class
-   * documentation and the
-   * documentation of the
-   * SparseLUDecomposition::AdditionalData
-   * class.
+   * For more detail about possible parameters, see the class documentation
+   * and the documentation of the SparseLUDecomposition::AdditionalData class.
    *
-   * According to the
-   * <tt>parameters</tt>, this function
-   * creates a new SparsityPattern
-   * or keeps the previous sparsity
-   * or takes the sparsity given by
-   * the user to <tt>data</tt>. Then,
-   * this function performs the LU
+   * According to the <tt>parameters</tt>, this function creates a new
+   * SparsityPattern or keeps the previous sparsity or takes the sparsity
+   * given by the user to <tt>data</tt>. Then, this function performs the LU
    * decomposition.
    *
-   * After this function is called
-   * the preconditioner is ready to
-   * be used (using the
-   * <code>vmult</code> function of
-   * derived classes).
+   * After this function is called the preconditioner is ready to be used
+   * (using the <code>vmult</code> function of derived classes).
    */
   template <typename somenumber>
   void initialize (const SparseMatrix<somenumber> &matrix,
                    const AdditionalData parameters);
 
   /**
-   * This method is deprecated,
-   * and left for backward
-   * compatibility. It will be removed
-   * in later versions.
+   * This method is deprecated, and left for backward compatibility. It will
+   * be removed in later versions.
    *
    * @deprecated
    */
   void reinit (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
 
   /**
-   * This method is deprecated,
-   * and left for backward
-   * compability. It will be removed
-   * in later versions.
+   * This method is deprecated, and left for backward compability. It will be
+   * removed in later versions.
    *
    * @deprecated
    */
@@ -328,31 +263,29 @@ public:
                   const double                    strengthen_diagonal=0.) DEAL_II_DEPRECATED;
 
   /**
-   * This method is deprecated,
-   * and left for backward
-   * compability. It will be removed
-   * in later versions.
+   * This method is deprecated, and left for backward compability. It will be
+   * removed in later versions.
    *
    * @deprecated
    */
   virtual bool is_decomposed () const DEAL_II_DEPRECATED;
 
   /**
-   * Return whether the object is
-   * empty. It calls the inherited
+   * Return whether the object is empty. It calls the inherited
    * SparseMatrix::empty() function.
    */
   bool empty () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   virtual std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -364,97 +297,62 @@ public:
   //@}
 protected:
   /**
-   * Copies the passed SparseMatrix
-   * onto this object. This
-   * object's sparsity pattern
-   * remains unchanged.
+   * Copies the passed SparseMatrix onto this object. This object's sparsity
+   * pattern remains unchanged.
    */
   template<typename somenumber>
   void copy_from (const SparseMatrix<somenumber> &matrix);
 
   /**
-   * Performs the strengthening
-   * loop. For each row calculates
-   * the sum of absolute values of
-   * its elements, determines the
-   * strengthening factor (through
-   * get_strengthen_diagonal())
-   * sf and multiplies the diagonal
-   * entry with <tt>sf+1</tt>.
+   * Performs the strengthening loop. For each row calculates the sum of
+   * absolute values of its elements, determines the strengthening factor
+   * (through get_strengthen_diagonal()) sf and multiplies the diagonal entry
+   * with <tt>sf+1</tt>.
    */
   virtual void strengthen_diagonal_impl ();
 
   /**
-   * In the decomposition phase,
-   * computes a strengthening
-   * factor for the diagonal entry
-   * in row <tt>row</tt> with sum of
-   * absolute values of its
+   * In the decomposition phase, computes a strengthening factor for the
+   * diagonal entry in row <tt>row</tt> with sum of absolute values of its
    * elements <tt>rowsum</tt>.<br> Note:
-   * The default implementation in
-   * SparseLUDecomposition
-   * returns
-   * <tt>strengthen_diagonal</tt>'s
-   * value.
+   * The default implementation in SparseLUDecomposition returns
+   * <tt>strengthen_diagonal</tt>'s value.
    */
   virtual number get_strengthen_diagonal(const number rowsum, const size_type row) const;
 
   /**
-   * State flag. If not in
-   * decomposed state, it is
-   * illegal to apply the
-   * decomposition.  This flag is
-   * cleared when the underlaying
-   * SparseMatrix
-   * SparsityPattern is
-   * changed, and set by
-   * decompose().
+   * State flag. If not in decomposed state, it is illegal to apply the
+   * decomposition.  This flag is cleared when the underlaying SparseMatrix
+   * SparsityPattern is changed, and set by decompose().
    */
   bool decomposed;
 
   /**
-   * The default strengthening
-   * value, returned by
-   * get_strengthen_diagonal().
+   * The default strengthening value, returned by get_strengthen_diagonal().
    */
   double  strengthen_diagonal;
 
   /**
-   * For every row in the
-   * underlying
-   * SparsityPattern, this
-   * array contains a pointer
-   * to the row's first
-   * afterdiagonal entry. Becomes
-   * available after invocation of
-   * decompose().
+   * For every row in the underlying SparsityPattern, this array contains a
+   * pointer to the row's first afterdiagonal entry. Becomes available after
+   * invocation of decompose().
    */
   std::vector<const size_type *> prebuilt_lower_bound;
 
 private:
   /**
-   * Fills the
-   * #prebuilt_lower_bound
-   * array.
+   * Fills the #prebuilt_lower_bound array.
    */
   void prebuild_lower_bound ();
 
   /**
-   * In general this pointer is
-   * zero except for the case that
-   * no SparsityPattern is
-   * given to this class. Then, a
-   * SparsityPattern is created
-   * and is passed down to the
-   * SparseMatrix base class.
+   * In general this pointer is zero except for the case that no
+   * SparsityPattern is given to this class. Then, a SparsityPattern is
+   * created and is passed down to the SparseMatrix base class.
    *
-   * Nevertheless, the
-   * SparseLUDecomposition
-   * needs to keep ownership of
-   * this sparsity. It keeps this
-   * pointer to it enabling it to
-   * delete this sparsity at
-   * destruction time.
+   * Nevertheless, the SparseLUDecomposition needs to keep ownership of this
+   * sparsity. It keeps this pointer to it enabling it to delete this sparsity
+   * at destruction time.
    */
   SparsityPattern *own_sparsity;
 };
index f45a038a187a9da0171c8d31a04a8f358efa0ff7..f066f7b06229c39345631a2658ac5c41234ad890 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class provides an interface to the sparse direct solver
- * UMFPACK (see <a
- * href="http://www.cise.ufl.edu/research/sparse/umfpack">this
- * link</a>). UMFPACK is a set of routines for solving non-symmetric
- * sparse linear systems, Ax=b, using the Unsymmetric-pattern
- * MultiFrontal method and direct sparse LU factorization. Matrices
- * may have symmetric or unsymmetrix sparsity patterns, and may have
- * unsymmetric entries. The use of this class is explained in the @ref
- * step_22 "step-22" and @ref
- * step_29 "step-29" tutorial programs.
+ * This class provides an interface to the sparse direct solver UMFPACK (see
+ * <a href="http://www.cise.ufl.edu/research/sparse/umfpack">this link</a>).
+ * UMFPACK is a set of routines for solving non-symmetric sparse linear
+ * systems, Ax=b, using the Unsymmetric-pattern MultiFrontal method and direct
+ * sparse LU factorization. Matrices may have symmetric or unsymmetrix
+ * sparsity patterns, and may have unsymmetric entries. The use of this class
+ * is explained in the @ref step_22 "step-22" and @ref step_29 "step-29"
+ * tutorial programs.
  *
- * This matrix class implements the usual interface of
- * preconditioners, that is a function initialize(const
- * SparseMatrix<double>&matrix,const AdditionalData) for initalizing
- * and the whole set of vmult() functions common to all
- * matrices. Implemented here are only vmult() and vmult_add(), which
- * perform multiplication with the inverse matrix. Furthermore, this
- * class provides an older interface, consisting of the functions
- * factorize() and solve(). Both interfaces are interchangeable.
+ * This matrix class implements the usual interface of preconditioners, that
+ * is a function initialize(const SparseMatrix<double>&matrix,const
+ * AdditionalData) for initalizing and the whole set of vmult() functions
+ * common to all matrices. Implemented here are only vmult() and vmult_add(),
+ * which perform multiplication with the inverse matrix. Furthermore, this
+ * class provides an older interface, consisting of the functions factorize()
+ * and solve(). Both interfaces are interchangeable.
  *
  * @note This class only exists if support for <a
  * href="http://www.cise.ufl.edu/research/sparse/umfpack">UMFPACK</a> was
@@ -96,8 +93,8 @@ public:
 
 
   /**
-   * Constructor. See the documentation of this class for the meaning of
-   * the parameters to this function.
+   * Constructor. See the documentation of this class for the meaning of the
+   * parameters to this function.
    */
   SparseDirectUMFPACK ();
 
@@ -121,21 +118,20 @@ public:
 
   /**
    * Factorize the matrix. This function may be called multiple times for
-   * different matrices, after the object of this class has been
-   * initialized for a certain sparsity pattern. You may therefore save
-   * some computing time if you want to invert several matrices with the
-   * same sparsity pattern. However, note that the bulk of the computing
-   * time is actually spent in the factorization, so this functionality may
-   * not always be of large benefit.
+   * different matrices, after the object of this class has been initialized
+   * for a certain sparsity pattern. You may therefore save some computing
+   * time if you want to invert several matrices with the same sparsity
+   * pattern. However, note that the bulk of the computing time is actually
+   * spent in the factorization, so this functionality may not always be of
+   * large benefit.
    *
-   * In contrast to the other direct solver classes, the initialisation
-   * method does nothing. Therefore initialise is not automatically called
-   * by this method, when the initialization step has not been performed
-   * yet.
+   * In contrast to the other direct solver classes, the initialisation method
+   * does nothing. Therefore initialise is not automatically called by this
+   * method, when the initialization step has not been performed yet.
    *
-   * This function copies the contents of the matrix into its own storage;
-   * the matrix can therefore be deleted after this operation, even if
-   * subsequent solves are required.
+   * This function copies the contents of the matrix into its own storage; the
+   * matrix can therefore be deleted after this operation, even if subsequent
+   * solves are required.
    */
   template <class Matrix>
   void factorize (const Matrix &matrix);
@@ -159,14 +155,13 @@ public:
    */
 
   /**
-   * Preconditioner interface function. Usually, given the source vector,
-   * this method returns an approximate solution of <i>Ax = b</i>. As this
-   * class provides a wrapper to a direct solver, here it is actually the
-   * exact solution (exact within the range of numerical accuracy of
-   * course).
+   * Preconditioner interface function. Usually, given the source vector, this
+   * method returns an approximate solution of <i>Ax = b</i>. As this class
+   * provides a wrapper to a direct solver, here it is actually the exact
+   * solution (exact within the range of numerical accuracy of course).
    *
-   * In other words, this function actually multiplies with the exact
-   * inverse of the matrix, $A^{-1}$.
+   * In other words, this function actually multiplies with the exact inverse
+   * of the matrix, $A^{-1}$.
    */
   void vmult (Vector<double> &dst,
               const Vector<double> &src) const;
@@ -178,8 +173,8 @@ public:
               const BlockVector<double> &src) const;
 
   /**
-   * Same as before, but uses the transpose of the matrix, i.e. this
-   * function multiplies with $A^{-T}$.
+   * Same as before, but uses the transpose of the matrix, i.e. this function
+   * multiplies with $A^{-T}$.
    */
   void Tvmult (Vector<double> &dst,
                const Vector<double> &src) const;
@@ -191,15 +186,15 @@ public:
                const BlockVector<double> &src) const;
 
   /**
-   * Same as vmult(), but adding to the previous solution. Not implemented
-   * yet but necessary for compiling certain other classes.
+   * Same as vmult(), but adding to the previous solution. Not implemented yet
+   * but necessary for compiling certain other classes.
    */
   void vmult_add (Vector<double> &dst,
                   const Vector<double> &src) const;
 
   /**
-   * Same as before, but uses the transpose of the matrix, i.e. this
-   * function multiplies with $A^{-T}$.
+   * Same as before, but uses the transpose of the matrix, i.e. this function
+   * multiplies with $A^{-T}$.
    */
   void Tvmult_add (Vector<double> &dst,
                    const Vector<double> &src) const;
@@ -216,21 +211,19 @@ public:
    */
 
   /**
-   * Solve for a certain right hand side vector. This function may be
-   * called multiple times for different right hand side vectors after the
-   * matrix has been factorized. This yields a big saving in computing
-   * time, since the actual solution is fast, compared to the factorization
-   * of the matrix.
+   * Solve for a certain right hand side vector. This function may be called
+   * multiple times for different right hand side vectors after the matrix has
+   * been factorized. This yields a big saving in computing time, since the
+   * actual solution is fast, compared to the factorization of the matrix.
    *
    * The solution will be returned in place of the right hand side vector.
    *
-   * If the factorization has not happened before, strange things will
-   * happen. Note that we can't actually call the factorize() function from
-   * here if it has not yet been called, since we have no access to the
-   * actual matrix.
+   * If the factorization has not happened before, strange things will happen.
+   * Note that we can't actually call the factorize() function from here if it
+   * has not yet been called, since we have no access to the actual matrix.
    *
-   * If @p transpose is set to true this function solves for the transpose
-   * of the matrix, i.e. $x=A^{-T}b$.
+   * If @p transpose is set to true this function solves for the transpose of
+   * the matrix, i.e. $x=A^{-T}b$.
    */
   void solve (Vector<double> &rhs_and_solution, bool transpose = false) const;
 
@@ -240,8 +233,8 @@ public:
   void solve (BlockVector<double> &rhs_and_solution, bool transpose = false) const;
 
   /**
-   * Call the two functions factorize() and solve() in that order, i.e. perform
-   * the whole solution process for the given right hand side vector.
+   * Call the two functions factorize() and solve() in that order, i.e.
+   * perform the whole solution process for the given right hand side vector.
    *
    * The solution will be returned in place of the right hand side vector.
    */
@@ -263,9 +256,9 @@ public:
    */
 
   /**
-   * One of the UMFPack routines threw an error. The error code is included
-   * in the output and can be looked up in the UMFPack user manual. The
-   * name of the routine is included for reference.
+   * One of the UMFPack routines threw an error. The error code is included in
+   * the output and can be looked up in the UMFPack user manual. The name of
+   * the routine is included for reference.
    */
   DeclException2 (ExcUMFPACKError, char *, int,
                   << "UMFPACK routine " << arg1
@@ -276,9 +269,8 @@ public:
 private:
   /**
    * The UMFPACK routines allocate objects in which they store information
-   * about symbolic and numeric values of the decomposition. The actual
-   * data type of these objects is opaque, and only passed around as void
-   * pointers.
+   * about symbolic and numeric values of the decomposition. The actual data
+   * type of these objects is opaque, and only passed around as void pointers.
    */
   void *symbolic_decomposition;
   void *numeric_decomposition;
@@ -289,10 +281,10 @@ private:
   void clear ();
 
   /**
-   * Make sure that the arrays Ai and Ap are sorted in each row. UMFPACK
-   * wants it this way. We need to have three versions of this function,
-   * one for the usual SparseMatrix, one for the SparseMatrixEZ, and one
-   * for the BlockSparseMatrix classes
+   * Make sure that the arrays Ai and Ap are sorted in each row. UMFPACK wants
+   * it this way. We need to have three versions of this function, one for the
+   * usual SparseMatrix, one for the SparseMatrixEZ, and one for the
+   * BlockSparseMatrix classes
    */
   template <typename number>
   void sort_arrays (const SparseMatrixEZ<number> &);
@@ -318,11 +310,11 @@ private:
 
 
 /**
- * This class provides an interface to the parallel sparse direct solver
- * <a href="http://mumps.enseeiht.fr">MUMPS</a>. MUMPS is direct method
- * based on a multifrontal approach, which performs a direct LU
- * factorization. The matrix coming in may have either symmetric or
- * nonsymmetric sparsity pattern.
+ * This class provides an interface to the parallel sparse direct solver <a
+ * href="http://mumps.enseeiht.fr">MUMPS</a>. MUMPS is direct method based on
+ * a multifrontal approach, which performs a direct LU factorization. The
+ * matrix coming in may have either symmetric or nonsymmetric sparsity
+ * pattern.
  *
  * @note This class is useable if and only if a working installation of <a
  * href="http://mumps.enseeiht.fr">MUMPS</a> exists on your system and was
@@ -397,24 +389,23 @@ public:
 
   /**
    * This function initializes a MUMPS instance and hands over the system's
-   * matrix <tt>matrix</tt> and right-hand side <tt>vector</tt> to the
-   * solver.
+   * matrix <tt>matrix</tt> and right-hand side <tt>vector</tt> to the solver.
    */
   template <class Matrix>
   void initialize (const Matrix &matrix,
                    const Vector<double>       &vector);
 
   /**
-   * This function initializes a MUMPS instance and computes the
-   * factorization of the system's matrix <tt>matrix</tt>.
+   * This function initializes a MUMPS instance and computes the factorization
+   * of the system's matrix <tt>matrix</tt>.
    */
   template <class Matrix>
   void initialize (const Matrix &matrix);
 
   /**
-   * A function in which the linear system is solved and the solution
-   * vector is copied into the given <tt>vector</tt>. The right-hand side
-   * need to be supplied in initialize(matrix, vector);
+   * A function in which the linear system is solved and the solution vector
+   * is copied into the given <tt>vector</tt>. The right-hand side need to be
+   * supplied in initialize(matrix, vector);
    */
   void solve (Vector<double> &vector);
 
index dab89efefa978bdc0ec22f7bb04b103beaaae90a..b5bb0b366ae5ae3e37a870536af953824be44fe0 100644 (file)
@@ -30,23 +30,22 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * This class computes an Incomplete LU (ILU) decomposition of a sparse matrix,
- * using either the same sparsity pattern or a different one.
- * By incomplete we mean that unlike the exact decomposition, the incomplete
- * one is also computed using sparse factors, and entries
- * in the decomposition that do not fit into the given sparsity structure
- * are discarded.
+ * This class computes an Incomplete LU (ILU) decomposition of a sparse
+ * matrix, using either the same sparsity pattern or a different one. By
+ * incomplete we mean that unlike the exact decomposition, the incomplete one
+ * is also computed using sparse factors, and entries in the decomposition
+ * that do not fit into the given sparsity structure are discarded.
  *
- * The algorithm used by this class is essentially a copy of the
- * algorithm given in the book Y. Saad: "Iterative methods for sparse
- * linear systems", second edition, in section 10.3.2.
+ * The algorithm used by this class is essentially a copy of the algorithm
+ * given in the book Y. Saad: "Iterative methods for sparse linear systems",
+ * second edition, in section 10.3.2.
  *
  *
  * <h3>Usage and state management</h3>
  *
- * Refer to SparseLUDecomposition documentation for suggested
- * usage and state management. This class is used in the @ref
- * step_22 "step-22" tutorial program.
+ * Refer to SparseLUDecomposition documentation for suggested usage and state
+ * management. This class is used in the @ref step_22 "step-22" tutorial
+ * program.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -66,26 +65,21 @@ public:
   /**
    * Constructor. Does nothing.
    *
-   * Call the @p initialize
-   * function before using this
-   * object as preconditioner.
+   * Call the @p initialize function before using this object as
+   * preconditioner.
    */
   SparseILU ();
 
   /**
-   * @deprecated This method is deprecated, and
-   * left for backward
-   * compatibility. It will be removed
-   * in later versions.
-   * Instead, pass the sparsity pattern that you want used for
-   * the decomposition in the AdditionalData structure.
+   * @deprecated This method is deprecated, and left for backward
+   * compatibility. It will be removed in later versions. Instead, pass the
+   * sparsity pattern that you want used for the decomposition in the
+   * AdditionalData structure.
    */
   SparseILU (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
 
   /**
-   * Make
-   * SparseLUDecomposition::AdditionalData
-   * accessible to this class as
+   * Make SparseLUDecomposition::AdditionalData accessible to this class as
    * well.
    */
   typedef
@@ -93,65 +87,47 @@ public:
   AdditionalData;
 
   /**
-   * Perform the incomplete LU
-   * factorization of the given
-   * matrix.
+   * Perform the incomplete LU factorization of the given matrix.
    *
-   * This function needs to be
-   * called before an object of
-   * this class is used as
-   * preconditioner.
+   * This function needs to be called before an object of this class is used
+   * as preconditioner.
    *
-   * For more details about
-   * possible parameters, see the
-   * class documentation of
-   * SparseLUDecomposition and the
-   * documentation of the
-   * @p SparseLUDecomposition::AdditionalData
-   * class.
+   * For more details about possible parameters, see the class documentation
+   * of SparseLUDecomposition and the documentation of the @p
+   * SparseLUDecomposition::AdditionalData class.
    *
-   * According to the
-   * @p parameters, this function
-   * creates a new SparsityPattern
-   * or keeps the previous sparsity
-   * or takes the sparsity given by
-   * the user to @p data. Then,
-   * this function performs the LU
+   * According to the @p parameters, this function creates a new
+   * SparsityPattern or keeps the previous sparsity or takes the sparsity
+   * given by the user to @p data. Then, this function performs the LU
    * decomposition.
    *
-   * After this function is called
-   * the preconditioner is ready to
-   * be used.
+   * After this function is called the preconditioner is ready to be used.
    */
   template <typename somenumber>
   void initialize (const SparseMatrix<somenumber> &matrix,
                    const AdditionalData &parameters = AdditionalData());
 
   /**
-   * @deprecated This method is deprecated, and left for backward
-   * compability. It will be removed in later versions.
+   * @deprecated This method is deprecated, and left for backward compability.
+   * It will be removed in later versions.
    */
   template <typename somenumber>
   void decompose (const SparseMatrix<somenumber> &matrix,
                   const double                    strengthen_diagonal=0.) DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This method is deprecated, and
-   * left for backward
-   * compatibility. It will be
-   * removed in later versions.
+   * @deprecated This method is deprecated, and left for backward
+   * compatibility. It will be removed in later versions.
    */
   template <typename somenumber>
   void apply_decomposition (Vector<somenumber>       &dst,
                             const Vector<somenumber> &src) const DEAL_II_DEPRECATED;
 
   /**
-   * Apply the incomplete decomposition,
-   * i.e. do one forward-backward step
+   * Apply the incomplete decomposition, i.e. do one forward-backward step
    * $dst=(LU)^{-1}src$.
    *
-   * The initialize() function
-   * needs to be called before.
+   * The initialize() function needs to be called before.
    */
   template <typename somenumber>
   void vmult (Vector<somenumber>       &dst,
@@ -159,13 +135,10 @@ public:
 
 
   /**
-   * Apply the transpose of the
-   * incomplete decomposition,
-   * i.e. do one forward-backward step
-   * $dst=(LU)^{-T}src$.
+   * Apply the transpose of the incomplete decomposition, i.e. do one forward-
+   * backward step $dst=(LU)^{-T}src$.
    *
-   * The initialize() function
-   * needs to be called before.
+   * The initialize() function needs to be called before.
    */
   template <typename somenumber>
   void Tvmult (Vector<somenumber>       &dst,
@@ -173,14 +146,15 @@ public:
 
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
index 2b90904b1b501066686291d7377919d2866aab4f..c797be97a3c1c406862839d07eeb1f6837f9e1fb 100644 (file)
@@ -300,8 +300,8 @@ namespace SparseMatrixIterators
     friend class Iterator;
 
     /**
-     * Make the SparseMatrix class a friend so that it, in turn, can
-     * declare the Reference class a friend.
+     * Make the SparseMatrix class a friend so that it, in turn, can declare
+     * the Reference class a friend.
      */
     template <typename> friend class dealii::SparseMatrix;
   };
@@ -311,12 +311,11 @@ namespace SparseMatrixIterators
   /**
    * STL conforming iterator for constant and non-constant matrices.
    *
-   * The typical use for these iterators is to iterate over the elements of
-   * a sparse matrix
-   * or over the elements of individual rows. Note that there is no guarantee
-   * that the elements of a row are actually traversed in an order in which
-   * columns monotonically increase. See the documentation of the
-   * SparsityPattern class for more information.
+   * The typical use for these iterators is to iterate over the elements of a
+   * sparse matrix or over the elements of individual rows. Note that there is
+   * no guarantee that the elements of a row are actually traversed in an
+   * order in which columns monotonically increase. See the documentation of
+   * the SparsityPattern class for more information.
    *
    * The first template argument denotes the underlying numeric type, the
    * second the constness of the matrix.
@@ -326,17 +325,17 @@ namespace SparseMatrixIterators
    * matrices.
    *
    * @note This class operates directly on the internal data structures of the
-   * SparsityPattern and SparseMatrix classes. As a consequence, some operations
-   * are cheap and some are not. In particular, it is cheap to access the column
-   * index and the value of an entry pointed to. On the other hand, it is expensive
-   * to access the row index (this requires $O(\log(N))$ operations for a
-   * matrix with $N$ row). As a consequence, when you design algorithms that
-   * use these iterators, it is common practice to not loop over <i>all</i>
-   * elements of a sparse matrix at once, but to have an outer loop over
-   * all rows and within this loop iterate over the elements of this row.
-   * This way, you only ever need to dereference the iterator to obtain
-   * the column indices and values whereas the (expensive) lookup of the row index
-   * can be avoided by using the loop index instead.
+   * SparsityPattern and SparseMatrix classes. As a consequence, some
+   * operations are cheap and some are not. In particular, it is cheap to
+   * access the column index and the value of an entry pointed to. On the
+   * other hand, it is expensive to access the row index (this requires
+   * $O(\log(N))$ operations for a matrix with $N$ row). As a consequence,
+   * when you design algorithms that use these iterators, it is common
+   * practice to not loop over <i>all</i> elements of a sparse matrix at once,
+   * but to have an outer loop over all rows and within this loop iterate over
+   * the elements of this row. This way, you only ever need to dereference the
+   * iterator to obtain the column indices and values whereas the (expensive)
+   * lookup of the row index can be avoided by using the loop index instead.
    */
   template <typename number, bool Constness>
   class Iterator
@@ -350,8 +349,8 @@ namespace SparseMatrixIterators
     MatrixType;
 
     /**
-     * A typedef for the type you get when you dereference an iterator
-     * of the current kind.
+     * A typedef for the type you get when you dereference an iterator of the
+     * current kind.
      */
     typedef
     const Accessor<number,Constness> &value_type;
@@ -431,10 +430,10 @@ namespace SparseMatrixIterators
     bool operator > (const Iterator &) const;
 
     /**
-     * Return the distance between the current iterator and the argument.
-     * The distance is given by how many times one has to apply operator++
-     * to the current iterator to get the argument (for a positive return
-     * value), or operator-- (for a negative return value).
+     * Return the distance between the current iterator and the argument. The
+     * distance is given by how many times one has to apply operator++ to the
+     * current iterator to get the argument (for a positive return value), or
+     * operator-- (for a negative return value).
      */
     int operator - (const Iterator &p) const;
 
@@ -460,25 +459,24 @@ namespace SparseMatrixIterators
 //TODO: Add multithreading to the other vmult functions.
 
 /**
- * Sparse matrix. This class implements the function to store values
- * in the locations of a sparse matrix denoted by a
- * SparsityPattern. The separation of sparsity pattern and values is
- * done since one can store data elements of different type in these
- * locations without the SparsityPattern having to know this, and more
- * importantly one can associate more than one matrix with the same
- * sparsity pattern.
+ * Sparse matrix. This class implements the function to store values in the
+ * locations of a sparse matrix denoted by a SparsityPattern. The separation
+ * of sparsity pattern and values is done since one can store data elements of
+ * different type in these locations without the SparsityPattern having to
+ * know this, and more importantly one can associate more than one matrix with
+ * the same sparsity pattern.
  *
  * The elements of a SparseMatrix are stored in the same order in which the
- * SparsityPattern class stores its entries.
- * Within each row, elements are generally stored left-to-right in increasing
- * column index order; the exception to this rule is that if the matrix
- * is square (n_rows() == n_columns()), then the diagonal entry is stored
- * as the first element in each row to make operations like applying a
- * Jacobi or SSOR preconditioner faster. As a consequence, if you traverse
- * the elements of a row of a SparseMatrix with the help of iterators into
- * this object (using SparseMatrix::begin and SparseMatrix::end) you
- * will find that the elements are not sorted by column index within each row
- * whenever the matrix is square.
+ * SparsityPattern class stores its entries. Within each row, elements are
+ * generally stored left-to-right in increasing column index order; the
+ * exception to this rule is that if the matrix is square (n_rows() ==
+ * n_columns()), then the diagonal entry is stored as the first element in
+ * each row to make operations like applying a Jacobi or SSOR preconditioner
+ * faster. As a consequence, if you traverse the elements of a row of a
+ * SparseMatrix with the help of iterators into this object (using
+ * SparseMatrix::begin and SparseMatrix::end) you will find that the elements
+ * are not sorted by column index within each row whenever the matrix is
+ * square.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -505,9 +503,9 @@ public:
   /**
    * Declare a type that has holds real-valued numbers with the same precision
    * as the template argument to this class. If the template argument of this
-   * class is a real data type, then real_type equals the template
-   * argument. If the template argument is a std::complex type then real_type
-   * equals the type underlying the complex numbers.
+   * class is a real data type, then real_type equals the template argument.
+   * If the template argument is a std::complex type then real_type equals the
+   * type underlying the complex numbers.
    *
    * This typedef is used to represent the return type of norms.
    */
@@ -897,9 +895,9 @@ public:
   void symmetrize ();
 
   /**
-   * Copy the given matrix to this one.  The operation triggers an assertion if the
-   * sparsity patterns of the two involved matrices do not point to the same
-   * object, since in this case the copy operation is cheaper. Since this
+   * Copy the given matrix to this one.  The operation triggers an assertion
+   * if the sparsity patterns of the two involved matrices do not point to the
+   * same object, since in this case the copy operation is cheaper. Since this
    * operation is notheless not for free, we do not make it available through
    * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
    * arguments to functions, which should really be arguments by reference.
@@ -978,9 +976,9 @@ public:
 
   /**
    * Return the value of the entry (<i>i,j</i>).  This may be an expensive
-   * operation and you should always take care where to call this function.
-   * In order to avoid abuse, this function throws an exception if the
-   * required element does not exist in the matrix.
+   * operation and you should always take care where to call this function. In
+   * order to avoid abuse, this function throws an exception if the required
+   * element does not exist in the matrix.
    *
    * In case you want a function that returns zero instead (for entries that
    * are not in the sparsity pattern of the matrix), use the el() function.
@@ -1037,8 +1035,8 @@ public:
                     const size_type index) const DEAL_II_DEPRECATED;
 
   /**
-   * This is for hackers. Get access to the <i>i</i>th element of this
-   * matrix. The elements are stored in a consecutive way, refer to the
+   * This is for hackers. Get access to the <i>i</i>th element of this matrix.
+   * The elements are stored in a consecutive way, refer to the
    * SparsityPattern class for more details.
    *
    * You should use this interface very carefully and only if you are
@@ -1249,8 +1247,8 @@ public:
    * Return the $l_1$-norm of the matrix, that is $|M|_1=\max_{\mathrm{all\
    * columns\ }j}\sum_{\mathrm{all\ rows\ } i} |M_{ij}|$, (max. sum of
    * columns).  This is the natural matrix norm that is compatible to the
-   * $l_1$-norm for vectors, i.e.  $|Mv|_1\leq |M|_1 |v|_1$.
-   * (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
+   * $l_1$-norm for vectors, i.e.  $|Mv|_1\leq |M|_1 |v|_1$. (cf. Haemmerlin-
+   * Hoffmann: Numerische Mathematik)
    */
   real_type l1_norm () const;
 
@@ -1259,8 +1257,7 @@ public:
    * $|M|_\infty=\max_{\mathrm{all\ rows\ }i}\sum_{\mathrm{all\ columns\ }j}
    * |M_{ij}|$, (max. sum of rows).  This is the natural matrix norm that is
    * compatible to the $l_\infty$-norm of vectors, i.e.  $|Mv|_\infty \leq
-   * |M|_\infty |v|_\infty$.  (cf. Haemmerlin-Hoffmann: Numerische
-   * Mathematik)
+   * |M|_\infty |v|_\infty$.  (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
    */
   real_type linfty_norm () const;
 
@@ -1286,10 +1283,10 @@ public:
                             const number              omega = 1.) const;
 
   /**
-   * Apply SSOR preconditioning to <tt>src</tt> with damping
-   * <tt>omega</tt>. The optional argument <tt>pos_right_of_diagonal</tt> is
-   * supposed to provide an array where each entry specifies the position just
-   * right of the diagonal in the global array of nonzeros.
+   * Apply SSOR preconditioning to <tt>src</tt> with damping <tt>omega</tt>.
+   * The optional argument <tt>pos_right_of_diagonal</tt> is supposed to
+   * provide an array where each entry specifies the position just right of
+   * the diagonal in the global array of nonzeros.
    */
   template <typename somenumber>
   void precondition_SSOR (Vector<somenumber>             &dst,
@@ -1416,8 +1413,8 @@ public:
    * STL-like iterator with the first entry of the matrix. This is the version
    * for constant matrices.
    *
-   * Note the discussion in the general documentation of this class about
-   * the order in which elements are accessed.
+   * Note the discussion in the general documentation of this class about the
+   * order in which elements are accessed.
    */
   const_iterator begin () const;
 
@@ -1430,8 +1427,8 @@ public:
    * STL-like iterator with the first entry of the matrix. This is the version
    * for non-constant matrices.
    *
-   * Note the discussion in the general documentation of this class about
-   * the order in which elements are accessed.
+   * Note the discussion in the general documentation of this class about the
+   * order in which elements are accessed.
    */
   iterator begin ();
 
@@ -1474,8 +1471,8 @@ public:
    * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    *
-   * Note the discussion in the general documentation of this class about
-   * the order in which elements are accessed.
+   * Note the discussion in the general documentation of this class about the
+   * order in which elements are accessed.
    */
   iterator begin (const size_type r);
 
@@ -1496,15 +1493,15 @@ public:
 //@{
 
   /**
-   * Print the matrix to the given stream, using the format
-   * <tt>(row,column) value</tt>, i.e. one nonzero entry of the matrix
-   * per line. If <tt>across</tt> is true, print all entries on a
-   * single line, using the format row,column:value.
+   * Print the matrix to the given stream, using the format <tt>(row,column)
+   * value</tt>, i.e. one nonzero entry of the matrix per line. If
+   * <tt>across</tt> is true, print all entries on a single line, using the
+   * format row,column:value.
    *
-   * If the argument <tt>diagonal_first</tt> is true, diagonal
-   * elements of quadratic matrices are printed first in their row,
-   * corresponding to the internal storage scheme. If it is false, the
-   * elements in a row are written in ascending column order.
+   * If the argument <tt>diagonal_first</tt> is true, diagonal elements of
+   * quadratic matrices are printed first in their row, corresponding to the
+   * internal storage scheme. If it is false, the elements in a row are
+   * written in ascending column order.
    */
   template <class STREAM>
   void print (STREAM &out,
@@ -1559,10 +1556,10 @@ public:
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously been written by block_write() from a
-   * file. This is done using the inverse operations to the above function, so
-   * it is reasonably fast because the bitstream is not interpreted except for
-   * a few numbers up front.
+   * Read data that has previously been written by block_write() from a file.
+   * This is done using the inverse operations to the above function, so it is
+   * reasonably fast because the bitstream is not interpreted except for a few
+   * numbers up front.
    *
    * The object is resized on this operation, and all previous contents are
    * lost. Note, however, that no checks are performed whether new data and
@@ -1576,8 +1573,10 @@ public:
    */
   void block_read (std::istream &in);
   //@}
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -1663,8 +1662,7 @@ private:
   template <typename> friend class BlockMatrixBase;
 
   /**
-   * Also give access to internal details to the iterator/accessor
-   * classes.
+   * Also give access to internal details to the iterator/accessor classes.
    */
   template <typename,bool> friend class SparseMatrixIterators::Iterator;
   template <typename,bool> friend class SparseMatrixIterators::Accessor;
index c31a3257751509a79f92ac836287ee74117a3f23..aa88acffbe09e2d3665e2b42a7664472c8984e94 100644 (file)
@@ -810,15 +810,12 @@ namespace internal
   namespace SparseMatrix
   {
     /**
-     * Perform a vmult using the SparseMatrix
-     * data structures, but only using a
-     * subinterval for the row indices.
+     * Perform a vmult using the SparseMatrix data structures, but only using
+     * a subinterval for the row indices.
      *
-     * In the sequential case, this function
-     * is called on all rows, in the parallel
-     * case it may be called on a subrange,
-     * at the discretion of the task
-     * scheduler.
+     * In the sequential case, this function is called on all rows, in the
+     * parallel case it may be called on a subrange, at the discretion of the
+     * task scheduler.
      */
     template <typename number,
               typename InVector>
@@ -873,15 +870,12 @@ namespace internal
   namespace SparseMatrix
   {
     /**
-     * Perform a vmult using the SparseMatrix
-     * data structures, but only using a
-     * subinterval for the row indices.
+     * Perform a vmult using the SparseMatrix data structures, but only using
+     * a subinterval for the row indices.
      *
-     * In the sequential case, this function
-     * is called on all rows, in the parallel
-     * case it may be called on a subrange,
-     * at the discretion of the task
-     * scheduler.
+     * In the sequential case, this function is called on all rows, in the
+     * parallel case it may be called on a subrange, at the discretion of the
+     * task scheduler.
      */
     template <typename number,
               typename InVector>
@@ -1256,15 +1250,12 @@ namespace internal
   namespace SparseMatrix
   {
     /**
-     * Perform a vmult using the SparseMatrix
-     * data structures, but only using a
-     * subinterval for the row indices.
+     * Perform a vmult using the SparseMatrix data structures, but only using
+     * a subinterval for the row indices.
      *
-     * In the sequential case, this function
-     * is called on all rows, in the parallel
-     * case it may be called on a subrange,
-     * at the discretion of the task
-     * scheduler.
+     * In the sequential case, this function is called on all rows, in the
+     * parallel case it may be called on a subrange, at the discretion of the
+     * task scheduler.
      */
     template <typename number,
               typename InVector,
index 96eb4bf1d5fb70a8613a4f11a2c9775d6bb6f2b5..b2c04f2f707fb946358588f44c2789045bbf6568 100644 (file)
@@ -37,62 +37,59 @@ template<typename number> class FullMatrix;
 /**
  * Sparse matrix without sparsity pattern.
  *
- * Instead of using a pre-assembled sparsity pattern, this matrix
- * builds the pattern on the fly. Filling the matrix may consume more
- * time as with @p SparseMatrix, since large memory movements may be
- * involved. To help optimizing things, an expected row-length may be
- * provided to the constructor, as well as an increment size
- * for rows.
+ * Instead of using a pre-assembled sparsity pattern, this matrix builds the
+ * pattern on the fly. Filling the matrix may consume more time as with @p
+ * SparseMatrix, since large memory movements may be involved. To help
+ * optimizing things, an expected row-length may be provided to the
+ * constructor, as well as an increment size for rows.
  *
- * The storage structure: like with the usual sparse matrix, it is
- * attempted to store only non-zero elements. these are stored in a
- * single data array @p data. They are ordered by row and inside each
- * row by column number. Each row is described by its starting point
- * in the data array and its length. These are stored in the
- * @p row_info array, together with additional useful information.
+ * The storage structure: like with the usual sparse matrix, it is attempted
+ * to store only non-zero elements. these are stored in a single data array @p
+ * data. They are ordered by row and inside each row by column number. Each
+ * row is described by its starting point in the data array and its length.
+ * These are stored in the @p row_info array, together with additional useful
+ * information.
  *
- * Due to the structure, gaps may occur between rows. Whenever a new
- * entry must be created, an attempt is made to use the gap in its
- * row. If the gap is full, the row must be extended and all
- * subsequent rows must be shifted backwards. This is a very expensive
- * operation and should be avoided as much as possible.
+ * Due to the structure, gaps may occur between rows. Whenever a new entry
+ * must be created, an attempt is made to use the gap in its row. If the gap
+ * is full, the row must be extended and all subsequent rows must be shifted
+ * backwards. This is a very expensive operation and should be avoided as much
+ * as possible.
  *
- * This is, where the optimization parameters, provided to the
- * constructor or to the function @p reinit come
- * in. @p default_row_length is the amount of entries that will be
- * allocated for each row on initialization (the actual length of the
- * rows is still zero). This means, that @p default_row_length
- * entries can be added to this row without shifting other rows. If
- * less entries are added, the additional memory will be wasted.
+ * This is, where the optimization parameters, provided to the constructor or
+ * to the function @p reinit come in. @p default_row_length is the amount of
+ * entries that will be allocated for each row on initialization (the actual
+ * length of the rows is still zero). This means, that @p default_row_length
+ * entries can be added to this row without shifting other rows. If less
+ * entries are added, the additional memory will be wasted.
  *
- * If the space for a row is not sufficient, then it is enlarged by
- * @p default_increment entries. This way, the subsequent rows are
- * not shifted by single entries very often.
+ * If the space for a row is not sufficient, then it is enlarged by @p
+ * default_increment entries. This way, the subsequent rows are not shifted by
+ * single entries very often.
  *
- * Finally, the @p default_reserve allocates extra space at the end
- * of the data array. This space is used whenever a row must be
- * enlarged. Since @p std::vector doubles the capacity every time it
- * must increase it, this value should allow for all the growth needed.
+ * Finally, the @p default_reserve allocates extra space at the end of the
+ * data array. This space is used whenever a row must be enlarged. Since @p
+ * std::vector doubles the capacity every time it must increase it, this value
+ * should allow for all the growth needed.
  *
- * Suggested settings: @p default_row_length should be the length of
- * a typical row, for instance the size of the stencil in regular
- * parts of the grid. Then, @p default_increment may be the expected
- * amount of entries added to the row by having one hanging node. This
- * way, a good compromise between memory consumption and speed should
- * be achieved. @p default_reserve should then be an estimate for the
- * number of hanging nodes times @p default_increment.
+ * Suggested settings: @p default_row_length should be the length of a typical
+ * row, for instance the size of the stencil in regular parts of the grid.
+ * Then, @p default_increment may be the expected amount of entries added to
+ * the row by having one hanging node. This way, a good compromise between
+ * memory consumption and speed should be achieved. @p default_reserve should
+ * then be an estimate for the number of hanging nodes times @p
+ * default_increment.
  *
- * Letting @p default_increment zero causes an exception whenever a
- * row overflows.
+ * Letting @p default_increment zero causes an exception whenever a row
+ * overflows.
  *
- * If the rows are expected to be filled more or less from first to
- * last, using a @p default_row_length of zero may not be such a bad
- * idea.
+ * If the rows are expected to be filled more or less from first to last,
+ * using a @p default_row_length of zero may not be such a bad idea.
  *
- * The name of this matrix is in reverence to a publication of the
- * Internal Revenue Service of the United States of America. I hope
- * some other aliens will appreciate it. By the way, the suffix makes
- * sense by pronouncing it the American way.
+ * The name of this matrix is in reverence to a publication of the Internal
+ * Revenue Service of the United States of America. I hope some other aliens
+ * will appreciate it. By the way, the suffix makes sense by pronouncing it
+ * the American way.
  *
  * @author Guido Kanschat
  * @date 2002, 2010
@@ -107,22 +104,18 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * The class for storing the
-   * column number of an entry
-   * together with its value.
+   * The class for storing the column number of an entry together with its
+   * value.
    */
   struct Entry
   {
     /**
-     * Standard constructor. Sets
-     * @p column to
-     * @p invalid.
+     * Standard constructor. Sets @p column to @p invalid.
      */
     Entry();
 
     /**
-     * Constructor. Fills column
-     * and value.
+     * Constructor. Fills column and value.
      */
     Entry (const size_type column,
            const number &value);
@@ -144,10 +137,8 @@ public:
   };
 
   /**
-   * Structure for storing
-   * information on a matrix
-   * row. One object for each row
-   * will be stored in the matrix.
+   * Structure for storing information on a matrix row. One object for each
+   * row will be stored in the matrix.
    */
   struct RowInfo
   {
@@ -157,19 +148,15 @@ public:
     RowInfo (size_type start = Entry::invalid);
 
     /**
-     * Index of first entry of
-     * the row in the data field.
+     * Index of first entry of the row in the data field.
      */
     size_type start;
     /**
-     * Number of entries in this
-     * row.
+     * Number of entries in this row.
      */
     unsigned short length;
     /**
-     * Position of the diagonal
-     * element relative tor the
-     * start index.
+     * Position of the diagonal element relative tor the start index.
      */
     unsigned short diagonal;
     /**
@@ -194,33 +181,25 @@ public:
     {
     public:
       /**
-       * Constructor. Since we use
-       * accessors only for read
-       * access, a const matrix
-       * pointer is sufficient.
+       * Constructor. Since we use accessors only for read access, a const
+       * matrix pointer is sufficient.
        */
       Accessor (const SparseMatrixEZ<number> *matrix,
                 const size_type               row,
                 const unsigned short          index);
 
       /**
-       * Row number of the element
-       * represented by this
-       * object.
+       * Row number of the element represented by this object.
        */
       size_type row() const;
 
       /**
-       * Index in row of the element
-       * represented by this
-       * object.
+       * Index in row of the element represented by this object.
        */
       unsigned short index() const;
 
       /**
-       * Column number of the
-       * element represented by
-       * this object.
+       * Column number of the element represented by this object.
        */
       size_type column() const;
 
@@ -246,8 +225,7 @@ public:
       unsigned short a_index;
 
       /**
-       * Make enclosing class a
-       * friend.
+       * Make enclosing class a friend.
        */
       friend class const_iterator;
     };
@@ -261,16 +239,12 @@ public:
                    const unsigned short          index);
 
     /**
-     * Prefix increment. This
-     * always returns a valid
-     * entry or <tt>end()</tt>.
+     * Prefix increment. This always returns a valid entry or <tt>end()</tt>.
      */
     const_iterator &operator++ ();
 
     /**
-     * Postfix increment. This
-     * always returns a valid
-     * entry or <tt>end()</tt>.
+     * Postfix increment. This always returns a valid entry or <tt>end()</tt>.
      */
     const_iterator &operator++ (int);
 
@@ -285,10 +259,7 @@ public:
     const Accessor *operator-> () const;
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const const_iterator &) const;
     /**
@@ -297,43 +268,28 @@ public:
     bool operator != (const const_iterator &) const;
 
     /**
-     * Comparison
-     * operator. Result is true
-     * if either the first row
-     * number is smaller or if
-     * the row numbers are
-     * equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      */
     bool operator < (const const_iterator &) const;
 
   private:
     /**
-     * Store an object of the
-     * accessor class.
+     * Store an object of the accessor class.
      */
     Accessor accessor;
 
     /**
-     * Make the enclosing class a
-     * friend. This is only
-     * necessary since icc7
-     * otherwise wouldn't allow
-     * us to make
-     * const_iterator::Accessor a
-     * friend, stating that it
-     * can't access this class --
-     * this is of course bogus,
-     * since granting friendship
-     * doesn't need access to the
-     * class being granted
-     * friendship...
+     * Make the enclosing class a friend. This is only necessary since icc7
+     * otherwise wouldn't allow us to make const_iterator::Accessor a friend,
+     * stating that it can't access this class -- this is of course bogus,
+     * since granting friendship doesn't need access to the class being
+     * granted friendship...
      */
   };
 
   /**
-   * Type of matrix entries. In analogy to
-   * the STL container classes.
+   * Type of matrix entries. In analogy to the STL container classes.
    */
   typedef number value_type;
 
@@ -342,36 +298,24 @@ public:
    */
 //@{
   /**
-   * Constructor. Initializes an
-   * empty matrix of dimension zero
-   * times zero.
+   * Constructor. Initializes an empty matrix of dimension zero times zero.
    */
   SparseMatrixEZ ();
 
   /**
-   * Dummy copy constructor. This
-   * is here for use in
-   * containers. It may only be
-   * called for empty objects.
+   * Dummy copy constructor. This is here for use in containers. It may only
+   * be called for empty objects.
    *
-   * If you really want to copy a whole
-   * matrix, you can do so by using the
-   * @p copy_from function.
+   * If you really want to copy a whole matrix, you can do so by using the @p
+   * copy_from function.
    */
   SparseMatrixEZ (const SparseMatrixEZ &);
 
   /**
-   * Constructor. Generates a
-   * matrix of the given size,
-   * ready to be filled. The
-   * optional parameters
-   * @p default_row_length and
-   * @p default_increment allow
-   * for preallocating
-   * memory. Providing these
-   * properly is essential for an
-   * efficient assembling of the
-   * matrix.
+   * Constructor. Generates a matrix of the given size, ready to be filled.
+   * The optional parameters @p default_row_length and @p default_increment
+   * allow for preallocating memory. Providing these properly is essential for
+   * an efficient assembling of the matrix.
    */
   explicit SparseMatrixEZ (const size_type n_rows,
                            const size_type n_columns,
@@ -379,50 +323,32 @@ public:
                            const unsigned int default_increment = 1);
 
   /**
-   * Destructor. Free all memory, but do not
-   * release the memory of the sparsity
-   * structure.
+   * Destructor. Free all memory, but do not release the memory of the
+   * sparsity structure.
    */
   ~SparseMatrixEZ ();
 
   /**
-   * Pseudo operator only copying
-   * empty objects.
+   * Pseudo operator only copying empty objects.
    */
   SparseMatrixEZ<number> &operator = (const SparseMatrixEZ<number> &);
 
   /**
-   * This operator assigns a scalar to
-   * a matrix. Since this does usually
-   * not make much sense (should we set
-   * all matrix entries to this value?
-   * Only the nonzero entries of the
-   * sparsity pattern?), this operation
-   * is only allowed if the actual
-   * value to be assigned is zero. This
-   * operator only exists to allow for
-   * the obvious notation
-   * <tt>matrix=0</tt>, which sets all
-   * elements of the matrix to zero,
-   * but keep the sparsity pattern
-   * previously used.
+   * This operator assigns a scalar to a matrix. Since this does usually not
+   * make much sense (should we set all matrix entries to this value? Only the
+   * nonzero entries of the sparsity pattern?), this operation is only allowed
+   * if the actual value to be assigned is zero. This operator only exists to
+   * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+   * of the matrix to zero, but keep the sparsity pattern previously used.
    */
   SparseMatrixEZ<number> &operator = (const double d);
 
   /**
-   * Reinitialize the sparse matrix
-   * to the dimensions provided.
-   * The matrix will have no
-   * entries at this point. The
-   * optional parameters
-   * @p default_row_length,
-   * @p default_increment and
-   * @p reserve allow
-   * for preallocating
-   * memory. Providing these
-   * properly is essential for an
-   * efficient assembling of the
-   * matrix.
+   * Reinitialize the sparse matrix to the dimensions provided. The matrix
+   * will have no entries at this point. The optional parameters @p
+   * default_row_length, @p default_increment and @p reserve allow for
+   * preallocating memory. Providing these properly is essential for an
+   * efficient assembling of the matrix.
    */
   void reinit (const size_type n_rows,
                const size_type n_columns,
@@ -431,11 +357,8 @@ public:
                size_type reserve = 0);
 
   /**
-   * Release all memory and return
-   * to a state just like after
-   * having called the default
-   * constructor. It also forgets
-   * its sparsity pattern.
+   * Release all memory and return to a state just like after having called
+   * the default constructor. It also forgets its sparsity pattern.
    */
   void clear ();
 //@}
@@ -444,55 +367,43 @@ public:
    */
 //@{
   /**
-   * Return whether the object is
-   * empty. It is empty if
-   * both dimensions are zero.
+   * Return whether the object is empty. It is empty if both dimensions are
+   * zero.
    */
   bool empty () const;
 
   /**
-   * Return the dimension of the
-   * image space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the image space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type m () const;
 
   /**
-   * Return the dimension of the
-   * range space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the range space.  To remember: the matrix is of
+   * dimension $m \times n$.
    */
   size_type n () const;
 
   /**
-   * Return the number of entries
-   * in a specific row.
+   * Return the number of entries in a specific row.
    */
   size_type get_row_length (const size_type row) const;
 
   /**
-   * Return the number of nonzero
-   * elements of this matrix.
+   * Return the number of nonzero elements of this matrix.
    */
   size_type n_nonzero_elements () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-   * Print statistics. If @p full
-   * is @p true, prints a
-   * histogram of all existing row
-   * lengths and allocated row
-   * lengths. Otherwise, just the
-   * relation of allocated and used
-   * entries is shown.
+   * Print statistics. If @p full is @p true, prints a histogram of all
+   * existing row lengths and allocated row lengths. Otherwise, just the
+   * relation of allocated and used entries is shown.
    */
   template <class STREAM>
   void print_statistics (STREAM &s, bool full = false);
@@ -500,15 +411,11 @@ public:
   /**
    * Compute numbers of entries.
    *
-   * In the first three arguments,
-   * this function returns the
-   * number of entries used,
-   * allocated and reserved by this
-   * matrix.
+   * In the first three arguments, this function returns the number of entries
+   * used, allocated and reserved by this matrix.
    *
-   * If the final argument is true,
-   * the number of entries in each
-   * line is printed as well.
+   * If the final argument is true, the number of entries in each line is
+   * printed as well.
    */
   void compute_statistics (size_type &used,
                            size_type &allocated,
@@ -521,56 +428,35 @@ public:
    */
 //@{
   /**
-                   * Set the element <tt>(i,j)</tt> to
-                   * @p value. Allocates the entry,
-                   * if it does not exist and
-                   * @p value is non-zero.
-                   * If <tt>value</tt> is not a
-                   * finite number an exception
-                   * is thrown.
-                   */
+   * Set the element <tt>(i,j)</tt> to @p value. Allocates the entry, if it
+   * does not exist and @p value is non-zero. If <tt>value</tt> is not a
+   * finite number an exception is thrown.
+   */
   void set (const size_type i, const size_type j,
             const number value);
 
   /**
-   * Add @p value to the element
-   * <tt>(i,j)</tt>. Allocates the entry
-   * if it does not exist. Filters
-   * out zeroes automatically.
-   * If <tt>value</tt> is not a
-   * finite number an exception
-   * is thrown.
+   * Add @p value to the element <tt>(i,j)</tt>. Allocates the entry if it
+   * does not exist. Filters out zeroes automatically. If <tt>value</tt> is
+   * not a finite number an exception is thrown.
    */
   void add (const size_type i,
             const size_type j,
             const number value);
 
   /**
-   * Add all elements given in a
-   * FullMatrix<double> into sparse
-   * matrix locations given by
-   * <tt>indices</tt>. In other words,
-   * this function adds the elements in
-   * <tt>full_matrix</tt> to the
-   * respective entries in calling
-   * matrix, using the local-to-global
-   * indexing specified by
-   * <tt>indices</tt> for both the rows
-   * and the columns of the
-   * matrix. This function assumes a
-   * quadratic sparse matrix and a
-   * quadratic full_matrix, the usual
-   * situation in FE calculations.
+   * Add all elements given in a FullMatrix<double> into sparse matrix
+   * locations given by <tt>indices</tt>. In other words, this function adds
+   * the elements in <tt>full_matrix</tt> to the respective entries in calling
+   * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+   * for both the rows and the columns of the matrix. This function assumes a
+   * quadratic sparse matrix and a quadratic full_matrix, the usual situation
+   * in FE calculations.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const std::vector<size_type> &indices,
@@ -578,11 +464,9 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Same function as before, but now
-   * including the possibility to use
-   * rectangular full_matrices and
-   * different local-to-global indexing
-   * on rows and columns, respectively.
+   * Same function as before, but now including the possibility to use
+   * rectangular full_matrices and different local-to-global indexing on rows
+   * and columns, respectively.
    */
   template <typename number2>
   void add (const std::vector<size_type> &row_indices,
@@ -591,21 +475,13 @@ public:
             const bool                       elide_zero_values = true);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix with
-   * column indices as given by
-   * <tt>col_indices</tt> to the
-   * respective value.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const size_type               row,
@@ -614,21 +490,13 @@ public:
             const bool                    elide_zero_values = true);
 
   /**
-   * Add an array of values given by
-   * <tt>values</tt> in the given
-   * global matrix row at columns
-   * specified by col_indices in the
-   * sparse matrix.
+   * Add an array of values given by <tt>values</tt> in the given global
+   * matrix row at columns specified by col_indices in the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const size_type  row,
@@ -639,44 +507,27 @@ public:
             const bool       col_indices_are_sorted = false);
 
   /**
-   * Copy the given matrix to this
-   * one.  The operation throws an
-   * error if the sparsity patterns
-   * of the two involved matrices
-   * do not point to the same
-   * object, since in this case the
-   * copy operation is
-   * cheaper. Since this operation
-   * is notheless not for free, we
-   * do not make it available
-   * through <tt>operator =</tt>, since
-   * this may lead to unwanted
-   * usage, e.g. in copy arguments
-   * to functions, which should
-   * really be arguments by
-   * reference.
+   * Copy the given matrix to this one.  The operation throws an error if the
+   * sparsity patterns of the two involved matrices do not point to the same
+   * object, since in this case the copy operation is cheaper. Since this
+   * operation is notheless not for free, we do not make it available through
+   * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
+   * arguments to functions, which should really be arguments by reference.
    *
-   * The source matrix may be a matrix
-   * of arbitrary type, as long as its
-   * data type is convertible to the
-   * data type of this matrix.
+   * The source matrix may be a matrix of arbitrary type, as long as its data
+   * type is convertible to the data type of this matrix.
    *
-   * The function returns a reference to
-   * @p this.
+   * The function returns a reference to @p this.
    */
   template <class MATRIX>
   SparseMatrixEZ<number> &
   copy_from (const MATRIX &source);
 
   /**
-   * Add @p matrix scaled by
-   * @p factor to this matrix.
+   * Add @p matrix scaled by @p factor to this matrix.
    *
-   * The source matrix may be a
-   * matrix of arbitrary type, as
-   * long as its data type is
-   * convertible to the data type
-   * of this matrix and it has the
+   * The source matrix may be a matrix of arbitrary type, as long as its data
+   * type is convertible to the data type of this matrix and it has the
    * standard @p const_iterator.
    */
   template <class MATRIX>
@@ -688,30 +539,20 @@ public:
    */
 //@{
   /**
-   * Return the value of the entry
-   * (i,j).  This may be an
-   * expensive operation and you
-   * should always take care where
-   * to call this function.  In
-   * order to avoid abuse, this
-   * function throws an exception
-   * if the required element does
-   * not exist in the matrix.
+   * Return the value of the entry (i,j).  This may be an expensive operation
+   * and you should always take care where to call this function.  In order to
+   * avoid abuse, this function throws an exception if the required element
+   * does not exist in the matrix.
    *
-   * In case you want a function
-   * that returns zero instead (for
-   * entries that are not in the
-   * sparsity pattern of the
-   * matrix), use the @p el
-   * function.
+   * In case you want a function that returns zero instead (for entries that
+   * are not in the sparsity pattern of the matrix), use the @p el function.
    */
   number operator () (const size_type i,
                       const size_type j) const;
 
   /**
-   * Return the value of the entry
-   * (i,j). Returns zero for all
-   * non-existing entries.
+   * Return the value of the entry (i,j). Returns zero for all non-existing
+   * entries.
    */
   number el (const size_type i,
              const size_type j) const;
@@ -721,42 +562,33 @@ public:
    */
 //@{
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M*src$ with $M$
-   * being this matrix.
+   * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+   * matrix.
    */
   template <typename somenumber>
   void vmult (Vector<somenumber>       &dst,
               const Vector<somenumber> &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * let $dst = M^T*src$ with $M$
-   * being this matrix. This
-   * function does the same as
-   * @p vmult but takes the
-   * transposed matrix.
+   * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+   * matrix. This function does the same as @p vmult but takes the transposed
+   * matrix.
    */
   template <typename somenumber>
   void Tvmult (Vector<somenumber>       &dst,
                const Vector<somenumber> &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add $M*src$ on
-   * $dst$ with $M$ being this
-   * matrix.
+   * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+   * this matrix.
    */
   template <typename somenumber>
   void vmult_add (Vector<somenumber>       &dst,
                   const Vector<somenumber> &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add $M^T*src$
-   * to $dst$ with $M$ being this
-   * matrix. This function does the
-   * same as @p vmult_add but takes
+   * Adding Matrix-vector multiplication. Add $M^T*src$ to $dst$ with $M$
+   * being this matrix. This function does the same as @p vmult_add but takes
    * the transposed matrix.
    */
   template <typename somenumber>
@@ -777,14 +609,9 @@ public:
    */
 //@{
   /**
-   * Apply the Jacobi
-   * preconditioner, which
-   * multiplies every element of
-   * the @p src vector by the
-   * inverse of the respective
-   * diagonal element and
-   * multiplies the result with the
-   * damping factor @p omega.
+   * Apply the Jacobi preconditioner, which multiplies every element of the @p
+   * src vector by the inverse of the respective diagonal element and
+   * multiplies the result with the damping factor @p omega.
    */
   template <typename somenumber>
   void precondition_Jacobi (Vector<somenumber>       &dst,
@@ -792,8 +619,7 @@ public:
                             const number              omega = 1.) const;
 
   /**
-   * Apply SSOR preconditioning to
-   * @p src.
+   * Apply SSOR preconditioning to @p src.
    */
   template <typename somenumber>
   void precondition_SSOR (Vector<somenumber>       &dst,
@@ -802,8 +628,7 @@ public:
                           const std::vector<std::size_t> &pos_right_of_diagonal = std::vector<std::size_t>()) const;
 
   /**
-   * Apply SOR preconditioning matrix to @p src.
-   * The result of this method is
+   * Apply SOR preconditioning matrix to @p src. The result of this method is
    * $dst = (om D - L)^{-1} src$.
    */
   template <typename somenumber>
@@ -812,9 +637,8 @@ public:
                          const number              om = 1.) const;
 
   /**
-   * Apply transpose SOR preconditioning matrix to @p src.
-   * The result of this method is
-   * $dst = (om D - U)^{-1} src$.
+   * Apply transpose SOR preconditioning matrix to @p src. The result of this
+   * method is $dst = (om D - U)^{-1} src$.
    */
   template <typename somenumber>
   void precondition_TSOR (Vector<somenumber>       &dst,
@@ -822,18 +646,12 @@ public:
                           const number              om = 1.) const;
 
   /**
-   * Add the matrix @p A
-   * conjugated by @p B, that is,
-   * $B A B^T$ to this object. If
-   * the parameter @p transpose is
-   * true, compute $B^T A B$.
+   * Add the matrix @p A conjugated by @p B, that is, $B A B^T$ to this
+   * object. If the parameter @p transpose is true, compute $B^T A B$.
    *
-   * This function requires that
-   * @p B has a @p const_iterator
-   * traversing all matrix entries
-   * and that @p A has a function
-   * <tt>el(i,j)</tt> for access to a
-   * specific entry.
+   * This function requires that @p B has a @p const_iterator traversing all
+   * matrix entries and that @p A has a function <tt>el(i,j)</tt> for access
+   * to a specific entry.
    */
   template <class MATRIXA, class MATRIXB>
   void conjugate_add (const MATRIXA &A,
@@ -845,8 +663,7 @@ public:
    */
 //@{
   /**
-   * STL-like iterator with the
-   * first existing entry.
+   * STL-like iterator with the first existing entry.
    */
   const_iterator begin () const;
 
@@ -856,18 +673,14 @@ public:
   const_iterator end () const;
 
   /**
-   * STL-like iterator with the
-   * first entry of row @p r. If
-   * this row is empty, the result
-   * is <tt>end(r)</tt>, which does NOT
-   * point into row @p r..
+   * STL-like iterator with the first entry of row @p r. If this row is empty,
+   * the result is <tt>end(r)</tt>, which does NOT point into row @p r..
    */
   const_iterator begin (const size_type r) const;
 
   /**
-   * Final iterator of row
-   * @p r. The result may be
-   * different from <tt>end()</tt>!
+   * Final iterator of row @p r. The result may be different from
+   * <tt>end()</tt>!
    */
   const_iterator end (const size_type r) const;
 //@}
@@ -876,52 +689,30 @@ public:
    */
 //@{
   /**
-   * Print the matrix to the given
-   * stream, using the format
-   * <tt>(line,col) value</tt>, i.e. one
-   * nonzero entry of the matrix
-   * per line.
+   * Print the matrix to the given stream, using the format <tt>(line,col)
+   * value</tt>, i.e. one nonzero entry of the matrix per line.
    */
   void print (std::ostream &out) const;
 
   /**
-   * Print the matrix in the usual
-   * format, i.e. as a matrix and
-   * not as a list of nonzero
-   * elements. For better
-   * readability, elements not in
-   * the matrix are displayed as
-   * empty space, while matrix
-   * elements which are explicitly
-   * set to zero are displayed as
-   * such.
+   * Print the matrix in the usual format, i.e. as a matrix and not as a list
+   * of nonzero elements. For better readability, elements not in the matrix
+   * are displayed as empty space, while matrix elements which are explicitly
+   * set to zero are displayed as such.
    *
-   * The parameters allow for a
-   * flexible setting of the output
-   * format: @p precision and
-   * @p scientific are used to
-   * determine the number format,
-   * where @p scientific = @p false
-   * means fixed point notation.  A
-   * zero entry for @p width makes
-   * the function compute a width,
-   * but it may be changed to a
-   * positive value, if output is
-   * crude.
+   * The parameters allow for a flexible setting of the output format: @p
+   * precision and @p scientific are used to determine the number format,
+   * where @p scientific = @p false means fixed point notation.  A zero entry
+   * for @p width makes the function compute a width, but it may be changed to
+   * a positive value, if output is crude.
    *
-   * Additionally, a character for
-   * an empty value may be
-   * specified.
+   * Additionally, a character for an empty value may be specified.
    *
-   * Finally, the whole matrix can
-   * be multiplied with a common
-   * denominator to produce more
-   * readable output, even
-   * integers.
+   * Finally, the whole matrix can be multiplied with a common denominator to
+   * produce more readable output, even integers.
    *
-   * This function
-   * may produce @em large amounts of
-   * output if applied to a large matrix!
+   * This function may produce @em large amounts of output if applied to a
+   * large matrix!
    */
   void print_formatted (std::ostream       &out,
                         const unsigned int  precision   = 3,
@@ -931,36 +722,29 @@ public:
                         const double        denominator = 1.) const;
 
   /**
-   * Write the data of this object
-   * in binary mode to a file.
+   * Write the data of this object in binary mode to a file.
    *
-   * Note that this binary format
-   * is platform dependent.
+   * Note that this binary format is platform dependent.
    */
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously
-   * been written by
-   * @p block_write.
+   * Read data that has previously been written by @p block_write.
    *
-   * The object is resized on this
-   * operation, and all previous
-   * contents are lost.
+   * The object is resized on this operation, and all previous contents are
+   * lost.
    *
-   * A primitive form of error
-   * checking is performed which
-   * will recognize the bluntest
-   * attempts to interpret some
-   * data as a vector stored
-   * bitwise to a file, but not
-   * more.
+   * A primitive form of error checking is performed which will recognize the
+   * bluntest attempts to interpret some data as a vector stored bitwise to a
+   * file, but not more.
    */
   void block_read (std::istream &in);
 //@}
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception for missing diagonal entry.
@@ -982,19 +766,15 @@ public:
   //@}
 private:
   /**
-   * Find an entry and return a
-   * const pointer. Return a
-   * zero-pointer if the entry does
-   * not exist.
+   * Find an entry and return a const pointer. Return a zero-pointer if the
+   * entry does not exist.
    */
   const Entry *locate (const size_type row,
                        const size_type col) const;
 
   /**
-   * Find an entry and return a
-   * writable pointer. Return a
-   * zero-pointer if the entry does
-   * not exist.
+   * Find an entry and return a writable pointer. Return a zero-pointer if the
+   * entry does not exist.
    */
   Entry *locate (const size_type row,
                  const size_type col);
@@ -1006,13 +786,9 @@ private:
                    const size_type col);
 
   /**
-   * Version of @p vmult which only
-   * performs its actions on the
-   * region defined by
-   * <tt>[begin_row,end_row)</tt>. This
-   * function is called by @p vmult
-   * in the case of enabled
-   * multithreading.
+   * Version of @p vmult which only performs its actions on the region defined
+   * by <tt>[begin_row,end_row)</tt>. This function is called by @p vmult in
+   * the case of enabled multithreading.
    */
   template <typename somenumber>
   void threaded_vmult (Vector<somenumber>       &dst,
@@ -1021,15 +797,9 @@ private:
                        const size_type           end_row) const;
 
   /**
-   * Version of
-   * @p matrix_norm_square which
-   * only performs its actions on
-   * the region defined by
-   * <tt>[begin_row,end_row)</tt>. This
-   * function is called by
-   * @p matrix_norm_square in the
-   * case of enabled
-   * multithreading.
+   * Version of @p matrix_norm_square which only performs its actions on the
+   * region defined by <tt>[begin_row,end_row)</tt>. This function is called
+   * by @p matrix_norm_square in the case of enabled multithreading.
    */
   template <typename somenumber>
   void threaded_matrix_norm_square (const Vector<somenumber> &v,
@@ -1038,15 +808,9 @@ private:
                                     somenumber               *partial_sum) const;
 
   /**
-   * Version of
-   * @p matrix_scalar_product which
-   * only performs its actions on
-   * the region defined by
-   * <tt>[begin_row,end_row)</tt>. This
-   * function is called by
-   * @p matrix_scalar_product in the
-   * case of enabled
-   * multithreading.
+   * Version of @p matrix_scalar_product which only performs its actions on
+   * the region defined by <tt>[begin_row,end_row)</tt>. This function is
+   * called by @p matrix_scalar_product in the case of enabled multithreading.
    */
   template <typename somenumber>
   void threaded_matrix_scalar_product (const Vector<somenumber> &u,
@@ -1056,9 +820,7 @@ private:
                                        somenumber               *partial_sum) const;
 
   /**
-   * Number of columns. This is
-   * used to check vector
-   * dimensions only.
+   * Number of columns. This is used to check vector dimensions only.
    */
   size_type n_columns;
 
index 41bfb2f4c70a0f37d0901b229505127e43f2eafb..c92c40db839e73a253d8865e45488ebfa9f8fef5 100644 (file)
@@ -26,21 +26,20 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * Modified incomplete Cholesky (MIC(0)) preconditioner.  This class
- * conforms to the state and usage specification in
- * SparseLUDecomposition.
+ * Modified incomplete Cholesky (MIC(0)) preconditioner.  This class conforms
+ * to the state and usage specification in SparseLUDecomposition.
  *
  *
  * <h3>The decomposition</h3>
  *
  * Let a sparse matrix $A$ be in the form $A = - L - U + D$, where $-L$ and
  * $-U$ are strictly lower and upper triangular matrices. The MIC(0)
- * decomposition of the matrix $A$ is defined by $B = (X-L)X^(-1)(X-U)$,
- * where $X$ is a diagonal matrix, defined by the condition $\text{rowsum}(A) =
+ * decomposition of the matrix $A$ is defined by $B = (X-L)X^(-1)(X-U)$, where
+ * $X$ is a diagonal matrix, defined by the condition $\text{rowsum}(A) =
  * \text{rowsum}(B)$.
  *
- * @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf
- * Hartmann 2003.
+ * @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf Hartmann
+ * 2003.
  */
 template <typename number>
 class SparseMIC : public SparseLUDecomposition<number>
@@ -52,17 +51,16 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Constructor. Does nothing, so
-   * you have to call @p decompose
-   * sometimes afterwards.
+   * Constructor. Does nothing, so you have to call @p decompose sometimes
+   * afterwards.
    */
   SparseMIC ();
 
   /**
    * @deprecated This method is deprecated, and left for backward
-   * compatibility. It will be removed in later versions.  Instead,
-   * pass the sparsity pattern that you want used for the
-   * decomposition in the AdditionalData structure.
+   * compatibility. It will be removed in later versions.  Instead, pass the
+   * sparsity pattern that you want used for the decomposition in the
+   * AdditionalData structure.
    */
   SparseMIC (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
 
@@ -72,96 +70,74 @@ public:
   virtual ~SparseMIC();
 
   /**
-   * Deletes all member
-   * variables. Leaves the class in
-   * the state that it had directly
-   * after calling the constructor
+   * Deletes all member variables. Leaves the class in the state that it had
+   * directly after calling the constructor
    */
   virtual void clear();
 
   /**
-   * Make the @p AdditionalData
-   * type in the base class
-   * accessible to this class as
-   * well.
+   * Make the @p AdditionalData type in the base class accessible to this
+   * class as well.
    */
   typedef
   typename SparseLUDecomposition<number>::AdditionalData
   AdditionalData;
 
   /**
-   * @deprecated This method is deprecated, and
-   * left for backward
-   * compatibility. It will be
-   * removed in later versions.
+   * @deprecated This method is deprecated, and left for backward
+   * compatibility. It will be removed in later versions.
    */
   void reinit (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
 
   /**
-   * Perform the incomplete LU
-   * factorization of the given
-   * matrix.
+   * Perform the incomplete LU factorization of the given matrix.
    *
-   * This function needs to be
-   * called before an object of
-   * this class is used as
-   * preconditioner.
+   * This function needs to be called before an object of this class is used
+   * as preconditioner.
    *
-   * For more details about
-   * possible parameters, see the
-   * class documentation of
-   * SparseLUDecomposition and the
-   * documentation of the
-   * @p SparseLUDecomposition::AdditionalData
-   * class.
+   * For more details about possible parameters, see the class documentation
+   * of SparseLUDecomposition and the documentation of the @p
+   * SparseLUDecomposition::AdditionalData class.
    *
-   * According to the
-   * @p parameters, this function
-   * creates a new SparsityPattern
-   * or keeps the previous sparsity
-   * or takes the sparsity given by
-   * the user to @p data. Then,
-   * this function performs the MIC
+   * According to the @p parameters, this function creates a new
+   * SparsityPattern or keeps the previous sparsity or takes the sparsity
+   * given by the user to @p data. Then, this function performs the MIC
    * decomposition.
    *
-   * After this function is called
-   * the preconditioner is ready to
-   * be used.
+   * After this function is called the preconditioner is ready to be used.
    */
   template <typename somenumber>
   void initialize (const SparseMatrix<somenumber> &matrix,
                    const AdditionalData &parameters = AdditionalData());
 
   /**
-   * @deprecated This method is deprecated, and left for backward
-   * compability. It will be removed in later versions. Use
-   * initialize() instead.
+   * @deprecated This method is deprecated, and left for backward compability.
+   * It will be removed in later versions. Use initialize() instead.
    */
   template <typename somenumber>
   void decompose (const SparseMatrix<somenumber> &matrix,
                   const double                   strengthen_diagonal=0.) DEAL_II_DEPRECATED;
 
   /**
-   * Apply the incomplete decomposition,
-   * i.e. do one forward-backward step
+   * Apply the incomplete decomposition, i.e. do one forward-backward step
    * $dst=(LU)^{-1}src$.
    *
-   * Call @p initialize before
-   * calling this function.
+   * Call @p initialize before calling this function.
    */
   template <typename somenumber>
   void vmult (Vector<somenumber>       &dst,
               const Vector<somenumber> &src) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * Exception
@@ -184,28 +160,23 @@ public:
   //@}
 private:
   /**
-   * Values of the computed
-   * diagonal.
+   * Values of the computed diagonal.
    */
   std::vector<number> diag;
 
   /**
-   * Inverses of the the diagonal:
-   * precomputed for faster vmult.
+   * Inverses of the the diagonal: precomputed for faster vmult.
    */
   std::vector<number> inv_diag;
 
   /**
-   * Values of the computed "inner
-   * sums", i.e. per-row sums of
-   * the elements laying on the
-   * right side of the diagonal.
+   * Values of the computed "inner sums", i.e. per-row sums of the elements
+   * laying on the right side of the diagonal.
    */
   std::vector<number> inner_sums;
 
   /**
-   * Compute the row-th "inner
-   * sum".
+   * Compute the row-th "inner sum".
    */
   number get_rowsum (const size_type row) const;
 };
index 29585bc39758389ad31e53e62ae660a4e9b4d294..a4fc54216017b8e0eb905f4123d2021a5b372be8 100644 (file)
@@ -39,60 +39,57 @@ template <typename number> class SparseBlockVanka;
  */
 
 /**
- * Point-wise Vanka preconditioning.
- * This class does Vanka preconditioning  on a point-wise base.
- * Vanka preconditioners are used for saddle point problems like Stoke's
- * problem or problems arising in optimization where Lagrange multiplier
- * occur and let Netwon's matrix have a zero block. With these matrices the
- * application of Jacobi or Gauss-Seidel methods is impossible, because
- * some diagonal elements are zero in the rows of the Lagrange multiplier.
- * The approach of Vanka is to solve a small (usually indefinite) system
- * of equations for each Langrange multiplie variable (we will also call
- * the pressure in Stokes' equation a Langrange multiplier since it
- * can be interpreted as such).
+ * Point-wise Vanka preconditioning. This class does Vanka preconditioning  on
+ * a point-wise base. Vanka preconditioners are used for saddle point problems
+ * like Stoke's problem or problems arising in optimization where Lagrange
+ * multiplier occur and let Netwon's matrix have a zero block. With these
+ * matrices the application of Jacobi or Gauss-Seidel methods is impossible,
+ * because some diagonal elements are zero in the rows of the Lagrange
+ * multiplier. The approach of Vanka is to solve a small (usually indefinite)
+ * system of equations for each Langrange multiplie variable (we will also
+ * call the pressure in Stokes' equation a Langrange multiplier since it can
+ * be interpreted as such).
  *
- * Objects of this class are constructed by passing a vector of indices
- * of the degrees of freedom of the Lagrange multiplier. In the actual
- * preconditioning method, these rows are traversed in the order in which
- * the appear in the matrix. Since this is a Gau�-Seidel like procedure,
+ * Objects of this class are constructed by passing a vector of indices of the
+ * degrees of freedom of the Lagrange multiplier. In the actual
+ * preconditioning method, these rows are traversed in the order in which the
+ * appear in the matrix. Since this is a Gau�-Seidel like procedure,
  * remember to have a good ordering in advance (for transport dominated
- * problems, Cuthill-McKee algorithms are a good means for this, if points
- * on the inflow boundary are chosen as starting points for the renumbering).
+ * problems, Cuthill-McKee algorithms are a good means for this, if points on
+ * the inflow boundary are chosen as starting points for the renumbering).
  *
  * For each selected degree of freedom, a local system of equations is built
  * by the degree of freedom itself and all other values coupling immediately,
  * i.e. the set of degrees of freedom considered for the local system of
  * equations for degree of freedom @p i is @p i itself and all @p j such that
  * the element <tt>(i,j)</tt> is a nonzero entry in the sparse matrix under
- * consideration. The elements <tt>(j,i)</tt> are not considered. We now pick all
- * matrix entries from rows and columns out of the set of degrees of freedom
- * just described out of the global matrix and put it into a local matrix,
- * which is subsequently inverted. This system may be of different size for
- * each degree of freedom, depending for example on the local neighborhood of
- * the respective node on a computational grid.
+ * consideration. The elements <tt>(j,i)</tt> are not considered. We now pick
+ * all matrix entries from rows and columns out of the set of degrees of
+ * freedom just described out of the global matrix and put it into a local
+ * matrix, which is subsequently inverted. This system may be of different
+ * size for each degree of freedom, depending for example on the local
+ * neighborhood of the respective node on a computational grid.
  *
- * The right hand side is built up in the same way, i.e. by copying
- * all entries that coupled with the one under present consideration,
- * but it is augmented by all degrees of freedom coupling with the
- * degrees from the set described above (i.e. the DoFs coupling second
- * order to the present one). The reason for this is, that the local
- * problems to be solved shall have Dirichlet boundary conditions on
- * the second order coupling DoFs, so we have to take them into
- * account but eliminate them before actually solving; this
- * elimination is done by the modification of the right hand side, and
- * in the end these degrees of freedom do not occur in the matrix and
- * solution vector any more at all.
+ * The right hand side is built up in the same way, i.e. by copying all
+ * entries that coupled with the one under present consideration, but it is
+ * augmented by all degrees of freedom coupling with the degrees from the set
+ * described above (i.e. the DoFs coupling second order to the present one).
+ * The reason for this is, that the local problems to be solved shall have
+ * Dirichlet boundary conditions on the second order coupling DoFs, so we have
+ * to take them into account but eliminate them before actually solving; this
+ * elimination is done by the modification of the right hand side, and in the
+ * end these degrees of freedom do not occur in the matrix and solution vector
+ * any more at all.
  *
- * This local system is solved and the values are updated into the
- * destination vector.
+ * This local system is solved and the values are updated into the destination
+ * vector.
  *
  * Remark: the Vanka method is a non-symmetric preconditioning method.
  *
  *
- * <h3>Example of Use</h3>
- * This little example is taken from a program doing parameter optimization.
- * The Lagrange multiplier is the third component of the finite element
- * used. The system is solved by the GMRES method.
+ * <h3>Example of Use</h3> This little example is taken from a program doing
+ * parameter optimization. The Lagrange multiplier is the third component of
+ * the finite element used. The system is solved by the GMRES method.
  * @code
  *                        // tag the Lagrange multiplier variable
  *    vector<bool> signature(3);
@@ -116,12 +113,12 @@ template <typename number> class SparseBlockVanka;
  * @endcode
  *
  *
- * <h4>Implementor's remark</h4>
- * At present, the local matrices are built up such that the degree of freedom
- * associated with the local Lagrange multiplier is the first one. Thus, usually
- * the upper left entry in the local matrix is zero. It is not clear to me (W.B.)
- * whether this might pose some problems in the inversion of the local matrices.
- * Maybe someone would like to check this.
+ * <h4>Implementor's remark</h4> At present, the local matrices are built up
+ * such that the degree of freedom associated with the local Lagrange
+ * multiplier is the first one. Thus, usually the upper left entry in the
+ * local matrix is zero. It is not clear to me (W.B.) whether this might pose
+ * some problems in the inversion of the local matrices. Maybe someone would
+ * like to check this.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -139,56 +136,29 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Constructor. Gets the matrix
-   * for preconditioning and a bit
-   * vector with entries @p true for
-   * all rows to be updated. A
-   * reference to this vector will
-   * be stored, so it must persist
-   * longer than the Vanka
-   * object. The same is true for
-   * the matrix.
+   * Constructor. Gets the matrix for preconditioning and a bit vector with
+   * entries @p true for all rows to be updated. A reference to this vector
+   * will be stored, so it must persist longer than the Vanka object. The same
+   * is true for the matrix.
    *
-   * The matrix @p M which is passed
-   * here may or may not be the
-   * same matrix for which this
-   * object shall act as
-   * preconditioner. In particular,
-   * it is conceivable that the
-   * preconditioner is build up for
-   * one matrix once, but is used
-   * for subsequent steps in a
-   * nonlinear process as well,
-   * where the matrix changes in
-   * each step slightly.
+   * The matrix @p M which is passed here may or may not be the same matrix
+   * for which this object shall act as preconditioner. In particular, it is
+   * conceivable that the preconditioner is build up for one matrix once, but
+   * is used for subsequent steps in a nonlinear process as well, where the
+   * matrix changes in each step slightly.
    *
-   * If @p conserve_mem is @p false,
-   * then the inverses of the local
-   * systems are computed now; if
-   * the flag is @p true, then they
-   * are computed every time the
-   * preconditioner is
-   * applied. This saves some
-   * memory, but makes
-   * preconditioning very
-   * slow. Note also, that if the
-   * flag is @p false, then the
-   * contents of the matrix @p M at
-   * the time of calling this
-   * constructor are used, while if
-   * the flag is @p true, then the
-   * values in @p M at the time of
-   * preconditioning are used. This
-   * may lead to different results,
+   * If @p conserve_mem is @p false, then the inverses of the local systems
+   * are computed now; if the flag is @p true, then they are computed every
+   * time the preconditioner is applied. This saves some memory, but makes
+   * preconditioning very slow. Note also, that if the flag is @p false, then
+   * the contents of the matrix @p M at the time of calling this constructor
+   * are used, while if the flag is @p true, then the values in @p M at the
+   * time of preconditioning are used. This may lead to different results,
    * obviously, of @p M changes.
    *
-   * The parameter @p n_threads
-   * determines how many threads
-   * shall be used in parallel when
-   * building the inverses of the
-   * diagonal blocks. This
-   * parameter is ignored if not in
-   * multithreaded mode.
+   * The parameter @p n_threads determines how many threads shall be used in
+   * parallel when building the inverses of the diagonal blocks. This
+   * parameter is ignored if not in multithreaded mode.
    */
   SparseVanka(const SparseMatrix<number> &M,
               const std::vector<bool>    &selected,
@@ -196,16 +166,13 @@ public:
               const unsigned int          n_threads       = multithread_info.n_threads());
 
   /**
-   * Destructor.
-   * Delete all allocated matrices.
+   * Destructor. Delete all allocated matrices.
    */
   ~SparseVanka();
 
   /**
-   * Do the preconditioning.
-   * This function takes the residual
-   * in @p src and returns the resulting
-   * update vector in @p dst.
+   * Do the preconditioning. This function takes the residual in @p src and
+   * returns the resulting update vector in @p dst.
    */
   template<typename number2>
   void vmult (Vector<number2>       &dst,
@@ -213,45 +180,25 @@ public:
 
 protected:
   /**
-   * Apply the inverses
-   * corresponding to those degrees
-   * of freedom that have a @p true
-   * value in @p dof_mask, to the
-   * @p src vector and move the
-   * result into @p dst. Actually,
-   * only values for allowed
-   * indices are written to @p dst,
-   * so the application of this
-   * function only does what is
-   * announced in the general
-   * documentation if the given
-   * mask sets all values to zero
+   * Apply the inverses corresponding to those degrees of freedom that have a
+   * @p true value in @p dof_mask, to the @p src vector and move the result
+   * into @p dst. Actually, only values for allowed indices are written to @p
+   * dst, so the application of this function only does what is announced in
+   * the general documentation if the given mask sets all values to zero
    *
-   * The reason for providing the
-   * mask anyway is that in derived
-   * classes we may want to apply
-   * the preconditioner to parts of
-   * the matrix only, in order to
-   * parallelize the
-   * application. Then, it is
-   * important to only write to
-   * some slices of @p dst, in order
-   * to eliminate the dependencies
-   * of threads of each other.
+   * The reason for providing the mask anyway is that in derived classes we
+   * may want to apply the preconditioner to parts of the matrix only, in
+   * order to parallelize the application. Then, it is important to only write
+   * to some slices of @p dst, in order to eliminate the dependencies of
+   * threads of each other.
    *
-   * If a null pointer is passed
-   * instead of a pointer to the
-   * @p dof_mask (as is the default
-   * value), then it is assumed
-   * that we shall work on all
-   * degrees of freedom. This is
-   * then equivalent to calling the
-   * function with a
-   * <tt>vector<bool>(n_dofs,true)</tt>.
+   * If a null pointer is passed instead of a pointer to the @p dof_mask (as
+   * is the default value), then it is assumed that we shall work on all
+   * degrees of freedom. This is then equivalent to calling the function with
+   * a <tt>vector<bool>(n_dofs,true)</tt>.
    *
-   * The @p vmult of this class
-   * of course calls this function
-   * with a null pointer
+   * The @p vmult of this class of course calls this function with a null
+   * pointer
    */
   template<typename number2>
   void apply_preconditioner (Vector<number2>         &dst,
@@ -259,9 +206,8 @@ protected:
                              const std::vector<bool> *const dof_mask = 0) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -277,88 +223,57 @@ private:
   const bool conserve_mem;
 
   /**
-   * Indices of those degrees of
-   * freedom that we shall work on.
+   * Indices of those degrees of freedom that we shall work on.
    */
   const std::vector<bool> &selected;
 
   /**
-   * Number of threads to be used
-   * when building the
-   * inverses. Only relevant in
+   * Number of threads to be used when building the inverses. Only relevant in
    * multithreaded mode.
    */
   const unsigned int n_threads;
 
   /**
-   * Array of inverse matrices,
-   * one for each degree of freedom.
-   * Only those elements will be used
-   * that are tagged in @p selected.
+   * Array of inverse matrices, one for each degree of freedom. Only those
+   * elements will be used that are tagged in @p selected.
    */
   mutable std::vector<SmartPointer<FullMatrix<float>,SparseVanka<number> > > inverses;
 
   /**
-   * Compute the inverses of all
-   * selected diagonal elements.
+   * Compute the inverses of all selected diagonal elements.
    */
   void compute_inverses ();
 
   /**
-   * Compute the inverses at
-   * positions in the range
-   * <tt>[begin,end)</tt>. In
-   * non-multithreaded mode,
-   * <tt>compute_inverses()</tt> calls
-   * this function with the whole
-   * range, but in multithreaded
-   * mode, several copies of this
+   * Compute the inverses at positions in the range <tt>[begin,end)</tt>. In
+   * non-multithreaded mode, <tt>compute_inverses()</tt> calls this function
+   * with the whole range, but in multithreaded mode, several copies of this
    * function are spawned.
    */
   void compute_inverses (const size_type begin,
                          const size_type end);
 
   /**
-   * Compute the inverse of the
-   * block located at position
-   * @p row. Since the vector is
-   * used quite often, it is
-   * generated only once in the
-   * caller of this function and
-   * passed to this function which
-   * first clears it. Reusing the
-   * vector makes the process
-   * significantly faster than in
-   * the case where this function
-   * re-creates it each time.
+   * Compute the inverse of the block located at position @p row. Since the
+   * vector is used quite often, it is generated only once in the caller of
+   * this function and passed to this function which first clears it. Reusing
+   * the vector makes the process significantly faster than in the case where
+   * this function re-creates it each time.
    */
   void compute_inverse (const size_type         row,
                         std::vector<size_type> &local_indices);
 
   /**
-   * Make the derived class a
-   * friend. This seems silly, but
-   * is actually necessary, since
-   * derived classes can only
-   * access non-public members
-   * through their @p this
-   * pointer, but not access these
-   * members as member functions of
-   * other objects of the type of
-   * this base class (i.e. like
-   * <tt>x.f()</tt>, where @p x is an
-   * object of the base class, and
-   * @p f one of it's non-public
-   * member functions).
+   * Make the derived class a friend. This seems silly, but is actually
+   * necessary, since derived classes can only access non-public members
+   * through their @p this pointer, but not access these members as member
+   * functions of other objects of the type of this base class (i.e. like
+   * <tt>x.f()</tt>, where @p x is an object of the base class, and @p f one
+   * of it's non-public member functions).
    *
-   * Now, in the case of the
-   * @p SparseBlockVanka class, we
-   * would like to take the address
-   * of a function of the base
-   * class in order to call it
-   * through the multithreading
-   * framework, so the derived
-   * class has to be a friend.
+   * Now, in the case of the @p SparseBlockVanka class, we would like to take
+   * the address of a function of the base class in order to call it through
+   * the multithreading framework, so the derived class has to be a friend.
    */
   template <typename T> friend class SparseBlockVanka;
 };
@@ -366,125 +281,112 @@ private:
 
 
 /**
- * Block version of the sparse Vanka preconditioner. This class
- * divides the matrix into blocks and works on the diagonal blocks
- * only, which of course reduces the efficiency as preconditioner, but
- * is perfectly parallelizable. The constructor takes a parameter into
- * how many blocks the matrix shall be subdivided and then lets the
- * underlying class do the work. Division of the matrix is done in
- * several ways which are described in detail below.
+ * Block version of the sparse Vanka preconditioner. This class divides the
+ * matrix into blocks and works on the diagonal blocks only, which of course
+ * reduces the efficiency as preconditioner, but is perfectly parallelizable.
+ * The constructor takes a parameter into how many blocks the matrix shall be
+ * subdivided and then lets the underlying class do the work. Division of the
+ * matrix is done in several ways which are described in detail below.
  *
- * This class is probably useless if you don't have a multiprocessor
- * system, since then the amount of work per preconditioning step is
- * the same as for the @p SparseVanka class, but preconditioning
- * properties are worse. On the other hand, if you have a
- * multiprocessor system, the worse preconditioning quality (leading
- * to more iterations of the linear solver) usually is well balanced
- * by the increased speed of application due to the parallelization,
- * leading to an overall decrease in elapsed wall-time for solving
- * your linear system. It should be noted that the quality as
- * preconditioner reduces with growing number of blocks, so there may
- * be an optimal value (in terms of wall-time per linear solve) for
- * the number of blocks.
+ * This class is probably useless if you don't have a multiprocessor system,
+ * since then the amount of work per preconditioning step is the same as for
+ * the @p SparseVanka class, but preconditioning properties are worse. On the
+ * other hand, if you have a multiprocessor system, the worse preconditioning
+ * quality (leading to more iterations of the linear solver) usually is well
+ * balanced by the increased speed of application due to the parallelization,
+ * leading to an overall decrease in elapsed wall-time for solving your linear
+ * system. It should be noted that the quality as preconditioner reduces with
+ * growing number of blocks, so there may be an optimal value (in terms of
+ * wall-time per linear solve) for the number of blocks.
  *
- * To facilitate writing portable code, if the number of blocks into
- * which the matrix is to be subdivided, is set to one, then this
- * class acts just like the @p SparseVanka class. You may therefore
- * want to set the number of blocks equal to the number of processors
- * you have.
+ * To facilitate writing portable code, if the number of blocks into which the
+ * matrix is to be subdivided, is set to one, then this class acts just like
+ * the @p SparseVanka class. You may therefore want to set the number of
+ * blocks equal to the number of processors you have.
  *
  * Note that the parallelization is done if <tt>deal.II</tt> was configured
- * for multithread use and that the number of threads which is spawned
- * equals the number of blocks. This is reasonable since you will not
- * want to set the number of blocks unnecessarily large, since, as
- * mentioned, this reduces the preconditioning properties.
+ * for multithread use and that the number of threads which is spawned equals
+ * the number of blocks. This is reasonable since you will not want to set the
+ * number of blocks unnecessarily large, since, as mentioned, this reduces the
+ * preconditioning properties.
  *
  *
  * <h3>Splitting the matrix into blocks</h3>
  *
- * Splitting the matrix into blocks is always done in a way such that
- * the blocks are not necessarily of equal size, but such that the
- * number of selected degrees of freedom for which a local system is
- * to be solved is equal between blocks. The reason for this strategy
- * to subdivision is load-balancing for multithreading. There are
- * several possibilities to actually split the matrix into blocks,
- * which are selected by the flag @p blocking_strategy that is passed
- * to the constructor. By a block, we will in the sequel denote a list
- * of indices of degrees of freedom; the algorithm will work on each
- * block separately, i.e. the solutions of the local systems
- * corresponding to a degree of freedom of one block will only be used
- * to update the degrees of freedom belonging to the same block, but
- * never to update degrees of freedoms of other blocks. A block can be
- * a consecutive list of indices, as in the first alternative below,
- * or a nonconsecutive list of indices. Of course, we assume that the
- * intersection of each two blocks is empty and that the union of all
- * blocks equals the interval <tt>[0,N)</tt>, where @p N is the number of
- * degrees of freedom of the system of equations.
+ * Splitting the matrix into blocks is always done in a way such that the
+ * blocks are not necessarily of equal size, but such that the number of
+ * selected degrees of freedom for which a local system is to be solved is
+ * equal between blocks. The reason for this strategy to subdivision is load-
+ * balancing for multithreading. There are several possibilities to actually
+ * split the matrix into blocks, which are selected by the flag @p
+ * blocking_strategy that is passed to the constructor. By a block, we will in
+ * the sequel denote a list of indices of degrees of freedom; the algorithm
+ * will work on each block separately, i.e. the solutions of the local systems
+ * corresponding to a degree of freedom of one block will only be used to
+ * update the degrees of freedom belonging to the same block, but never to
+ * update degrees of freedoms of other blocks. A block can be a consecutive
+ * list of indices, as in the first alternative below, or a nonconsecutive
+ * list of indices. Of course, we assume that the intersection of each two
+ * blocks is empty and that the union of all blocks equals the interval
+ * <tt>[0,N)</tt>, where @p N is the number of degrees of freedom of the
+ * system of equations.
  *
  * <ul>
- * <li> @p index_intervals:
- *    Here, we chose the blocks to be intervals <tt>[a_i,a_{i+1</tt>)},
- *    i.e. consecutive degrees of freedom are usually also within the
- *    same block. This is a reasonable strategy, if the degrees of
- *    freedom have, for example, be re-numbered using the
- *    Cuthill-McKee algorithm, in which spatially neighboring degrees
- *    of freedom have neighboring indices. In that case, coupling in
- *    the matrix is usually restricted to the vicinity of the diagonal
- *    as well, and we can simply cut the matrix into blocks.
+ * <li> @p index_intervals: Here, we chose the blocks to be intervals
+ * <tt>[a_i,a_{i+1</tt>)}, i.e. consecutive degrees of freedom are usually
+ * also within the same block. This is a reasonable strategy, if the degrees
+ * of freedom have, for example, be re-numbered using the Cuthill-McKee
+ * algorithm, in which spatially neighboring degrees of freedom have
+ * neighboring indices. In that case, coupling in the matrix is usually
+ * restricted to the vicinity of the diagonal as well, and we can simply cut
+ * the matrix into blocks.
  *
- *    The bounds of the intervals, i.e. the @p a_i above, are chosen
- *    such that the number of degrees of freedom on which we shall
- *    work (i.e. usually the degrees of freedom corresponding to
- *    Lagrange multipliers) is about the same in each block; this does
- *    not mean, however, that the sizes of the blocks are equal, since
- *    the blocks also comprise the other degrees of freedom for which
- *    no local system is solved. In the extreme case, consider that
- *    all Lagrange multipliers are sorted to the end of the range of
- *    DoF indices, then the first block would be very large, since it
- *    comprises all other DoFs and some Lagrange multipliers, while
- *    all other blocks are rather small and comprise only Langrange
- *    multipliers. This strategy therefore does not only depend on the
- *    order in which the Lagrange DoFs are sorted, but also on the
- *    order in which the other DoFs are sorted. It is therefore
- *    necessary to note that this almost renders the capability as
- *    preconditioner useless if the degrees of freedom are numbered by
- *    component, i.e. all Lagrange multipliers en bloc.
+ * The bounds of the intervals, i.e. the @p a_i above, are chosen such that
+ * the number of degrees of freedom on which we shall work (i.e. usually the
+ * degrees of freedom corresponding to Lagrange multipliers) is about the same
+ * in each block; this does not mean, however, that the sizes of the blocks
+ * are equal, since the blocks also comprise the other degrees of freedom for
+ * which no local system is solved. In the extreme case, consider that all
+ * Lagrange multipliers are sorted to the end of the range of DoF indices,
+ * then the first block would be very large, since it comprises all other DoFs
+ * and some Lagrange multipliers, while all other blocks are rather small and
+ * comprise only Langrange multipliers. This strategy therefore does not only
+ * depend on the order in which the Lagrange DoFs are sorted, but also on the
+ * order in which the other DoFs are sorted. It is therefore necessary to note
+ * that this almost renders the capability as preconditioner useless if the
+ * degrees of freedom are numbered by component, i.e. all Lagrange multipliers
+ * en bloc.
  *
- * <li> @p adaptive: This strategy is a bit more clever in cases where
- *    the Langrange DoFs are clustered, as in the example above. It
- *    works as follows: it first groups the Lagrange DoFs into blocks,
- *    using the same strategy as above. However, instead of grouping
- *    the other DoFs into the blocks of Lagrange DoFs with nearest DoF
- *    index, it decides for each non-Lagrange DoF to put it into the
- *    block of Lagrange DoFs which write to this non-Lagrange DoF most
- *    often. This makes it possible to even sort the Lagrange DoFs to
- *    the end and still associate spatially neighboring non-Lagrange
- *    DoFs to the same blocks where the respective Lagrange DoFs are,
- *    since they couple to each other while spatially distant DoFs
- *    don't couple.
+ * <li> @p adaptive: This strategy is a bit more clever in cases where the
+ * Langrange DoFs are clustered, as in the example above. It works as follows:
+ * it first groups the Lagrange DoFs into blocks, using the same strategy as
+ * above. However, instead of grouping the other DoFs into the blocks of
+ * Lagrange DoFs with nearest DoF index, it decides for each non-Lagrange DoF
+ * to put it into the block of Lagrange DoFs which write to this non-Lagrange
+ * DoF most often. This makes it possible to even sort the Lagrange DoFs to
+ * the end and still associate spatially neighboring non-Lagrange DoFs to the
+ * same blocks where the respective Lagrange DoFs are, since they couple to
+ * each other while spatially distant DoFs don't couple.
  *
- *    The additional computational effort to sorting the non-Lagrange
- *    DoFs is not very large compared with the inversion of the local
- *    systems and applying the preconditioner, so this strategy might
- *    be reasonable if you want to sort your degrees of freedom by
- *    component. If the degrees of freedom are not sorted by
- *    component, the results of the both strategies outlined above
- *    does not differ much. However, unlike the first strategy, the
- *    performance of the second strategy does not deteriorate if the
- *    DoFs are renumbered by component.
+ * The additional computational effort to sorting the non-Lagrange DoFs is not
+ * very large compared with the inversion of the local systems and applying
+ * the preconditioner, so this strategy might be reasonable if you want to
+ * sort your degrees of freedom by component. If the degrees of freedom are
+ * not sorted by component, the results of the both strategies outlined above
+ * does not differ much. However, unlike the first strategy, the performance
+ * of the second strategy does not deteriorate if the DoFs are renumbered by
+ * component.
  * </ul>
  *
  *
  * <h3>Typical results</h3>
  *
- * As a prototypical test case, we use a nonlinear problem from
- * optimization, which leads to a series of saddle point problems,
- * each of which is solved using GMRES with Vanka as
- * preconditioner. The equation had approx. 850 degrees of
- * freedom. With the non-blocked version @p SparseVanka (or
- * @p SparseBlockVanka with <tt>n_blocks==1</tt>), the following numbers of
- * iterations is needed to solver the linear system in each nonlinear
- * step:
+ * As a prototypical test case, we use a nonlinear problem from optimization,
+ * which leads to a series of saddle point problems, each of which is solved
+ * using GMRES with Vanka as preconditioner. The equation had approx. 850
+ * degrees of freedom. With the non-blocked version @p SparseVanka (or @p
+ * SparseBlockVanka with <tt>n_blocks==1</tt>), the following numbers of
+ * iterations is needed to solver the linear system in each nonlinear step:
  * @verbatim
  *   101 68 64 53 35 21
  * @endverbatim
@@ -493,22 +395,21 @@ private:
  * @verbatim
  *   124 88 83 66 44 28
  * @endverbatim
- * As can be seen, more iterations are needed. However, in terms of
- * computing time, the first version needs 72 seconds wall time (and
- * 79 seconds CPU time, which is more than wall time since some other
- * parts of the program were parallelized as well), while the second
- * version needed 53 second wall time (and 110 seconds CPU time) on a
- * four processor machine. The total time is in both cases dominated
- * by the linear solvers. In this case, it is therefore worth while
- * using the blocked version of the preconditioner if wall time is
- * more important than CPU time.
+ * As can be seen, more iterations are needed. However, in terms of computing
+ * time, the first version needs 72 seconds wall time (and 79 seconds CPU
+ * time, which is more than wall time since some other parts of the program
+ * were parallelized as well), while the second version needed 53 second wall
+ * time (and 110 seconds CPU time) on a four processor machine. The total time
+ * is in both cases dominated by the linear solvers. In this case, it is
+ * therefore worth while using the blocked version of the preconditioner if
+ * wall time is more important than CPU time.
  *
- * The results with the block version above were obtained with the
- * first blocking strategy and the degrees of freedom were not
- * numbered by component. Using the second strategy does not much
- * change the numbers of iterations (at most by one in each step) and
- * they also do not change when the degrees of freedom are sorted
- * by component, while the first strategy significantly deteriorated.
+ * The results with the block version above were obtained with the first
+ * blocking strategy and the degrees of freedom were not numbered by
+ * component. Using the second strategy does not much change the numbers of
+ * iterations (at most by one in each step) and they also do not change when
+ * the degrees of freedom are sorted by component, while the first strategy
+ * significantly deteriorated.
  *
  * @author Wolfgang Bangerth, 2000
  */
@@ -522,10 +423,8 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Enumeration of the different
-   * methods by which the DoFs are
-   * distributed to the blocks on
-   * which we are to work.
+   * Enumeration of the different methods by which the DoFs are distributed to
+   * the blocks on which we are to work.
    */
   enum BlockingStrategy
   {
@@ -533,9 +432,7 @@ public:
   };
 
   /**
-   * Constructor. Pass all
-   * arguments except for
-   * @p n_blocks to the base class.
+   * Constructor. Pass all arguments except for @p n_blocks to the base class.
    */
   SparseBlockVanka (const SparseMatrix<number> &M,
                     const std::vector<bool>    &selected,
@@ -552,9 +449,8 @@ public:
               const Vector<number2> &src) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -565,26 +461,17 @@ private:
   const unsigned int n_blocks;
 
   /**
-   * In this field, we precompute
-   * for each block which degrees
-   * of freedom belong to it. Thus,
-   * if <tt>dof_masks[i][j]==true</tt>,
-   * then DoF @p j belongs to block
-   * @p i. Of course, no other
-   * <tt>dof_masks[l][j]</tt> may be
-   * @p true for <tt>l!=i</tt>. This
-   * computation is done in the
-   * constructor, to avoid
-   * recomputing each time the
-   * preconditioner is called.
+   * In this field, we precompute for each block which degrees of freedom
+   * belong to it. Thus, if <tt>dof_masks[i][j]==true</tt>, then DoF @p j
+   * belongs to block @p i. Of course, no other <tt>dof_masks[l][j]</tt> may
+   * be @p true for <tt>l!=i</tt>. This computation is done in the
+   * constructor, to avoid recomputing each time the preconditioner is called.
    */
   std::vector<std::vector<bool> > dof_masks;
 
   /**
-   * Compute the contents of the
-   * field @p dof_masks. This
-   * function is called from the
-   * constructor.
+   * Compute the contents of the field @p dof_masks. This function is called
+   * from the constructor.
    */
   void compute_dof_masks (const SparseMatrix<number> &M,
                           const std::vector<bool>    &selected,
index a45e013dd7893cee49e8229675b7c20b904237f9..b6eadf2d50724bfa395bcef83d91248ab1ea6461 100644 (file)
@@ -104,9 +104,9 @@ namespace SparsityPatternIterators
   typedef types::global_dof_index size_type;
 
   /**
-   * Accessor class for iterators into sparsity patterns. This class is
-   * also the base class for both const and non-const accessor classes
-   * into sparse matrices.
+   * Accessor class for iterators into sparsity patterns. This class is also
+   * the base class for both const and non-const accessor classes into sparse
+   * matrices.
    *
    * Note that this class only allows read access to elements, providing their
    * row and column number (or alternatively the index within the complete
@@ -147,8 +147,9 @@ namespace SparsityPatternIterators
     size_type row () const;
 
     /**
-     * Index within the current row of the element represented by this object. This function
-     * can only be called for entries for which is_valid_entry() is true.
+     * Index within the current row of the element represented by this object.
+     * This function can only be called for entries for which is_valid_entry()
+     * is true.
      */
     size_type index () const;
 
@@ -164,8 +165,8 @@ namespace SparsityPatternIterators
      * entries are valid. However, before compression, the sparsity pattern
      * allocated some memory to be used while still adding new nonzero
      * entries; if you create iterators in this phase of the sparsity
-     * pattern's lifetime, you will iterate over elements that are not
-     * valid. If this is so, then this function will return false.
+     * pattern's lifetime, you will iterate over elements that are not valid.
+     * If this is so, then this function will return false.
      */
     bool is_valid_entry () const;
 
@@ -219,12 +220,12 @@ namespace SparsityPatternIterators
   /**
    * STL conforming iterator walking over the elements of a sparsity pattern.
    *
-   * The typical use for these iterators is to iterate over the elements of
-   * sparsity pattern (or, since they also serve as the basis for iterating
-   * over the elements of an associated matrix, over the elements of a sparse matrix)
-   * or over the elements of individual rows. Note that there is no guarantee
-   * that the elements of a row are actually traversed in an order in which
-   * columns monotonically increase. See the documentation of the
+   * The typical use for these iterators is to iterate over the elements of a
+   * sparsity pattern (or, since they also serve as the basis for iterating
+   * over the elements of an associated matrix, over the elements of a sparse
+   * matrix) or over the elements of individual rows. Note that there is no
+   * guarantee that the elements of a row are actually traversed in an order
+   * in which columns monotonically increase. See the documentation of the
    * SparsityPattern class for more information.
    *
    * @note This class operates directly on the internal data structures of the
@@ -235,10 +236,10 @@ namespace SparsityPatternIterators
    * matrix with $N$ row). As a consequence, when you design algorithms that
    * use these iterators, it is common practice to not loop over <i>all</i>
    * elements of a sparsity pattern at once, but to have an outer loop over
-   * all rows and within this loop iterate over the elements of this row.
-   * This way, you only ever need to dereference the iterator to obtain
-   * the column indices whereas the (expensive) lookup of the row index
-   * can be avoided by using the loop index instead.
+   * all rows and within this loop iterate over the elements of this row. This
+   * way, you only ever need to dereference the iterator to obtain the column
+   * indices whereas the (expensive) lookup of the row index can be avoided by
+   * using the loop index instead.
    */
   class Iterator
   {
@@ -302,10 +303,10 @@ namespace SparsityPatternIterators
     bool operator < (const Iterator &) const;
 
     /**
-     * Return the distance between the current iterator and the argument.
-     * The distance is given by how many times one has to apply operator++
-     * to the current iterator to get the argument (for a positive return
-     * value), or operator-- (for a negative return value).
+     * Return the distance between the current iterator and the argument. The
+     * distance is given by how many times one has to apply operator++ to the
+     * current iterator to get the argument (for a positive return value), or
+     * operator-- (for a negative return value).
      */
     int operator - (const Iterator &p) const;
 
@@ -320,29 +321,29 @@ namespace SparsityPatternIterators
 
 
 /**
- * Structure representing the sparsity pattern of a sparse matrix.
- * This class is an example of the "static" type of @ref Sparsity.
- * It uses the compressed row storage (CSR) format to store data.
+ * Structure representing the sparsity pattern of a sparse matrix. This class
+ * is an example of the "static" type of @ref Sparsity. It uses the compressed
+ * row storage (CSR) format to store data.
  *
  * The elements of a SparsityPattern, corresponding to the places where
  * SparseMatrix objects can store nonzero entries, are stored row-by-row.
  * Within each row, elements are generally stored left-to-right in increasing
- * column index order; the exception to this rule is that if the matrix
- * is square (n_rows() == n_columns()), then the diagonal entry is stored
- * as the first element in each row to make operations like applying a
- * Jacobi or SSOR preconditioner faster. As a consequence, if you traverse
- * the elements of a row of a SparsityPattern with the help of iterators into
- * this object (using SparsityPattern::begin and SparsityPattern::end) you
- * will find that the elements are not sorted by column index within each row
- * whenever the matrix is square (the first item will be the diagonal, followed
- * by the other entries sorted by column index).
+ * column index order; the exception to this rule is that if the matrix is
+ * square (n_rows() == n_columns()), then the diagonal entry is stored as the
+ * first element in each row to make operations like applying a Jacobi or SSOR
+ * preconditioner faster. As a consequence, if you traverse the elements of a
+ * row of a SparsityPattern with the help of iterators into this object (using
+ * SparsityPattern::begin and SparsityPattern::end) you will find that the
+ * elements are not sorted by column index within each row whenever the matrix
+ * is square (the first item will be the diagonal, followed by the other
+ * entries sorted by column index).
  *
- * @note While this class forms the basis upon which SparseMatrix
- * objects base their storage format, and thus plays a central role in
- * setting up linear systems, it is rarely set up directly due to the
- * way it stores its information. Rather, one typically goes through
- * an intermediate format first, see for example the step-2 tutorial
- * program as well as the documentation module @ref Sparsity.
+ * @note While this class forms the basis upon which SparseMatrix objects base
+ * their storage format, and thus plays a central role in setting up linear
+ * systems, it is rarely set up directly due to the way it stores its
+ * information. Rather, one typically goes through an intermediate format
+ * first, see for example the step-2 tutorial program as well as the
+ * documentation module @ref Sparsity.
  *
  * @author Wolfgang Bangerth, Guido Kanschat and others
  */
@@ -400,8 +401,8 @@ public:
   static const size_type invalid_entry = numbers::invalid_size_type;
 
   /**
-   * @name Construction and setup
-   * Constructors, destructor; functions initializing, copying and filling an object.
+   * @name Construction and setup Constructors, destructor; functions
+   * initializing, copying and filling an object.
    */
 // @{
   /**
@@ -431,9 +432,8 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg max_per_row maximum number of nonzero entries per row
+   * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+   * number of nonzero entries per row
    */
   SparsityPattern (const size_type m,
                    const size_type n,
@@ -443,10 +443,9 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
+   * @arg m number of rows @arg n number of columns @arg row_lengths possible
+   * number of nonzero entries for each row.  This vector must have one entry
+   * for each row.
    */
   SparsityPattern (const size_type               m,
                    const size_type               n,
@@ -466,9 +465,9 @@ public:
   /**
    * Initialize a quadratic matrix.
    *
-   * @arg m number of rows and columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
+   * @arg m number of rows and columns @arg row_lengths possible number of
+   * nonzero entries for each row.  This vector must have one entry for each
+   * row.
    */
   SparsityPattern (const size_type               m,
                    const std::vector<unsigned int> &row_lengths);
@@ -478,8 +477,8 @@ public:
    *
    * This constructs objects intended for the application of the ILU(n)-method
    * or other incomplete decompositions.  Therefore, additional to the
-   * original entry structure, space for <tt>extra_off_diagonals</tt>
-   * side-diagonals is provided on both sides of the main diagonal.
+   * original entry structure, space for <tt>extra_off_diagonals</tt> side-
+   * diagonals is provided on both sides of the main diagonal.
    *
    * <tt>max_per_row</tt> is the maximum number of nonzero elements per row
    * which this structure is to hold. It is assumed that this number is
@@ -488,8 +487,8 @@ public:
    * will usually want to give the same number as you gave for
    * <tt>original</tt> plus the number of side diagonals times two. You may
    * however give a larger value if you wish to add further nonzero entries
-   * for the decomposition based on other criteria than their being on
-   * side-diagonals.
+   * for the decomposition based on other criteria than their being on side-
+   * diagonals.
    *
    * This function requires that <tt>original</tt> refers to a quadratic
    * matrix structure.  It must be compressed. The matrix structure is not
@@ -650,8 +649,8 @@ public:
   /**
    * Copy data from an object of type CompressedSparsityPattern,
    * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Although
-   * not a compressed sparsity pattern, this function is also instantiated
-   * if the argument is of type SparsityPattern (i.e., the current class).
+   * not a compressed sparsity pattern, this function is also instantiated if
+   * the argument is of type SparsityPattern (i.e., the current class).
    * Previous content of this object is lost, and the sparsity pattern is in
    * compressed mode afterwards.
    */
@@ -714,8 +713,8 @@ public:
    * iterator can be used to walk over all nonzero entries of the sparsity
    * pattern.
    *
-   * Note the discussion in the general documentation of this class about
-   * the order in which elements are accessed.
+   * Note the discussion in the general documentation of this class about the
+   * order in which elements are accessed.
    */
   iterator begin () const;
 
@@ -754,7 +753,7 @@ public:
    */
 // @{
   /**
-   *  Test for equality of two SparsityPatterns.
+   * Test for equality of two SparsityPatterns.
    */
   bool operator == (const SparsityPattern &)  const;
 
@@ -850,13 +849,13 @@ public:
    * complexity of this function is <i>log(m)</i> if the sparsity pattern is
    * compressed.
    *
-   * @note This function is not cheap since it has to search through all
-   * of the elements of the given row <tt>i</tt> to find whether index
-   * <tt>j</tt> exists. Thus, it is more expensive than necessary in cases
-   * where you want to loop over all of the nonzero elements of this
-   * sparsity pattern (or of a sparse matrix associated with it) or of a
-   * single row. In such cases, it is more efficient to use iterators over
-   * the elements of the sparsity pattern or of the sparse matrix.
+   * @note This function is not cheap since it has to search through all of
+   * the elements of the given row <tt>i</tt> to find whether index <tt>j</tt>
+   * exists. Thus, it is more expensive than necessary in cases where you want
+   * to loop over all of the nonzero elements of this sparsity pattern (or of
+   * a sparse matrix associated with it) or of a single row. In such cases, it
+   * is more efficient to use iterators over the elements of the sparsity
+   * pattern or of the sparse matrix.
    */
   size_type operator() (const size_type i,
                         const size_type j) const;
@@ -898,9 +897,8 @@ public:
    * i.e. <tt>column_number(row,0)==row</tt>.
    *
    * If the sparsity pattern is already compressed, then (except for the
-   * diagonal element), the entries are sorted by columns,
-   * i.e. <tt>column_number(row,i)</tt> <tt><</tt>
-   * <tt>column_number(row,i+1)</tt>.
+   * diagonal element), the entries are sorted by columns, i.e.
+   * <tt>column_number(row,i)</tt> <tt><</tt> <tt>column_number(row,i+1)</tt>.
    */
   size_type column_number (const size_type row,
                            const unsigned int index) const;
@@ -924,10 +922,10 @@ public:
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously been written by block_write() from a
-   * file. This is done using the inverse operations to the above function, so
-   * it is reasonably fast because the bitstream is not interpreted except for
-   * a few numbers up front.
+   * Read data that has previously been written by block_write() from a file.
+   * This is done using the inverse operations to the above function, so it is
+   * reasonably fast because the bitstream is not interpreted except for a few
+   * numbers up front.
    *
    * The object is resized on this operation, and all previous contents are
    * lost.
@@ -983,13 +981,12 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg max_per_row maximum number of nonzero entries per row
-   * @arg optimize_diagonal This parameter is ignored.
+   * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+   * number of nonzero entries per row @arg optimize_diagonal This parameter
+   * is ignored.
    *
-   * @deprecated Use the constructor without the last argument since
-   *   it is ignored.
+   * @deprecated Use the constructor without the last argument since it is
+   * ignored.
    */
   SparsityPattern (const size_type m,
                    const size_type n,
@@ -999,14 +996,12 @@ public:
   /**
    * Initialize a rectangular matrix.
    *
-   * @arg m number of rows
-   * @arg n number of columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
-   * @arg optimize_diagonal This argument is ignored.
+   * @arg m number of rows @arg n number of columns @arg row_lengths possible
+   * number of nonzero entries for each row.  This vector must have one entry
+   * for each row. @arg optimize_diagonal This argument is ignored.
    *
-   * @deprecated Use the constructor without the last argument since
-   *   it is ignored.
+   * @deprecated Use the constructor without the last argument since it is
+   * ignored.
    */
   SparsityPattern (const size_type               m,
                    const size_type               n,
@@ -1016,13 +1011,12 @@ public:
   /**
    * Initialize a quadratic matrix.
    *
-   * @arg m number of rows and columns
-   * @arg row_lengths possible number of nonzero entries for each row.  This
-   * vector must have one entry for each row.
-   * @arg optimize_diagonal This argument is ignored.
+   * @arg m number of rows and columns @arg row_lengths possible number of
+   * nonzero entries for each row.  This vector must have one entry for each
+   * row. @arg optimize_diagonal This argument is ignored.
    *
-   * @deprecated Use the constructor without the last argument since
-   *   it is ignored.
+   * @deprecated Use the constructor without the last argument since it is
+   * ignored.
    */
   SparsityPattern (const size_type               m,
                    const std::vector<unsigned int> &row_lengths,
@@ -1044,7 +1038,7 @@ public:
    * optimized access in relaxation methods of SparseMatrix.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   void reinit (const size_type               m,
                const size_type               n,
@@ -1056,7 +1050,7 @@ public:
    * Same as above, but with a VectorSlice argument instead.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   void reinit (const size_type                                   m,
                const size_type                                   n,
@@ -1072,7 +1066,7 @@ public:
    * function.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   void reinit (const size_type m,
                const size_type n,
@@ -1156,7 +1150,7 @@ public:
    * iterators that point to such pairs.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   template <typename ForwardIterator>
   void copy_from (const size_type       n_rows,
@@ -1167,12 +1161,12 @@ public:
 
   /**
    * Copy data from an object of type CompressedSparsityPattern,
-   * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern.
-   * Previous content of this object is lost, and the sparsity pattern is in
-   * compressed mode afterwards.
+   * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Previous
+   * content of this object is lost, and the sparsity pattern is in compressed
+   * mode afterwards.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   template <typename CompressedSparsityType>
   void copy_from (const CompressedSparsityType &csp,
@@ -1187,7 +1181,7 @@ public:
    * compressed mode afterwards.
    *
    * @deprecated The last argument of this function is ignored. Use the
-   *     version of this function without the last argument.
+   * version of this function without the last argument.
    */
   template <typename number>
   void copy_from (const FullMatrix<number> &matrix,
@@ -1201,8 +1195,8 @@ public:
    * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    *
-   * @deprecated Use the iterators provided by the begin() and end()
-   * functions instead.
+   * @deprecated Use the iterators provided by the begin() and end() functions
+   * instead.
    */
   row_iterator row_begin (const size_type r) const DEAL_II_DEPRECATED;
 
@@ -1214,8 +1208,8 @@ public:
    * particular the case if it is the end iterator for the last row of a
    * matrix.
    *
-   * @deprecated Use the iterators provided by the begin() and end()
-   * functions instead.
+   * @deprecated Use the iterators provided by the begin() and end() functions
+   * instead.
    */
   row_iterator row_end (const size_type r) const DEAL_II_DEPRECATED;
 
@@ -1223,8 +1217,8 @@ public:
    * Determine whether the matrix uses the special convention for quadratic
    * matrices that the diagonal entries are stored first in each row.
    *
-   * @deprecated The function always returns true if the matrix is
-   * square and false if it is not.
+   * @deprecated The function always returns true if the matrix is square and
+   * false if it is not.
    */
   bool optimize_diagonal () const DEAL_II_DEPRECATED;
 
@@ -1309,9 +1303,10 @@ public:
 // @}
 
   BOOST_SERIALIZATION_SPLIT_MEMBER()
-  /** @addtogroup Exceptions
-   * @name Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions @name Exceptions
+   * @{
+   */
   /**
    * You tried to add an element to a row, but there was no space left.
    */
@@ -1452,8 +1447,7 @@ private:
   friend class ChunkSparsityPattern;
 
   /**
-   * Also give access to internal details to the iterator/accessor
-   * classes.
+   * Also give access to internal details to the iterator/accessor classes.
    */
   friend class SparsityPatternIterators::Iterator;
   friend class SparsityPatternIterators::Accessor;
index fe71ea76b76b589c5c5099852d15c1041b6fedf1..3741f6328dbf279ad7e692e46bbcfb95d513334c 100644 (file)
@@ -40,7 +40,7 @@ DEAL_II_NAMESPACE_OPEN
  * patterns, such as renumbering rows and columns (or degrees of freedom if
  * you want) according to the connectivity, or partitioning degrees of
  * freedom.
-*/
+ */
 namespace SparsityTools
 {
   /**
@@ -103,11 +103,11 @@ namespace SparsityTools
    * These algorithms have one major drawback: they require a good starting
    * node, i.e. node that will have number zero in the output array. A
    * starting node forming the initial level of nodes can thus be given by the
-   * user, e.g. by exploiting knowledge of the actual topology of the
-   * domain. It is also possible to give several starting indices, which may
-   * be used to simulate a simple upstream numbering (by giving the inflow
-   * nodes as starting values) or to make preconditioning faster (by letting
-   * the Dirichlet boundary indices be starting points).
+   * user, e.g. by exploiting knowledge of the actual topology of the domain.
+   * It is also possible to give several starting indices, which may be used
+   * to simulate a simple upstream numbering (by giving the inflow nodes as
+   * starting values) or to make preconditioning faster (by letting the
+   * Dirichlet boundary indices be starting points).
    *
    * If no starting index is given, one is chosen automatically, namely one
    * with the smallest coordination number (the coordination number is the
@@ -165,9 +165,9 @@ namespace SparsityTools
 
   /**
    * similar to the function above, but includes support for
-   * BlockCompressedSimpleSparsityPattern.
-   * @p owned_set_per_cpu is typically DoFHandler::locally_owned_dofs_per_processor
-   * and @p myrange are locally_relevant_dofs.
+   * BlockCompressedSimpleSparsityPattern. @p owned_set_per_cpu is typically
+   * DoFHandler::locally_owned_dofs_per_processor and @p myrange are
+   * locally_relevant_dofs.
    */
   template <class CSP_t>
   void distribute_sparsity_pattern(CSP_t &csp,
@@ -208,7 +208,7 @@ namespace SparsityTools
 }
 
 /**
- *@}
+ * @}
  */
 
 DEAL_II_NAMESPACE_CLOSE
index bfa1ec7bc61b50f600f08c3876990de80c93c940..6b21f8203b9e6df03ab65e68cc8c78a52261c34b 100644 (file)
@@ -29,22 +29,20 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * This class is a wrapper to the @p Vector class which allows to swap
- * out the data to a file and reload it later on. It handles the
- * management of the name of the file where the data is to be stored
- * temporarily and removes the file is necessary at the end of the
- * lifetime of the vector.
+ * This class is a wrapper to the @p Vector class which allows to swap out the
+ * data to a file and reload it later on. It handles the management of the
+ * name of the file where the data is to be stored temporarily and removes the
+ * file is necessary at the end of the lifetime of the vector.
  *
- * There are functions to swap the data to a file, and to reload
- * it. There is also a function @p alert that can be used to signal to
- * an object of this class that the data will be needed shortly, so
- * the object can initiate that the data be loaded already. While in
- * non-multithreading mode, this function has no effect since @p reload
- * has to be called afterwards anyway. On the other hand, in
- * multithreading mode, the data is preloaded in the background using
- * a thread on its own, and may already be available at the time when
- * @p reload is called. If it is not available, @p reload waits until
- * the detached thread has loaded the data.
+ * There are functions to swap the data to a file, and to reload it. There is
+ * also a function @p alert that can be used to signal to an object of this
+ * class that the data will be needed shortly, so the object can initiate that
+ * the data be loaded already. While in non-multithreading mode, this function
+ * has no effect since @p reload has to be called afterwards anyway. On the
+ * other hand, in multithreading mode, the data is preloaded in the background
+ * using a thread on its own, and may already be available at the time when @p
+ * reload is called. If it is not available, @p reload waits until the
+ * detached thread has loaded the data.
  *
  * @note Instantiations for this template are provided for <tt>@<float@> and
  * @<double@></tt>; others can be generated in application programs (see the
@@ -57,158 +55,102 @@ class SwappableVector : public Vector<number>
 {
 public:
   /**
-   * Constructor. Does nothing
-   * apart from calling the
-   * constructor of the underlying
-   * class.
+   * Constructor. Does nothing apart from calling the constructor of the
+   * underlying class.
    */
   SwappableVector ();
 
   /**
-   * Copy constructor. Copies the
-   * data if @p v contains some, but
-   * does not do so if @p v is empty
-   * or has its data swapped
-   * out. In the latter case, warn
-   * about that. In particular do
-   * not take over ownership of any
-   * files that @p v might own.
+   * Copy constructor. Copies the data if @p v contains some, but does not do
+   * so if @p v is empty or has its data swapped out. In the latter case, warn
+   * about that. In particular do not take over ownership of any files that @p
+   * v might own.
    */
   SwappableVector (const SwappableVector &v);
 
   /**
-   * Destructor. If this class
-   * still owns a file to which
-   * temporary data was stored,
-   * then it is deleted.
+   * Destructor. If this class still owns a file to which temporary data was
+   * stored, then it is deleted.
    */
   virtual ~SwappableVector ();
 
   /**
-   * Copy operator. Do mostly the
-   * same as the copy constructor
-   * does; if necessary, delete
-   * temporary files owned by this
-   * object at first.
+   * Copy operator. Do mostly the same as the copy constructor does; if
+   * necessary, delete temporary files owned by this object at first.
    */
   SwappableVector &operator = (const SwappableVector &);
 
   /**
-   * Swap out the data of this
-   * vector to the file of which
-   * the name is given. It is
-   * assumed that the file can be
-   * overwritten if it exists, and
-   * ownership of this file is
-   * assumed by this object. The
-   * file is deleted either upon
-   * calling @p kill_file, or on
-   * destruction of this object.
+   * Swap out the data of this vector to the file of which the name is given.
+   * It is assumed that the file can be overwritten if it exists, and
+   * ownership of this file is assumed by this object. The file is deleted
+   * either upon calling @p kill_file, or on destruction of this object.
    *
-   * The content of the vector is
-   * cleared and it size is reset
-   * to zero.
+   * The content of the vector is cleared and it size is reset to zero.
    *
-   * If this object owns another
-   * file, for example when
-   * @p swap_out but no @p kill_file
-   * has previously been called,
-   * then that is deleted first.
+   * If this object owns another file, for example when @p swap_out but no @p
+   * kill_file has previously been called, then that is deleted first.
    */
   void swap_out (const std::string &filename);
 
   /**
-   * Reload the data of this vector
-   * from the file to which it has
-   * been stored previously using
-   * @p swap_out. Since the file is
-   * not deleted after reloading,
-   * you can call @p reload multiple
-   * times, in between you may do
-   * everything with the vector,
-   * including changing its size.
+   * Reload the data of this vector from the file to which it has been stored
+   * previously using @p swap_out. Since the file is not deleted after
+   * reloading, you can call @p reload multiple times, in between you may do
+   * everything with the vector, including changing its size.
    *
-   * This function resets the size
-   * of the vector to the number of
-   * elements there were upon
-   * calling @p swap_out before.
+   * This function resets the size of the vector to the number of elements
+   * there were upon calling @p swap_out before.
    */
   void reload ();
 
   /**
-   * Calling this function can be
-   * used to alert this vector that
-   * it will need to reload its
-   * data soon. It has no effect if
-   * the data of the vector is
-   * already present, and it has no
-   * effect in single-thread mode
-   * as well, but in multithread
-   * mode, it spawns another thread
-   * that reads the data in
-   * parallel to the usual
-   * execution of the program, such
-   * that when @p reload is called,
-   * the data may eventually be
-   * available already. It might
-   * therefore be wirthwhile to
-   * call this function some time
-   * in advance, if you know that
-   * the data will be needed, and
-   * loading takes some time, for
-   * instance if the file to which
-   * the data was written is not in
-   * a local tmp directory.
+   * Calling this function can be used to alert this vector that it will need
+   * to reload its data soon. It has no effect if the data of the vector is
+   * already present, and it has no effect in single-thread mode as well, but
+   * in multithread mode, it spawns another thread that reads the data in
+   * parallel to the usual execution of the program, such that when @p reload
+   * is called, the data may eventually be available already. It might
+   * therefore be wirthwhile to call this function some time in advance, if
+   * you know that the data will be needed, and loading takes some time, for
+   * instance if the file to which the data was written is not in a local tmp
+   * directory.
    *
-   * Calling this function multiple
-   * times before calling @p reload
-   * is allowed and has no effect
-   * for subsequent calls. Calling
-   * this function while the data
-   * is still or already in memory
-   * is allowed and has no effect.
+   * Calling this function multiple times before calling @p reload is allowed
+   * and has no effect for subsequent calls. Calling this function while the
+   * data is still or already in memory is allowed and has no effect.
    */
   void alert ();
 
 
   /**
-   * Remove the file to which the
-   * data has been stored the last
-   * time. After this, the object
-   * does not own any file any
-   * more, so of course you can't
+   * Remove the file to which the data has been stored the last time. After
+   * this, the object does not own any file any more, so of course you can't
    * call @p reload no more.
    *
-   * If this object does not own a
-   * file, for example since
-   * @p swap_out was not called, or
-   * because @p kill_file has been
-   * called previously, then this
+   * If this object does not own a file, for example since @p swap_out was not
+   * called, or because @p kill_file has been called previously, then this
    * function does nothing.
    */
   void kill_file ();
 
   /**
-   * Return the name of the file to
-   * which the data was stored the
-   * last time you called
-   * @p swap_out. If @p swap_out was
-   * not called, or if in between
-   * @p kill_file was called, then
-   * the filename is an empty
-   * string.
+   * Return the name of the file to which the data was stored the last time
+   * you called @p swap_out. If @p swap_out was not called, or if in between
+   * @p kill_file was called, then the filename is an empty string.
    */
   const std::string &get_filename () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
   /**
    * Exception.
    */
@@ -231,57 +173,36 @@ public:
   //@}
 private:
   /**
-   * Name of the file to which data
-   * was swapped out. If no data is
-   * presently swapped out
-   * (i.e. before calling
-   * @p swap_out and after
-   * @p kill_file), the string is
-   * empty, indicating no ownership
-   * of files.
+   * Name of the file to which data was swapped out. If no data is presently
+   * swapped out (i.e. before calling @p swap_out and after @p kill_file), the
+   * string is empty, indicating no ownership of files.
    */
   std::string filename;
 
   /**
-   * If in multithread mode, then
-   * the @p alert function has
-   * functionality, but needs to
-   * coordinate with the @p reload
-   * function. This is done through
-   * the following lock.
+   * If in multithread mode, then the @p alert function has functionality, but
+   * needs to coordinate with the @p reload function. This is done through the
+   * following lock.
    *
-   * If not in MT mode, then the
-   * class used here is empty, and
-   * we can as well get away
-   * with it.
+   * If not in MT mode, then the class used here is empty, and we can as well
+   * get away with it.
    */
   Threads::Mutex lock;
 
   /**
-   * Flag by which the @p alert
-   * function signifies that the
-   * data has been preloaded
-   * already. This flag is always
-   * @p false in non-MT mode.
+   * Flag by which the @p alert function signifies that the data has been
+   * preloaded already. This flag is always @p false in non-MT mode.
    */
   bool data_is_preloaded;
 
   /**
-   * Internal function that
-   * actually reloads the
-   * vector. Called from @p reload
+   * Internal function that actually reloads the vector. Called from @p reload
    * and @p alert.
    *
-   * The parameter specifies
-   * whether the function shall set
-   * @p data_is_preloaded or
-   * not. The calling functions
-   * can't sometimes do this
-   * themselves, since they call
-   * this function detached, so
-   * this function has to signal
-   * success itself if this is
-   * required.
+   * The parameter specifies whether the function shall set @p
+   * data_is_preloaded or not. The calling functions can't sometimes do this
+   * themselves, since they call this function detached, so this function has
+   * to signal success itself if this is required.
    */
   void reload_vector (const bool set_flag);
 };
index fe7b0e618cc4a603f0d999fca42ab5bc4714fed8..24d9e821ac9516b782aa6af1d18c796f09e47689 100644 (file)
@@ -24,15 +24,13 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * The transpose of a given matrix.  This auxiliary class swaps the
- * effect ov vmult() and Tvmult() as well as vmult_add() and
- * Tvmult_add().
+ * The transpose of a given matrix.  This auxiliary class swaps the effect ov
+ * vmult() and Tvmult() as well as vmult_add() and Tvmult_add().
  *
  * The implementation is analogous to the class PointerMatrix.
  *
- * @note The transposed matrix is never actually assembled. Instead,
- * only the matrix vector multiplication is performed in a transposed
- * way.
+ * @note The transposed matrix is never actually assembled. Instead, only the
+ * matrix vector multiplication is performed in a transposed way.
  *
  * @ingroup Matrix2
  * @author Guido Kanschat, 2006
@@ -43,32 +41,24 @@ class
 {
 public:
   /**
-   * Constructor.  The pointer in the
-   * argument is stored in this
-   * class. As usual, the lifetime of
-   * <tt>*M</tt> must be longer than the
-   * one of the PointerMatrix.
+   * Constructor.  The pointer in the argument is stored in this class. As
+   * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+   * PointerMatrix.
    *
-   * If <tt>M</tt> is zero, no
-   * matrix is stored.
+   * If <tt>M</tt> is zero, no matrix is stored.
    */
   TransposeMatrix (const MATRIX *M=0);
 
   /**
-   * Constructor. The name argument
-   * is used to identify the
-   * SmartPointer for this object.
+   * Constructor. The name argument is used to identify the SmartPointer for
+   * this object.
    */
   TransposeMatrix(const char *name);
 
   /**
-   * Constructor. <tt>M</tt> points
-   * to a matrix which must live
-   * longer than the
-   * TransposeMatrix. The name
-   * argument is used to identify
-   * the SmartPointer for this
-   * object.
+   * Constructor. <tt>M</tt> points to a matrix which must live longer than
+   * the TransposeMatrix. The name argument is used to identify the
+   * SmartPointer for this object.
    */
   TransposeMatrix(const MATRIX *M,
                   const char *name);
@@ -77,16 +67,13 @@ public:
   virtual void clear();
 
   /**
-   * Return whether the object is
-   * empty.
+   * Return whether the object is empty.
    */
   bool empty () const;
 
   /**
-   * Assign a new matrix
-   * pointer. Deletes the old pointer
-   * and releases its matrix.
-   * @see SmartPointer
+   * Assign a new matrix pointer. Deletes the old pointer and releases its
+   * matrix. @see SmartPointer
    */
   const TransposeMatrix &operator= (const MATRIX *M);
 
@@ -103,15 +90,13 @@ public:
                        const VECTOR &src) const;
 
   /**
-   * Matrix-vector product, adding to
-   * <tt>dst</tt>.
+   * Matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void vmult_add (VECTOR &dst,
                           const VECTOR &src) const;
 
   /**
-   * Tranposed matrix-vector product,
-   * adding to <tt>dst</tt>.
+   * Tranposed matrix-vector product, adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
                            const VECTOR &src) const;
index f2c55e8462e86e5ed35f8fa79fb404ee20318020..158560d6c83b6c3dc46a9790501b467ff88289d0 100644 (file)
@@ -35,16 +35,16 @@ template<typename number> class Vector;
 
 
 /**
- * A quadratic tridiagonal matrix. That is, a matrix where all entries
- * are zero, except the diagonal and the entries left and right of it.
+ * A quadratic tridiagonal matrix. That is, a matrix where all entries are
+ * zero, except the diagonal and the entries left and right of it.
  *
- * The matrix has an additional symmetric mode, in which case only the
- * upper triangle of the matrix is stored and mirrored to the lower
- * one for matrix vector operations.
+ * The matrix has an additional symmetric mode, in which case only the upper
+ * triangle of the matrix is stored and mirrored to the lower one for matrix
+ * vector operations.
  *
  * @ingroup Matrix1
  * @author Guido Kanschat, 2005, 2006
-*/
+ */
 template<typename number>
 class TridiagonalMatrix
 {
@@ -60,18 +60,14 @@ public:
    * @name Constructors and initalization.
    */
   /**
-   * Constructor generating an
-   * empty matrix of dimension
-   * <tt>n</tt>.
+   * Constructor generating an empty matrix of dimension <tt>n</tt>.
    */
   TridiagonalMatrix(size_type    n = 0,
                     bool symmetric = false);
 
   /**
-   * Reinitialize the matrix to a
-   * new size and reset all entries
-   * to zero. The symmetry
-   * properties may be set as well.
+   * Reinitialize the matrix to a new size and reset all entries to zero. The
+   * symmetry properties may be set as well.
    */
   void reinit(size_type n,
               bool symmetric = false);
@@ -82,28 +78,21 @@ public:
 //@{
 
   /**
-   * Number of rows of this matrix.
-   * To remember: this matrix is an
-   * <i>m x m</i>-matrix.
+   * Number of rows of this matrix. To remember: this matrix is an <i>m x
+   * m</i>-matrix.
    */
   size_type m () const;
 
   /**
-   * Number of columns of this matrix.
-   * To remember: this matrix is an
-   * <i>n x n</i>-matrix.
+   * Number of columns of this matrix. To remember: this matrix is an <i>n x
+   * n</i>-matrix.
    */
   size_type n () const;
 
   /**
-   * Return whether the matrix
-   * contains only elements with
-   * value zero. This function is
-   * mainly for internal
-   * consistency checks and should
-   * seldom be used when not in
-   * debug mode since it uses quite
-   * some time.
+   * Return whether the matrix contains only elements with value zero. This
+   * function is mainly for internal consistency checks and should seldom be
+   * used when not in debug mode since it uses quite some time.
    */
   bool all_zero () const;
 
@@ -113,27 +102,19 @@ public:
 ///@name Element access
 //@{
   /**
-   * Read-only access to a
-   * value. This is restricted to
-   * the case where <i>|i-j| <=
-   * 1</i>.
+   * Read-only access to a value. This is restricted to the case where
+   * <i>|i-j| <= 1</i>.
    */
   number operator()(size_type i, size_type j) const;
 
   /**
-   * Read-write access to a
-   * value. This is restricted to
-   * the case where <i>|i-j| <=
-   * 1</i>.
+   * Read-write access to a value. This is restricted to the case where
+   * <i>|i-j| <= 1</i>.
    *
-   * @note In case of symmetric
-   * storage technique, the entries
-   * <i>(i,j)</i> and <i>(j,i)</i>
-   * are identified and <b>both</b>
-   * exist. This must be taken into
-   * account if adding up is used
-   * for matrix assembling in order
-   * not to obtain doubled entries.
+   * @note In case of symmetric storage technique, the entries <i>(i,j)</i>
+   * and <i>(j,i)</i> are identified and <b>both</b> exist. This must be taken
+   * into account if adding up is used for matrix assembling in order not to
+   * obtain doubled entries.
    */
   number &operator()(size_type i, size_type j);
 
@@ -142,97 +123,66 @@ public:
 //@{
 
   /**
-   * Matrix-vector-multiplication. Multiplies
-   * <tt>v</tt> from the right and
-   * stores the result in
-   * <tt>w</tt>.
+   * Matrix-vector-multiplication. Multiplies <tt>v</tt> from the right and
+   * stores the result in <tt>w</tt>.
    *
-   * If the optional parameter
-   * <tt>adding</tt> is <tt>true</tt>, the
-   * result is added to <tt>w</tt>.
+   * If the optional parameter <tt>adding</tt> is <tt>true</tt>, the result is
+   * added to <tt>w</tt>.
    *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   void vmult (Vector<number>       &w,
               const Vector<number> &v,
               const bool            adding=false) const;
 
   /**
-   * Adding
-   * Matrix-vector-multiplication. Same
-   * as vmult() with parameter
-   * <tt>adding=true</tt>, but
-   * widely used in
-   * <tt>deal.II</tt> classes.
+   * Adding Matrix-vector-multiplication. Same as vmult() with parameter
+   * <tt>adding=true</tt>, but widely used in <tt>deal.II</tt> classes.
    *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   void vmult_add (Vector<number>       &w,
                   const Vector<number> &v) const;
 
   /**
-   * Transpose
-   * matrix-vector-multiplication.
-   * Multiplies
-   * <tt>v<sup>T</sup></tt> from
-   * the left and stores the result
-   * in <tt>w</tt>.
+   * Transpose matrix-vector-multiplication. Multiplies <tt>v<sup>T</sup></tt>
+   * from the left and stores the result in <tt>w</tt>.
    *
-   * If the optional parameter
-   * <tt>adding</tt> is <tt>true</tt>, the
-   * result is added to <tt>w</tt>.
+   * If the optional parameter <tt>adding</tt> is <tt>true</tt>, the result is
+   * added to <tt>w</tt>.
    *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   void Tvmult (Vector<number>       &w,
                const Vector<number> &v,
                const bool            adding=false) const;
 
   /**
-   * Adding transpose
-   * matrix-vector-multiplication. Same
-   * as Tvmult() with parameter
-   * <tt>adding=true</tt>, but
-   * widely used in
-   * <tt>deal.II</tt> classes.
+   * Adding transpose matrix-vector-multiplication. Same as Tvmult() with
+   * parameter <tt>adding=true</tt>, but widely used in <tt>deal.II</tt>
+   * classes.
    *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   void Tvmult_add (Vector<number>       &w,
                    const Vector<number> &v) const;
 
   /**
-   * Build the matrix scalar product
-   * <tt>u^T M v</tt>. This function is mostly
-   * useful when building the cellwise
-   * scalar product of two functions in
-   * the finite element context.
+   * Build the matrix scalar product <tt>u^T M v</tt>. This function is mostly
+   * useful when building the cellwise scalar product of two functions in the
+   * finite element context.
    */
   number matrix_scalar_product (const Vector<number> &u,
                                 const Vector<number> &v) const;
 
   /**
-   * Return the square of the norm
-   * of the vector <tt>v</tt> with
-   * respect to the norm induced by
-   * this matrix,
-   * i.e. <i>(v,Mv)</i>. This is
-   * useful, e.g. in the finite
-   * element context, where the
-   * <i>L<sup>2</sup></i> norm of a
-   * function equals the matrix
-   * norm with respect to the mass
-   * matrix of the vector
-   * representing the nodal values
-   * of the finite element
-   * function.
+   * Return the square of the norm of the vector <tt>v</tt> with respect to
+   * the norm induced by this matrix, i.e. <i>(v,Mv)</i>. This is useful, e.g.
+   * in the finite element context, where the <i>L<sup>2</sup></i> norm of a
+   * function equals the matrix norm with respect to the mass matrix of the
+   * vector representing the nodal values of the finite element function.
    *
-   * Obviously, the matrix needs to
-   * be quadratic for this operation.
+   * Obviously, the matrix needs to be quadratic for this operation.
    */
   number matrix_norm_square (const Vector<number> &v) const;
 
@@ -241,77 +191,55 @@ public:
 //@{
 
   /**
-   * Return the $l_1$-norm of the matrix, i.e.
-   * $|M|_1=max_{all columns j}\sum_{all
-   * rows i} |M_ij|$,
-   * (max. sum of columns). This is the
-   * natural matrix norm that is compatible
-   * to the $l_1$-norm for vectors, i.e.
-   * $|Mv|_1\leq |M|_1 |v|_1$.
-   * (cf. Rannacher Numerik0)
+   * Return the $l_1$-norm of the matrix, i.e. $|M|_1=max_{all columns
+   * j}\sum_{all rows i} |M_ij|$, (max. sum of columns). This is the natural
+   * matrix norm that is compatible to the $l_1$-norm for vectors, i.e.
+   * $|Mv|_1\leq |M|_1 |v|_1$. (cf. Rannacher Numerik0)
    */
   number l1_norm () const;
 
   /**
-   * Return the $l_\infty$-norm of the
-   * matrix, i.e.
-   * $|M|_\infty=\max_{all rows i}\sum_{all
-   * columns j} |M_{ij}|$,
-   * (max. sum of rows).
-   * This is the
-   * natural matrix norm that is compatible
-   * to the $l_\infty$-norm of vectors, i.e.
+   * Return the $l_\infty$-norm of the matrix, i.e. $|M|_\infty=\max_{all rows
+   * i}\sum_{all columns j} |M_{ij}|$, (max. sum of rows). This is the natural
+   * matrix norm that is compatible to the $l_\infty$-norm of vectors, i.e.
    * $|Mv|_\infty \leq |M|_\infty |v|_\infty$.
    */
   number linfty_norm () const;
 
   /**
-   * The Frobenius norm of the matrix.
-   * Return value is the root of the square
+   * The Frobenius norm of the matrix. Return value is the root of the square
    * sum of all matrix entries.
    */
   number frobenius_norm () const;
 
   /**
-   * Compute the relative norm of
-   * the skew-symmetric part. The
-   * return value is the Frobenius
-   * norm of the skew-symmetric
-   * part of the matrix divided by
+   * Compute the relative norm of the skew-symmetric part. The return value is
+   * the Frobenius norm of the skew-symmetric part of the matrix divided by
    * that of the matrix.
    *
-   * Main purpose of this function
-   * is to check, if a matrix is
-   * symmetric within a certain
-   * accuracy, or not.
+   * Main purpose of this function is to check, if a matrix is symmetric
+   * within a certain accuracy, or not.
    */
   number relative_symmetry_norm2 () const;
 //@}
 ///@name LAPACK operations
 //@{
   /**
-   * Compute the eigenvalues of the
-   * symmetric tridiagonal matrix.
+   * Compute the eigenvalues of the symmetric tridiagonal matrix.
    *
-   * @note This function requires
-   * configuration of deal.II with
-   * LAPACK support. Additionally,
-   * the matrix must use symmetric
-   * storage technique.
+   * @note This function requires configuration of deal.II with LAPACK
+   * support. Additionally, the matrix must use symmetric storage technique.
    */
   void compute_eigenvalues();
   /**
-   * After calling
-   * compute_eigenvalues(), you can
-   * access each eigenvalue here.
+   * After calling compute_eigenvalues(), you can access each eigenvalue here.
    */
   number eigenvalue(const size_type i) const;
 //@}
 ///@name Miscellanea
 //@{
   /**
-   * Output of the matrix in
-   * user-defined format.
+   * Output of the matrix in user-defined format.
    */
   template <class OUT>
   void print (OUT &s,
@@ -319,9 +247,8 @@ public:
               const unsigned int  precision=2) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
   //@}
@@ -332,50 +259,33 @@ private:
    */
   std::vector<number> diagonal;
   /**
-   * The entries left of the
-   * diagonal. The entry with index
-   * zero is always zero, since the
-   * first row has no entry left of
-   * the diagonal. Therefore, the
-   * length of this vector is the
-   * same as that of #diagonal.
+   * The entries left of the diagonal. The entry with index zero is always
+   * zero, since the first row has no entry left of the diagonal. Therefore,
+   * the length of this vector is the same as that of #diagonal.
    *
-   * The length of this vector is
-   * zero for symmetric storage. In
-   * this case, the second element
-   * of #left is identified with
-   * the first element of #right.
+   * The length of this vector is zero for symmetric storage. In this case,
+   * the second element of #left is identified with the first element of
+   * #right.
    */
   std::vector<number> left;
   /**
-   * The entries right of the
-   * diagonal. The last entry is
-   * always zero, since the last
-   * row has no entry right of the
-   * diagonal. Therefore, the
-   * length of this vector is the
-   * same as that of #diagonal.
+   * The entries right of the diagonal. The last entry is always zero, since
+   * the last row has no entry right of the diagonal. Therefore, the length of
+   * this vector is the same as that of #diagonal.
    */
   std::vector<number> right;
 
   /**
-   * If this flag is true, only the
-   * entries to the right of the
-   * diagonal are stored and the
-   * matrix is assumed symmetric.
+   * If this flag is true, only the entries to the right of the diagonal are
+   * stored and the matrix is assumed symmetric.
    */
   bool is_symmetric;
 
   /**
-   * The state of the
-   * matrix. Normally, the state is
-   * LAPACKSupport::matrix,
-   * indicating that the object can
-   * be used for regular matrix
-   * operations.
+   * The state of the matrix. Normally, the state is LAPACKSupport::matrix,
+   * indicating that the object can be used for regular matrix operations.
    *
-   * See explanation of this data
-   * type for details.
+   * See explanation of this data type for details.
    */
   LAPACKSupport::State state;
 };
index a47665a74347dfb284ad739c1a2f9dabc084697c..347b84db90dbb2f166652dd0440e72bba1d3c768 100644 (file)
@@ -51,45 +51,42 @@ namespace TrilinosWrappers
    */
 
   /**
-   * Blocked sparse matrix based on the TrilinosWrappers::SparseMatrix class. This
-   * class implements the functions that are specific to the Trilinos SparseMatrix
-   * base objects for a blocked sparse matrix, and leaves the actual work
-   * relaying most of the calls to the individual blocks to the functions
-   * implemented in the base class. See there also for a description of when
-   * this class is useful.
+   * Blocked sparse matrix based on the TrilinosWrappers::SparseMatrix class.
+   * This class implements the functions that are specific to the Trilinos
+   * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+   * actual work relaying most of the calls to the individual blocks to the
+   * functions implemented in the base class. See there also for a description
+   * of when this class is useful.
    *
-   * In contrast to the deal.II-type SparseMatrix class, the Trilinos matrices do
-   * not have external objects for the sparsity patterns. Thus, one does not
-   * determine the size of the individual blocks of a block matrix of this type
-   * by attaching a block sparsity pattern, but by calling reinit() to set the
-   * number of blocks and then by setting the size of each block separately. In
-   * order to fix the data structures of the block matrix, it is then necessary
-   * to let it know that we have changed the sizes of the underlying
-   * matrices. For this, one has to call the collect_sizes() function, for much
-   * the same reason as is documented with the BlockSparsityPattern class.
+   * In contrast to the deal.II-type SparseMatrix class, the Trilinos matrices
+   * do not have external objects for the sparsity patterns. Thus, one does
+   * not determine the size of the individual blocks of a block matrix of this
+   * type by attaching a block sparsity pattern, but by calling reinit() to
+   * set the number of blocks and then by setting the size of each block
+   * separately. In order to fix the data structures of the block matrix, it
+   * is then necessary to let it know that we have changed the sizes of the
+   * underlying matrices. For this, one has to call the collect_sizes()
+   * function, for much the same reason as is documented with the
+   * BlockSparsityPattern class.
    *
-   * @ingroup Matrix1
-   * @see @ref GlossBlockLA "Block (linear algebra)"
+   * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
    * @author Martin Kronbichler, Wolfgang Bangerth, 2008
    */
   class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix>
   {
   public:
     /**
-     * Typedef the base class for simpler
-     * access to its own typedefs.
+     * Typedef the base class for simpler access to its own typedefs.
      */
     typedef BlockMatrixBase<SparseMatrix> BaseClass;
 
     /**
-     * Typedef the type of the underlying
-     * matrix.
+     * Typedef the type of the underlying matrix.
      */
     typedef BaseClass::BlockType  BlockType;
 
     /**
-     * Import the typedefs from the base
-     * class.
+     * Import the typedefs from the base class.
      */
     typedef BaseClass::value_type      value_type;
     typedef BaseClass::pointer         pointer;
@@ -101,25 +98,15 @@ namespace TrilinosWrappers
     typedef BaseClass::const_iterator  const_iterator;
 
     /**
-     * Constructor; initializes the
-     * matrix to be empty, without
-     * any structure, i.e.  the
-     * matrix is not usable at
-     * all. This constructor is
-     * therefore only useful for
-     * matrices which are members of
-     * a class. All other matrices
-     * should be created at a point
-     * in the data flow where all
-     * necessary information is
-     * available.
+     * Constructor; initializes the matrix to be empty, without any structure,
+     * i.e.  the matrix is not usable at all. This constructor is therefore
+     * only useful for matrices which are members of a class. All other
+     * matrices should be created at a point in the data flow where all
+     * necessary information is available.
      *
-     * You have to initialize the
-     * matrix before usage with
-     * reinit(BlockSparsityPattern). The
-     * number of blocks per row and
-     * column are then determined by
-     * that function.
+     * You have to initialize the matrix before usage with
+     * reinit(BlockSparsityPattern). The number of blocks per row and column
+     * are then determined by that function.
      */
     BlockSparseMatrix ();
 
@@ -129,67 +116,44 @@ namespace TrilinosWrappers
     ~BlockSparseMatrix ();
 
     /**
-     * Pseudo copy operator only copying
-     * empty objects. The sizes of the block
+     * Pseudo copy operator only copying empty objects. The sizes of the block
      * matrices need to be the same.
      */
     BlockSparseMatrix &
     operator = (const BlockSparseMatrix &);
 
     /**
-     * This operator assigns a scalar to a
-     * matrix. Since this does usually not
-     * make much sense (should we set all
-     * matrix entries to this value? Only
-     * the nonzero entries of the sparsity
-     * pattern?), this operation is only
-     * allowed if the actual value to be
-     * assigned is zero. This operator only
-     * exists to allow for the obvious
-     * notation <tt>matrix=0</tt>, which
-     * sets all elements of the matrix to
-     * zero, but keep the sparsity pattern
+     * This operator assigns a scalar to a matrix. Since this does usually not
+     * make much sense (should we set all matrix entries to this value? Only
+     * the nonzero entries of the sparsity pattern?), this operation is only
+     * allowed if the actual value to be assigned is zero. This operator only
+     * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+     * all elements of the matrix to zero, but keep the sparsity pattern
      * previously used.
      */
     BlockSparseMatrix &
     operator = (const double d);
 
     /**
-     * Resize the matrix, by setting
-     * the number of block rows and
-     * columns. This deletes all
-     * blocks and replaces them by
-     * unitialized ones, i.e. ones
-     * for which also the sizes are
-     * not yet set. You have to do
-     * that by calling the @p reinit
-     * functions of the blocks
-     * themselves. Do not forget to
-     * call collect_sizes() after
-     * that on this object.
+     * Resize the matrix, by setting the number of block rows and columns.
+     * This deletes all blocks and replaces them by unitialized ones, i.e.
+     * ones for which also the sizes are not yet set. You have to do that by
+     * calling the @p reinit functions of the blocks themselves. Do not forget
+     * to call collect_sizes() after that on this object.
      *
-     * The reason that you have to
-     * set sizes of the blocks
-     * yourself is that the sizes may
-     * be varying, the maximum number
-     * of elements per row may be
-     * varying, etc. It is simpler
-     * not to reproduce the interface
-     * of the @p SparsityPattern
-     * class here but rather let the
-     * user call whatever function
-     * she desires.
+     * The reason that you have to set sizes of the blocks yourself is that
+     * the sizes may be varying, the maximum number of elements per row may be
+     * varying, etc. It is simpler not to reproduce the interface of the @p
+     * SparsityPattern class here but rather let the user call whatever
+     * function she desires.
      */
     void reinit (const size_type n_block_rows,
                  const size_type n_block_columns);
 
     /**
-     * Resize the matrix, by using an
-     * array of Epetra maps to determine
-     * the %parallel distribution of the
-     * individual matrices. This function
-     * assumes that a quadratic block
-     * matrix is generated.
+     * Resize the matrix, by using an array of Epetra maps to determine the
+     * %parallel distribution of the individual matrices. This function
+     * assumes that a quadratic block matrix is generated.
      */
     template <typename BlockSparsityType>
     void reinit (const std::vector<Epetra_Map> &input_maps,
@@ -197,12 +161,9 @@ namespace TrilinosWrappers
                  const bool                   exchange_data = false);
 
     /**
-     * Resize the matrix, by using an
-     * array of index sets to determine
-     * the %parallel distribution of the
-     * individual matrices. This function
-     * assumes that a quadratic block
-     * matrix is generated.
+     * Resize the matrix, by using an array of index sets to determine the
+     * %parallel distribution of the individual matrices. This function
+     * assumes that a quadratic block matrix is generated.
      */
     template <typename BlockSparsityType>
     void reinit (const std::vector<IndexSet> &input_maps,
@@ -211,90 +172,56 @@ namespace TrilinosWrappers
                  const bool                   exchange_data = false);
 
     /**
-     * Resize the matrix and initialize it
-     * by the given sparsity pattern. Since
-     * no distribution map is given, the
-     * result is a block matrix for which
-     * all elements are stored locally.
+     * Resize the matrix and initialize it by the given sparsity pattern.
+     * Since no distribution map is given, the result is a block matrix for
+     * which all elements are stored locally.
      */
     template <typename BlockSparsityType>
     void reinit (const BlockSparsityType &block_sparsity_pattern);
 
     /**
-     * This function initializes the
-     * Trilinos matrix using the deal.II
-     * sparse matrix and the entries stored
-     * therein. It uses a threshold
-     * to copy only elements whose
-     * modulus is larger than the
-     * threshold (so zeros in the
-     * deal.II matrix can be filtered
-     * away).
+     * This function initializes the Trilinos matrix using the deal.II sparse
+     * matrix and the entries stored therein. It uses a threshold to copy only
+     * elements whose modulus is larger than the threshold (so zeros in the
+     * deal.II matrix can be filtered away).
      */
     void reinit (const std::vector<Epetra_Map>             &input_maps,
                  const ::dealii::BlockSparseMatrix<double> &deal_ii_sparse_matrix,
                  const double                               drop_tolerance=1e-13);
 
     /**
-     * This function initializes
-     * the Trilinos matrix using
-     * the deal.II sparse matrix
-     * and the entries stored
-     * therein. It uses a threshold
-     * to copy only elements whose
-     * modulus is larger than the
-     * threshold (so zeros in the
-     * deal.II matrix can be
-     * filtered away). Since no
-     * Epetra_Map is given, all the
-     * elements will be locally
-     * stored.
+     * This function initializes the Trilinos matrix using the deal.II sparse
+     * matrix and the entries stored therein. It uses a threshold to copy only
+     * elements whose modulus is larger than the threshold (so zeros in the
+     * deal.II matrix can be filtered away). Since no Epetra_Map is given, all
+     * the elements will be locally stored.
      */
     void reinit (const ::dealii::BlockSparseMatrix<double> &deal_ii_sparse_matrix,
                  const double                               drop_tolerance=1e-13);
 
     /**
-     * Returns the state of the
-     * matrix, i.e., whether
-     * compress() needs to be called
-     * after an operation requiring
-     * data exchange. Does only
-     * return non-true values when
-     * used in <tt>debug</tt> mode,
-     * since it is quite expensive to
-     * keep track of all operations
-     * that lead to the need for
+     * Returns the state of the matrix, i.e., whether compress() needs to be
+     * called after an operation requiring data exchange. Does only return
+     * non-true values when used in <tt>debug</tt> mode, since it is quite
+     * expensive to keep track of all operations that lead to the need for
      * compress().
      */
     bool is_compressed () const;
 
     /**
-     * This function collects the
-     * sizes of the sub-objects and
-     * stores them in internal
-     * arrays, in order to be able to
-     * relay global indices into the
-     * matrix to indices into the
-     * subobjects. You *must* call
-     * this function each time after
-     * you have changed the size of
-     * the sub-objects. Note that
-     * this is a collective
-     * operation, i.e., it needs to
-     * be called on all MPI
-     * processes. This command
-     * internally calls the method
-     * <tt>compress()</tt>, so you
-     * don't need to call that
-     * function in case you use
-     * <tt>collect_sizes()</tt>.
+     * This function collects the sizes of the sub-objects and stores them in
+     * internal arrays, in order to be able to relay global indices into the
+     * matrix to indices into the subobjects. You *must* call this function
+     * each time after you have changed the size of the sub-objects. Note that
+     * this is a collective operation, i.e., it needs to be called on all MPI
+     * processes. This command internally calls the method
+     * <tt>compress()</tt>, so you don't need to call that function in case
+     * you use <tt>collect_sizes()</tt>.
      */
     void collect_sizes ();
 
     /**
-     * Return the number of nonzero
-     * elements of this
-     * matrix.
+     * Return the number of nonzero elements of this matrix.
      */
     size_type n_nonzero_elements () const;
 
@@ -318,161 +245,102 @@ namespace TrilinosWrappers
                  const VectorType2 &src) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned.
      *
-     * Source <i>x</i> and
-     * destination <i>dst</i> must
-     * not be the same vector.
+     * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
      *
-     * Note that both vectors have
-     * to be distributed vectors
-     * generated using the same Map
-     * as was used for the matrix
-     * in case you work on a
-     * distributed memory
-     * architecture, using the
-     * interface in the
-     * TrilinosWrappers::MPI::BlockVector
-     * class.
+     * Note that both vectors have to be distributed vectors generated using
+     * the same Map as was used for the matrix in case you work on a
+     * distributed memory architecture, using the interface in the
+     * TrilinosWrappers::MPI::BlockVector class.
      */
     TrilinosScalar residual (MPI::BlockVector       &dst,
                              const MPI::BlockVector &x,
                              const MPI::BlockVector &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned.
      *
-     * Source <i>x</i> and
-     * destination <i>dst</i> must
-     * not be the same vector.
+     * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
      *
-     * Note that both vectors have
-     * to be distributed vectors
-     * generated using the same Map
-     * as was used for the matrix
-     * in case you work on a
-     * distributed memory
-     * architecture, using the
-     * interface in the
-     * TrilinosWrappers::BlockVector
-     * class. Since the block
-     * matrix is in general
-     * distributed among processes,
-     * this function only works
-     * when running the program on
-     * one processor.
+     * Note that both vectors have to be distributed vectors generated using
+     * the same Map as was used for the matrix in case you work on a
+     * distributed memory architecture, using the interface in the
+     * TrilinosWrappers::BlockVector class. Since the block matrix is in
+     * general distributed among processes, this function only works when
+     * running the program on one processor.
      */
     TrilinosScalar residual (BlockVector       &dst,
                              const BlockVector &x,
                              const BlockVector &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned. Just like the
-     * previous function, but only
-     * applicable if the matrix
-     * only has one block row.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+     * the previous function, but only applicable if the matrix only has one
+     * block row.
      */
     TrilinosScalar residual (MPI::BlockVector       &dst,
                              const MPI::Vector      &x,
                              const MPI::BlockVector &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned. Just like the
-     * previous function, but only
-     * applicable if the matrix
-     * only has one block row.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+     * the previous function, but only applicable if the matrix only has one
+     * block row.
      */
     TrilinosScalar residual (BlockVector       &dst,
                              const Vector      &x,
                              const BlockVector &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned. Just like the
-     * previous function, but only
-     * applicable if the matrix
-     * only has one block column.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+     * the previous function, but only applicable if the matrix only has one
+     * block column.
      */
     TrilinosScalar residual (MPI::Vector            &dst,
                              const MPI::BlockVector &x,
                              const MPI::Vector      &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned. Just like the
-     * previous function, but only
-     * applicable if the matrix
-     * only has one block column.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+     * the previous function, but only applicable if the matrix only has one
+     * block column.
      */
     TrilinosScalar residual (Vector            &dst,
                              const BlockVector &x,
                              const Vector      &b) const;
 
     /**
-     * Compute the residual of an
-     * equation <i>Mx=b</i>, where
-     * the residual is defined to
-     * be <i>r=b-Mx</i>. Write the
-     * residual into @p dst. The
-     * <i>l<sub>2</sub></i> norm of
-     * the residual vector is
-     * returned. Just like the
-     * previous function, but only
-     * applicable if the matrix
-     * only has one block.
+     * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+     * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+     * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+     * the previous function, but only applicable if the matrix only has one
+     * block.
      */
     TrilinosScalar residual (VectorBase       &dst,
                              const VectorBase &x,
                              const VectorBase &b) const;
 
     /**
-     * Make the clear() function in the
-     * base class visible, though it is
+     * Make the clear() function in the base class visible, though it is
      * protected.
      */
     using BlockMatrixBase<SparseMatrix>::clear;
 
-    /** @addtogroup Exceptions
+    /**
+     * @addtogroup Exceptions
      * @{
      */
 
index 225b472d07983c2a581c99b1b9ec1b254b8b9e5b..1422247e697e4a16f513a76154d7a116753d1d20 100644 (file)
@@ -48,22 +48,19 @@ namespace TrilinosWrappers
 
 
   /**
-   * An implementation of block vectors based on the vector class
-   * implemented in TrilinosWrappers. While the base class provides for
-   * most of the interface, this class handles the actual allocation of
-   * vectors and provides functions that are specific to the underlying
-   * vector type.
+   * An implementation of block vectors based on the vector class implemented
+   * in TrilinosWrappers. While the base class provides for most of the
+   * interface, this class handles the actual allocation of vectors and
+   * provides functions that are specific to the underlying vector type.
    *
    * In contrast to the class MPI::BlockVector, this class is based on a
-   * localized version of the vectors, which means that the whole vector
-   * is stored on each processor. Note that matrix vector products with
-   * this block vector class do only work in case the program is run on
-   * only one processor, since the Trilinos matrices are inherently
-   * parallel.
+   * localized version of the vectors, which means that the whole vector is
+   * stored on each processor. Note that matrix vector products with this
+   * block vector class do only work in case the program is run on only one
+   * processor, since the Trilinos matrices are inherently parallel.
    *
    * @ingroup Vectors
-   * @ingroup TrilinosWrappers
-   * @see @ref GlossBlockLA "Block (linear algebra)"
+   * @ingroup TrilinosWrappers @see @ref GlossBlockLA "Block (linear algebra)"
    * @author Martin Kronbichler, 2008
    */
   class BlockVector : public BlockVectorBase<Vector>
@@ -157,13 +154,13 @@ namespace TrilinosWrappers
     ~BlockVector ();
 
     /**
-    * use compress(VectorOperation) instead
-    *
-    * @deprecated
-    *
-    * See @ref GlossCompress "Compressing distributed objects" for more
-    * information.
-    */
+     * use compress(VectorOperation) instead
+     *
+     * @deprecated
+     *
+     * See @ref GlossCompress "Compressing distributed objects" for more
+     * information.
+     */
     void compress (const Epetra_CombineMode last_action) DEAL_II_DEPRECATED;
 
     /**
@@ -223,12 +220,10 @@ namespace TrilinosWrappers
      * index sets given in the input argument, according to the global size of
      * the individual components described in the index set, and using a given
      * MPI communicator. The MPI communicator is useful when data exchange
-     * with a distributed vector based on the same initialization is
-     * intended. In that case, the same communicator is used for data
-     * exchange.
+     * with a distributed vector based on the same initialization is intended.
+     * In that case, the same communicator is used for data exchange.
      *
-     * If <tt>fast==false</tt>, the vector
-     * is filled with zeros.
+     * If <tt>fast==false</tt>, the vector is filled with zeros.
      */
     void reinit (const std::vector<IndexSet> &partitioning,
                  const MPI_Comm              &communicator = MPI_COMM_WORLD,
@@ -239,16 +234,14 @@ namespace TrilinosWrappers
      * elements in the first argument, and with the respective sizes. Since no
      * distribution map is given, all vectors are local vectors.
      *
-     * If <tt>fast==false</tt>, the vector
-     * is filled with zeros.
+     * If <tt>fast==false</tt>, the vector is filled with zeros.
      */
     void reinit (const std::vector<size_type> &N,
                  const bool                    fast=false);
 
     /**
-     * Reinitialize the vector in the same way as the given to a
-     * distributed block vector. The elements will be copied in this
-     * process.
+     * Reinitialize the vector in the same way as the given to a distributed
+     * block vector. The elements will be copied in this process.
      */
     void reinit (const MPI::BlockVector &V);
 
@@ -261,10 +254,10 @@ namespace TrilinosWrappers
      *
      * Note that you must call this (or the other reinit() functions)
      * function, rather than calling the reinit() functions of an individual
-     * block, to allow the block vector to update its caches of vector
-     * sizes. If you call reinit() on one of the blocks, then subsequent
-     * actions on this object may yield unpredictable results since they may
-     * be routed to the wrong block.
+     * block, to allow the block vector to update its caches of vector sizes.
+     * If you call reinit() on one of the blocks, then subsequent actions on
+     * this object may yield unpredictable results since they may be routed to
+     * the wrong block.
      */
     void reinit (const BlockVector &V,
                  const bool fast = false);
@@ -466,9 +459,9 @@ namespace TrilinosWrappers
 
 
   /**
-   * Global function which overloads the default implementation
-   * of the C++ standard library which uses a temporary object. The
-   * function simply exchanges the data of the two vectors.
+   * Global function which overloads the default implementation of the C++
+   * standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates TrilinosWrappers::BlockVector
    * @author Martin Kronbichler, 2008
index 46585b30392bd2a4471a816a7ee819257475083c..932e2dc5b6086e7412ca41d6575236224e0c3858 100644 (file)
@@ -50,22 +50,20 @@ namespace TrilinosWrappers
   {
     /**
      * An implementation of block vectors based on the vector class
-     * implemented in TrilinosWrappers. While the base class provides for
-     * most of the interface, this class handles the actual allocation of
-     * vectors and provides functions that are specific to the underlying
-     * vector type.
+     * implemented in TrilinosWrappers. While the base class provides for most
+     * of the interface, this class handles the actual allocation of vectors
+     * and provides functions that are specific to the underlying vector type.
      *
-     * The model of distribution of data is such that each of the blocks
-     * is distributed across all MPI processes named in the MPI
-     * communicator. I.e. we don't just distribute the whole vector, but
-     * each component. In the constructors and reinit() functions, one
-     * therefore not only has to specify the sizes of the individual
-     * blocks, but also the number of elements of each of these blocks to
-     * be stored on the local process.
+     * The model of distribution of data is such that each of the blocks is
+     * distributed across all MPI processes named in the MPI communicator.
+     * I.e. we don't just distribute the whole vector, but each component. In
+     * the constructors and reinit() functions, one therefore not only has to
+     * specify the sizes of the individual blocks, but also the number of
+     * elements of each of these blocks to be stored on the local process.
      *
      * @ingroup Vectors
-     * @ingroup TrilinosWrappers
-     * @see @ref GlossBlockLA "Block (linear algebra)"
+     * @ingroup TrilinosWrappers @see @ref GlossBlockLA "Block (linear
+     * algebra)"
      * @author Martin Kronbichler, Wolfgang Bangerth, 2008, 2009
      */
     class BlockVector : public BlockVectorBase<Vector>
@@ -164,9 +162,9 @@ namespace TrilinosWrappers
       /**
        * Another copy function. This one takes a deal.II block vector and
        * copies it into a TrilinosWrappers block vector. Note that the number
-       * of blocks has to be the same in the vector as in the input
-       * vector. Use the reinit() command for resizing the BlockVector or for
-       * changing the internal structure of the block components.
+       * of blocks has to be the same in the vector as in the input vector.
+       * Use the reinit() command for resizing the BlockVector or for changing
+       * the internal structure of the block components.
        *
        * Since Trilinos only works on doubles, this function is limited to
        * accept only one possible number type in the deal.II vector.
@@ -200,14 +198,13 @@ namespace TrilinosWrappers
        * Reinit functionality. This function destroys the old vector content
        * and generates a new one based on the input partitioning. In addition
        * to just specifying one index set as in all the other methods above,
-       * this method allows to supply an additional set of ghost
-       * entries. There are two different versions of a vector that can be
-       * created. If the flag @p vector_writable is set to @p false, the
-       * vector only allows read access to the joint set of @p
-       * parallel_partitioning and @p ghost_entries. The effect of the reinit
-       * method is then equivalent to calling the other reinit method with an
-       * index set containing both the locally owned entries and the ghost
-       * entries.
+       * this method allows to supply an additional set of ghost entries.
+       * There are two different versions of a vector that can be created. If
+       * the flag @p vector_writable is set to @p false, the vector only
+       * allows read access to the joint set of @p parallel_partitioning and
+       * @p ghost_entries. The effect of the reinit method is then equivalent
+       * to calling the other reinit method with an index set containing both
+       * the locally owned entries and the ghost entries.
        *
        * If the flag @p vector_writable is set to true, this creates an
        * alternative storage scheme for ghost elements that allows multiple
@@ -258,9 +255,9 @@ namespace TrilinosWrappers
        * then queried from the input vector. Note that you should not write to
        * the resulting vector any more, since the some data can be stored
        * several times on different processors, leading to unpredictable
-       * results. In particular, such a vector cannot be used for
-       * matrix-vector products as for example done during the solution of
-       * linear systems.
+       * results. In particular, such a vector cannot be used for matrix-
+       * vector products as for example done during the solution of linear
+       * systems.
        */
       void import_nonlocal_data_for_fe (const TrilinosWrappers::BlockSparseMatrix &m,
                                         const BlockVector                         &v);
@@ -483,9 +480,9 @@ namespace TrilinosWrappers
 
 
     /**
-     * Global function which overloads the default implementation
-     * of the C++ standard library which uses a temporary object. The
-     * function simply exchanges the data of the two vectors.
+     * Global function which overloads the default implementation of the C++
+     * standard library which uses a temporary object. The function simply
+     * exchanges the data of the two vectors.
      *
      * @relates TrilinosWrappers::MPI::BlockVector
      * @author Martin Kronbichler, Wolfgang Bangerth, 2008
index 28cade20f68b43b2e47edb908cb09bc20409f6e3..d85946107c6329bac928861ecea86a01180f60f5 100644 (file)
@@ -66,8 +66,7 @@ namespace TrilinosWrappers
   class SolverBase;
 
   /**
-   * The base class for all preconditioners based on Trilinos sparse
-   * matrices.
+   * The base class for all preconditioners based on Trilinos sparse matrices.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -190,17 +189,16 @@ namespace TrilinosWrappers
 
 
   /**
-   * A wrapper class for a (pointwise) Jacobi preconditioner for
-   * Trilinos matrices. This preconditioner works both in serial and in
-   * parallel, depending on the matrix it is based on.
+   * A wrapper class for a (pointwise) Jacobi preconditioner for Trilinos
+   * matrices. This preconditioner works both in serial and in parallel,
+   * depending on the matrix it is based on.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. For the Jacobi preconditioner, these options are the
-   * damping parameter <tt>omega</tt> and a <tt>min_diagonal</tt>
-   * argument that can be used to make the preconditioner work even if
-   * the matrix contains some zero elements on the diagonal. The default
-   * settings are 1 for the damping parameter and zero for the diagonal
-   * augmentation.
+   * The AdditionalData data structure allows to set preconditioner options.
+   * For the Jacobi preconditioner, these options are the damping parameter
+   * <tt>omega</tt> and a <tt>min_diagonal</tt> argument that can be used to
+   * make the preconditioner work even if the matrix contains some zero
+   * elements on the diagonal. The default settings are 1 for the damping
+   * parameter and zero for the diagonal augmentation.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -237,11 +235,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the Jacobi preconditioner is used
-       * on matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we would
-       * divide by zero.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the Jacobi preconditioner is used on
+       * matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we would divide by
+       * zero.
        */
       double min_diagonal;
 
@@ -268,21 +266,19 @@ namespace TrilinosWrappers
    * matrices. This preconditioner works both in serial and in parallel,
    * depending on the matrix it is based on.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. For the SSOR preconditioner, these options are the
-   * damping/relaxation parameter <tt>omega</tt>, a
-   * <tt>min_diagonal</tt> argument that can be used to make the
-   * preconditioner work even if the matrix contains some zero elements
-   * on the diagonal, and a parameter <tt>overlap</tt> that determines
-   * if and how much overlap there should be between the matrix
-   * partitions on the various MPI processes. The default settings are 1
-   * for the relaxation parameter, 0 for the diagonal augmentation and 0
-   * for the overlap.
+   * The AdditionalData data structure allows to set preconditioner options.
+   * For the SSOR preconditioner, these options are the damping/relaxation
+   * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
+   * used to make the preconditioner work even if the matrix contains some
+   * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
+   * determines if and how much overlap there should be between the matrix
+   * partitions on the various MPI processes. The default settings are 1 for
+   * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
+   * overlap.
    *
-   * Note that a parallel application of the SSOR preconditioner is
-   * actually a block-Jacobi preconditioner with block size equal to the
-   * local matrix size. Spoken more technically, this parallel operation
-   * is an <a
+   * Note that a parallel application of the SSOR preconditioner is actually a
+   * block-Jacobi preconditioner with block size equal to the local matrix
+   * size. Spoken more technically, this parallel operation is an <a
    * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
    * Schwarz method</a> with an SSOR <em>approximate solve</em> as inner
    * solver, based on the outer parallel partitioning.
@@ -305,8 +301,8 @@ namespace TrilinosWrappers
      * setting the parameter <tt>min_diagonal</tt> to a small nonzero value
      * the SOR will work on a matrix that is not too far away from the one we
      * want to treat. Finally, <tt>overlap</tt> governs the overlap of the
-     * partitions when the preconditioner runs in parallel, forming a
-     * so-called additive Schwarz preconditioner.
+     * partitions when the preconditioner runs in parallel, forming a so-
+     * called additive Schwarz preconditioner.
      */
     struct AdditionalData
     {
@@ -328,11 +324,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the SSOR preconditioner is used on
-       * matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we divide by
-       * the diagonal element.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the SSOR preconditioner is used on
+       * matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we divide by the
+       * diagonal element.
        */
       double min_diagonal;
 
@@ -366,21 +362,19 @@ namespace TrilinosWrappers
    * matrices. This preconditioner works both in serial and in parallel,
    * depending on the matrix it is based on.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. For the SOR preconditioner, these options are the
-   * damping/relaxation parameter <tt>omega</tt>, a
-   * <tt>min_diagonal</tt> argument that can be used to make the
-   * preconditioner work even if the matrix contains some zero elements
-   * on the diagonal, and a parameter <tt>overlap</tt> that determines
-   * if and how much overlap there should be between the matrix
-   * partitions on the various MPI processes. The default settings are 1
-   * for the relaxation parameter, 0 for the diagonal augmentation and 0
-   * for the overlap.
+   * The AdditionalData data structure allows to set preconditioner options.
+   * For the SOR preconditioner, these options are the damping/relaxation
+   * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
+   * used to make the preconditioner work even if the matrix contains some
+   * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
+   * determines if and how much overlap there should be between the matrix
+   * partitions on the various MPI processes. The default settings are 1 for
+   * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
+   * overlap.
    *
-   * Note that a parallel application of the SOR preconditioner is
-   * actually a block-Jacobi preconditioner with block size equal to the
-   * local matrix size. Spoken more technically, this parallel operation
-   * is an <a
+   * Note that a parallel application of the SOR preconditioner is actually a
+   * block-Jacobi preconditioner with block size equal to the local matrix
+   * size. Spoken more technically, this parallel operation is an <a
    * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
    * Schwarz method</a> with an SOR <em>approximate solve</em> as inner
    * solver, based on the outer parallel partitioning.
@@ -403,8 +397,8 @@ namespace TrilinosWrappers
      * setting the parameter <tt>min_diagonal</tt> to a small nonzero value
      * the SOR will work on a matrix that is not too far away from the one we
      * want to treat. Finally, <tt>overlap</tt> governs the overlap of the
-     * partitions when the preconditioner runs in parallel, forming a
-     * so-called additive Schwarz preconditioner.
+     * partitions when the preconditioner runs in parallel, forming a so-
+     * called additive Schwarz preconditioner.
      */
     struct AdditionalData
     {
@@ -426,11 +420,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the SOR preconditioner is used on
-       * matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we divide by
-       * the diagonal element.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the SOR preconditioner is used on
+       * matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we divide by the
+       * diagonal element.
        */
       double min_diagonal;
 
@@ -459,19 +453,17 @@ namespace TrilinosWrappers
 
 
   /**
-   * A wrapper class for a block Jacobi preconditioner for Trilinos
-   * matrices. As opposed to PreconditionSOR where each row is treated
-   * separately, this scheme collects block of a given size and inverts a full
-   * matrix for all these rows simultaneously. Trilinos allows to select
-   * several strategies for selecting which rows form a block, including
-   * "linear" (i.e., divide the local range of the matrix in slices of the
-   * block size), "greedy" or "metis". Note that the term <em>block
-   * Jacobi</em> does not relate to possible blocks in the MPI setting, but
-   * small blocks of dense matrices extracted from the sparse matrix local to
-   * each processor.
+   * A wrapper class for a block Jacobi preconditioner for Trilinos matrices.
+   * As opposed to PreconditionSOR where each row is treated separately, this
+   * scheme collects block of a given size and inverts a full matrix for all
+   * these rows simultaneously. Trilinos allows to select several strategies
+   * for selecting which rows form a block, including "linear" (i.e., divide
+   * the local range of the matrix in slices of the block size), "greedy" or
+   * "metis". Note that the term <em>block Jacobi</em> does not relate to
+   * possible blocks in the MPI setting, but small blocks of dense matrices
+   * extracted from the sparse matrix local to each processor.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options.
+   * The AdditionalData data structure allows to set preconditioner options.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -518,10 +510,10 @@ namespace TrilinosWrappers
 
       /**
        * Strategy for creation of blocks passed on to Ifpack block relaxation
-       * (variable 'partitioner: type') with this string as the given
-       * value. Available types in Ifpack include "linear" (i.e., divide the
-       * local range of the matrix in slices of the block size), "greedy"
-       * "metis". For a full list, see the documentation of Ifpack.
+       * (variable 'partitioner: type') with this string as the given value.
+       * Available types in Ifpack include "linear" (i.e., divide the local
+       * range of the matrix in slices of the block size), "greedy" "metis".
+       * For a full list, see the documentation of Ifpack.
        */
       std::string block_creation_type;
 
@@ -532,11 +524,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the block Jacobi preconditioner is
-       * used on matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we divide by
-       * the diagonal element.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the block Jacobi preconditioner is used
+       * on matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we divide by the
+       * diagonal element.
        */
       double min_diagonal;
 
@@ -560,15 +552,14 @@ namespace TrilinosWrappers
 
   /**
    * A wrapper class for a block SSOR preconditioner for Trilinos matrices. As
-   * opposed to PreconditionSSOR where each row is treated separately
-   * (point-wise), this scheme collects block of a given size and inverts a
-   * full matrix for all these rows simultaneously. Trilinos allows to select
+   * opposed to PreconditionSSOR where each row is treated separately (point-
+   * wise), this scheme collects block of a given size and inverts a full
+   * matrix for all these rows simultaneously. Trilinos allows to select
    * several strategies for selecting which rows form a block, including
    * "linear" (i.e., divide the local range of the matrix in slices of the
    * block size), "greedy" or "metis".
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options.
+   * The AdditionalData data structure allows to set preconditioner options.
    *
    * Note that a parallel application of this preconditioner is actually a
    * block-Jacobi preconditioner with (outer) block size equal to the local
@@ -625,10 +616,10 @@ namespace TrilinosWrappers
 
       /**
        * Strategy for creation of blocks passed on to Ifpack block relaxation
-       * (variable 'partitioner: type') with this string as the given
-       * value. Available types in Ifpack include "linear" (i.e., divide the
-       * local range of the matrix in slices of the block size), "greedy"
-       * "metis". For a full list, see the documentation of Ifpack.
+       * (variable 'partitioner: type') with this string as the given value.
+       * Available types in Ifpack include "linear" (i.e., divide the local
+       * range of the matrix in slices of the block size), "greedy" "metis".
+       * For a full list, see the documentation of Ifpack.
        */
       std::string block_creation_type;
 
@@ -639,11 +630,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the SSOR preconditioner is used on
-       * matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we divide by
-       * the diagonal element.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the SSOR preconditioner is used on
+       * matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we divide by the
+       * diagonal element.
        */
       double min_diagonal;
 
@@ -681,8 +672,7 @@ namespace TrilinosWrappers
    * the local range of the matrix in slices of the block size), "greedy" or
    * "metis".
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options.
+   * The AdditionalData data structure allows to set preconditioner options.
    *
    * Note that a parallel application of this preconditioner is actually a
    * block-Jacobi preconditioner with (outer) block size equal to the local
@@ -739,10 +729,10 @@ namespace TrilinosWrappers
 
       /**
        * Strategy for creation of blocks passed on to Ifpack block relaxation
-       * (variable 'partitioner: type') with this string as the given
-       * value. Available types in Ifpack include "linear" (i.e., divide the
-       * local range of the matrix in slices of the block size), "greedy"
-       * "metis". For a full list, see the documentation of Ifpack.
+       * (variable 'partitioner: type') with this string as the given value.
+       * Available types in Ifpack include "linear" (i.e., divide the local
+       * range of the matrix in slices of the block size), "greedy" "metis".
+       * For a full list, see the documentation of Ifpack.
        */
       std::string block_creation_type;
 
@@ -753,11 +743,11 @@ namespace TrilinosWrappers
       double omega;
 
       /**
-       * This specifies the minimum value the diagonal elements should
-       * have. This might be necessary when the SOR preconditioner is used on
-       * matrices with zero diagonal elements. In that case, a
-       * straight-forward application would not be possible since we divide by
-       * the diagonal element.
+       * This specifies the minimum value the diagonal elements should have.
+       * This might be necessary when the SOR preconditioner is used on
+       * matrices with zero diagonal elements. In that case, a straight-
+       * forward application would not be possible since we divide by the
+       * diagonal element.
        */
       double min_diagonal;
 
@@ -787,37 +777,34 @@ namespace TrilinosWrappers
 
   /**
    * A wrapper class for an incomplete Cholesky factorization (IC)
-   * preconditioner for @em symmetric Trilinos matrices. This
-   * preconditioner works both in serial and in parallel, depending on
-   * the matrix it is based on. In general, an incomplete factorization
-   * does not take all fill-in elements that would appear in a full
-   * factorization (that is the basis for a direct solve). Trilinos
-   * allows to set the amount of fill-in elements, governed by the
-   * additional data argument <tt>ic_fill</tt>, so one can gradually
-   * choose between a factorization on the sparse matrix structure only
-   * (<tt>ic_fill=0</tt>) to a full factorization (<tt>ic_fill</tt> in
-   * the range of 10 to 50, depending on the spatial dimension of the
-   * PDE problem and the degree of the finite element basis functions;
-   * generally, more required fill-in elements require this parameter to
-   * be set to a higher integer value).
+   * preconditioner for @em symmetric Trilinos matrices. This preconditioner
+   * works both in serial and in parallel, depending on the matrix it is based
+   * on. In general, an incomplete factorization does not take all fill-in
+   * elements that would appear in a full factorization (that is the basis for
+   * a direct solve). Trilinos allows to set the amount of fill-in elements,
+   * governed by the additional data argument <tt>ic_fill</tt>, so one can
+   * gradually choose between a factorization on the sparse matrix structure
+   * only (<tt>ic_fill=0</tt>) to a full factorization (<tt>ic_fill</tt> in
+   * the range of 10 to 50, depending on the spatial dimension of the PDE
+   * problem and the degree of the finite element basis functions; generally,
+   * more required fill-in elements require this parameter to be set to a
+   * higher integer value).
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. Besides the fill-in argument, these options are some
-   * options for perturbations (see the documentation of the
-   * AdditionalData structure for details), and a parameter
-   * <tt>overlap</tt> that determines if and how much overlap there
-   * should be between the matrix partitions on the various MPI
-   * processes.  The default settings are 0 for the additional fill-in, 0
-   * for the absolute augmentation tolerance, 1 for the relative
-   * augmentation tolerance, 0 for the overlap.
+   * The AdditionalData data structure allows to set preconditioner options.
+   * Besides the fill-in argument, these options are some options for
+   * perturbations (see the documentation of the AdditionalData structure for
+   * details), and a parameter <tt>overlap</tt> that determines if and how
+   * much overlap there should be between the matrix partitions on the various
+   * MPI processes.  The default settings are 0 for the additional fill-in, 0
+   * for the absolute augmentation tolerance, 1 for the relative augmentation
+   * tolerance, 0 for the overlap.
    *
-   * Note that a parallel application of the IC preconditioner is
-   * actually a block-Jacobi preconditioner with block size equal to the
-   * local matrix size. Spoken more technically, this parallel operation
-   * is an <a
+   * Note that a parallel application of the IC preconditioner is actually a
+   * block-Jacobi preconditioner with block size equal to the local matrix
+   * size. Spoken more technically, this parallel operation is an <a
    * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
-   * Schwarz method</a> with an IC <em>approximate solve</em> as inner
-   * solver, based on the (outer) parallel partitioning.
+   * Schwarz method</a> with an IC <em>approximate solve</em> as inner solver,
+   * based on the (outer) parallel partitioning.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -899,35 +886,32 @@ namespace TrilinosWrappers
 
 
   /**
-   * A wrapper class for an incomplete LU factorization (ILU)
-   * preconditioner for Trilinos matrices. This preconditioner works
-   * both in serial and in parallel, depending on the matrix it is based
-   * on. In general, an incomplete factorization does not take all
-   * fill-in elements that would appear in a full factorization (that is
-   * the basis for a direct solve). Trilinos allows to set the amount of
-   * fill-in elements, governed by the additional data argument
-   * <tt>ilu_fill</tt>, so one can gradually choose between a
-   * factorization on the sparse matrix structure only
-   * (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in
-   * the range of 10 to 50, depending on the spatial dimension of the
-   * PDE problem and the degree of the finite element basis functions;
-   * generally, more required fill-in elements require this parameter to
-   * be set to a higher integer value).
+   * A wrapper class for an incomplete LU factorization (ILU) preconditioner
+   * for Trilinos matrices. This preconditioner works both in serial and in
+   * parallel, depending on the matrix it is based on. In general, an
+   * incomplete factorization does not take all fill-in elements that would
+   * appear in a full factorization (that is the basis for a direct solve).
+   * Trilinos allows to set the amount of fill-in elements, governed by the
+   * additional data argument <tt>ilu_fill</tt>, so one can gradually choose
+   * between a factorization on the sparse matrix structure only
+   * (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in the
+   * range of 10 to 50, depending on the spatial dimension of the PDE problem
+   * and the degree of the finite element basis functions; generally, more
+   * required fill-in elements require this parameter to be set to a higher
+   * integer value).
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. Besides the fill-in argument, these options are some
-   * options for perturbations (see the documentation of the
-   * AdditionalData structure for details), and a parameter
-   * <tt>overlap</tt> that determines if and how much overlap there
-   * should be between the matrix partitions on the various MPI
-   * processes. The default settings are 0 for the additional fill-in, 0
-   * for the absolute augmentation tolerance, 1 for the relative
-   * augmentation tolerance, 0 for the overlap.
+   * The AdditionalData data structure allows to set preconditioner options.
+   * Besides the fill-in argument, these options are some options for
+   * perturbations (see the documentation of the AdditionalData structure for
+   * details), and a parameter <tt>overlap</tt> that determines if and how
+   * much overlap there should be between the matrix partitions on the various
+   * MPI processes. The default settings are 0 for the additional fill-in, 0
+   * for the absolute augmentation tolerance, 1 for the relative augmentation
+   * tolerance, 0 for the overlap.
    *
-   * Note that a parallel application of the ILU preconditioner is
-   * actually a block-Jacobi preconditioner with block size equal to the
-   * local matrix size. Spoken more technically, this parallel operation
-   * is an <a
+   * Note that a parallel application of the ILU preconditioner is actually a
+   * block-Jacobi preconditioner with block size equal to the local matrix
+   * size. Spoken more technically, this parallel operation is an <a
    * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
    * Schwarz method</a> with an ILU <em>approximate solve</em> as inner
    * solver, based on the (outer) parallel partitioning.
@@ -1023,25 +1007,23 @@ namespace TrilinosWrappers
    * lets the user specify which elements should be dropped (i.e., should not
    * be part of the incomplete decomposition). Trilinos calculates first the
    * complete factorization for one row, and then skips those elements that
-   * are lower than the threshold. This is the main difference to the
-   * non-thresholded ILU preconditioner, where the parameter
-   * <tt>ilut_fill</tt> governs the incomplete factorization structure. This
-   * parameter is available here as well, but provides only some extra
-   * information here.
+   * are lower than the threshold. This is the main difference to the non-
+   * thresholded ILU preconditioner, where the parameter <tt>ilut_fill</tt>
+   * governs the incomplete factorization structure. This parameter is
+   * available here as well, but provides only some extra information here.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options. Besides the fill-in arguments, these options are some options
-   * for perturbations (see the documentation of the AdditionalData structure
-   * for details), and a parameter <tt>overlap</tt> that determines if and how
+   * The AdditionalData data structure allows to set preconditioner options.
+   * Besides the fill-in arguments, these options are some options for
+   * perturbations (see the documentation of the AdditionalData structure for
+   * details), and a parameter <tt>overlap</tt> that determines if and how
    * much overlap there should be between the matrix partitions on the various
    * MPI processes. The default settings are 0 for the additional fill-in, 0
    * for the absolute augmentation tolerance, 1 for the relative augmentation
    * tolerance, 0 for the overlap.
    *
-   * Note that a parallel application of the ILU-T preconditioner is
-   * actually a block-Jacobi preconditioner with block size equal to the
-   * local matrix size. Spoken more technically, this parallel operation
-   * is an <a
+   * Note that a parallel application of the ILU-T preconditioner is actually
+   * a block-Jacobi preconditioner with block size equal to the local matrix
+   * size. Spoken more technically, this parallel operation is an <a
    * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
    * Schwarz method</a> with an ILU <em>approximate solve</em> as inner
    * solver, based on the (outer) parallel partitioning.
@@ -1055,8 +1037,8 @@ namespace TrilinosWrappers
   public:
     /**
      * Standardized data struct to pipe additional parameters to the
-     * preconditioner. The Trilinos ILU-T decomposition allows for some
-     * fill-in, so it actually is a threshold incomplete LU factorization. The
+     * preconditioner. The Trilinos ILU-T decomposition allows for some fill-
+     * in, so it actually is a threshold incomplete LU factorization. The
      * amount of fill-in, and hence, the amount of memory used by this
      * preconditioner, is controlled by the parameters <tt>ilut_drop</tt> and
      * <tt>ilut_fill</tt>, which specifies a threshold about which values
@@ -1135,20 +1117,18 @@ namespace TrilinosWrappers
 
 
   /**
-   * A wrapper class for a sparse direct LU decomposition on parallel
-   * blocks for Trilinos matrices. When run in serial, this corresponds
-   * to a direct solve on the matrix.
+   * A wrapper class for a sparse direct LU decomposition on parallel blocks
+   * for Trilinos matrices. When run in serial, this corresponds to a direct
+   * solve on the matrix.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options.
+   * The AdditionalData data structure allows to set preconditioner options.
    *
-   * Note that a parallel application of the block direct solve
-   * preconditioner is actually a block-Jacobi preconditioner with block
-   * size equal to the local matrix size. Spoken more technically, this
-   * parallel operation is an <a
-   * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
-   * Schwarz method</a> with an <em>exact solve</em> as inner solver,
-   * based on the (outer) parallel partitioning.
+   * Note that a parallel application of the block direct solve preconditioner
+   * is actually a block-Jacobi preconditioner with block size equal to the
+   * local matrix size. Spoken more technically, this parallel operation is an
+   * <a href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
+   * Schwarz method</a> with an <em>exact solve</em> as inner solver, based on
+   * the (outer) parallel partitioning.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -1192,8 +1172,7 @@ namespace TrilinosWrappers
   /**
    * A wrapper class for a Chebyshev preconditioner for Trilinos matrices.
    *
-   * The AdditionalData data structure allows to set preconditioner
-   * options.
+   * The AdditionalData data structure allows to set preconditioner options.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Preconditioners
@@ -1304,9 +1283,9 @@ namespace TrilinosWrappers
    * processors.
    *
    * For proper functionality of this class we recommend using Trilinos v9.0
-   * and higher. Older versions may have problems with generating the
-   * coarse-matrix structure when using matrices with many nonzero entries per
-   * row (i.e., matrices stemming from higher order finite element
+   * and higher. Older versions may have problems with generating the coarse-
+   * matrix structure when using matrices with many nonzero entries per row
+   * (i.e., matrices stemming from higher order finite element
    * discretizations).
    *
    * @ingroup TrilinosWrappers
@@ -1319,9 +1298,9 @@ namespace TrilinosWrappers
 
     /**
      * A data structure that is used to control details of how the algebraic
-     * multigrid is set up. The flags detailed in here are then passed to
-     * the Trilinos ML implementation. A structure of the current type are
-     * passed to the constructor of PreconditionAMG.
+     * multigrid is set up. The flags detailed in here are then passed to the
+     * Trilinos ML implementation. A structure of the current type are passed
+     * to the constructor of PreconditionAMG.
      */
     struct AdditionalData
     {
@@ -1344,8 +1323,8 @@ namespace TrilinosWrappers
       /**
        * Determines whether the AMG preconditioner should be optimized for
        * elliptic problems (ML option smoothed aggregation SA, using a
-       * Chebyshev smoother) or for non-elliptic problems (ML option
-       * non-symmetric smoothed aggregation NSSA, smoother is SSOR with
+       * Chebyshev smoother) or for non-elliptic problems (ML option non-
+       * symmetric smoothed aggregation NSSA, smoother is SSOR with
        * underrelaxation).
        */
       bool elliptic;
@@ -1413,37 +1392,37 @@ namespace TrilinosWrappers
       bool output_details;
 
       /**
-       * Determines which smoother to use for the AMG cycle. Possibilities
-       * for smoother_type are the following:
+       * Determines which smoother to use for the AMG cycle. Possibilities for
+       * smoother_type are the following:
        * <ul>
-       *   <li>  "Aztec" </li>
-       *   <li>  "IFPACK" </li>
-       *   <li>  "Jacobi" </li>
-       *   <li>  "ML symmetric Gauss-Seidel" </li>
-       *   <li>  "symmetric Gauss-Seidel" </li>
-       *   <li>  "ML Gauss-Seidel" </li>
-       *   <li>  "Gauss-Seidel" </li>
-       *   <li>  "block Gauss-Seidel" </li>
-       *   <li>  "symmetric block Gauss-Seidel" </li>
-       *   <li>  "Chebyshev" </li>
-       *   <li>  "MLS" </li>
-       *   <li>  "Hiptmair" </li>
-       *   <li>  "Amesos-KLU" </li>
-       *   <li>  "Amesos-Superlu" </li>
-       *   <li>  "Amesos-UMFPACK" </li>
-       *   <li>  "Amesos-Superludist" </li>
-       *   <li>  "Amesos-MUMPS" </li>
-       *   <li>  "user-defined" </li>
-       *   <li>  "SuperLU" </li>
-       *   <li>  "IFPACK-Chebyshev" </li>
-       *   <li>  "self" </li>
-       *   <li>  "do-nothing" </li>
-       *   <li>  "IC" </li>
-       *   <li>  "ICT" </li>
-       *   <li>  "ILU" </li>
-       *   <li>  "ILUT" </li>
-       *   <li>  "Block Chebyshev" </li>
-       *   <li>  "IFPACK-Block Chebyshev" </li>
+       * <li>  "Aztec" </li>
+       * <li>  "IFPACK" </li>
+       * <li>  "Jacobi" </li>
+       * <li>  "ML symmetric Gauss-Seidel" </li>
+       * <li>  "symmetric Gauss-Seidel" </li>
+       * <li>  "ML Gauss-Seidel" </li>
+       * <li>  "Gauss-Seidel" </li>
+       * <li>  "block Gauss-Seidel" </li>
+       * <li>  "symmetric block Gauss-Seidel" </li>
+       * <li>  "Chebyshev" </li>
+       * <li>  "MLS" </li>
+       * <li>  "Hiptmair" </li>
+       * <li>  "Amesos-KLU" </li>
+       * <li>  "Amesos-Superlu" </li>
+       * <li>  "Amesos-UMFPACK" </li>
+       * <li>  "Amesos-Superludist" </li>
+       * <li>  "Amesos-MUMPS" </li>
+       * <li>  "user-defined" </li>
+       * <li>  "SuperLU" </li>
+       * <li>  "IFPACK-Chebyshev" </li>
+       * <li>  "self" </li>
+       * <li>  "do-nothing" </li>
+       * <li>  "IC" </li>
+       * <li>  "ICT" </li>
+       * <li>  "ILU" </li>
+       * <li>  "ILUT" </li>
+       * <li>  "Block Chebyshev" </li>
+       * <li>  "IFPACK-Block Chebyshev" </li>
        * </ul>
        */
       const char *smoother_type;
@@ -1585,33 +1564,30 @@ namespace TrilinosWrappers
                  const VectorBase &src) const;
 
     /**
-     * Apply the preconditioner on deal.II data structures
-     * instead of the ones provided in the Trilinos wrapper class,
-     * i.e., dst = src.
+     * Apply the preconditioner on deal.II data structures instead of the ones
+     * provided in the Trilinos wrapper class, i.e., dst = src.
      */
     void vmult (dealii::Vector<double>       &dst,
                 const dealii::Vector<double> &src) const;
 
     /**
-     * Apply the transpose preconditioner on deal.II data structures
-     * instead of the ones provided in the Trilinos wrapper class,
-     * i.e. dst = src.
+     * Apply the transpose preconditioner on deal.II data structures instead
+     * of the ones provided in the Trilinos wrapper class, i.e. dst = src.
      */
     void Tvmult (dealii::Vector<double>       &dst,
                  const dealii::Vector<double> &src) const;
 
     /**
-     * Apply the preconditioner on deal.II parallel data structures
-     * instead of the ones provided in the Trilinos wrapper class,
-     * i.e., dst = src.
+     * Apply the preconditioner on deal.II parallel data structures instead of
+     * the ones provided in the Trilinos wrapper class, i.e., dst = src.
      */
     void vmult (parallel::distributed::Vector<double>       &dst,
                 const dealii::parallel::distributed::Vector<double> &src) const;
 
     /**
      * Apply the transpose preconditioner on deal.II parallel data structures
-     * instead of the ones provided in the Trilinos wrapper class,
-     * i.e., dst = src.
+     * instead of the ones provided in the Trilinos wrapper class, i.e., dst =
+     * src.
      */
     void Tvmult (parallel::distributed::Vector<double>       &dst,
                  const dealii::parallel::distributed::Vector<double> &src) const;
index 822b742b1dfe2732d5fc90e7e1672a3eb87ed6c9..9f643bad365c73c2261b3ee4a22a484ce2e0ee86 100644 (file)
@@ -43,21 +43,19 @@ namespace TrilinosWrappers
 
 
   /**
-   * Base class for solver classes using the Trilinos solvers. Since
-   * solvers in Trilinos are selected based on flags passed to a generic
-   * solver object, basically all the actual solver calls happen in this
-   * class, and derived classes simply set the right flags to select one
-   * solver or another, or to set certain parameters for individual
-   * solvers. For a general discussion on the Trilinos solver package
-   * AztecOO, we refer to the <a href =
-   * "http://trilinos.sandia.gov/packages/aztecoo/AztecOOUserGuide.pdf">AztecOO
-   * user guide</a>.
+   * Base class for solver classes using the Trilinos solvers. Since solvers
+   * in Trilinos are selected based on flags passed to a generic solver
+   * object, basically all the actual solver calls happen in this class, and
+   * derived classes simply set the right flags to select one solver or
+   * another, or to set certain parameters for individual solvers. For a
+   * general discussion on the Trilinos solver package AztecOO, we refer to
+   * the <a href = "http://trilinos.sandia.gov/packages/aztecoo/AztecOOUserGui
+   * de.pdf">AztecOO user guide</a>.
    *
    * This solver class can also be used as a standalone class, where the
-   * respective Krylov method is set via the flag
-   * <tt>solver_name</tt>. This can be done at runtime (e.g., when
-   * parsing the solver from a ParameterList) and is similar to the
-   * deal.II class SolverSelector.
+   * respective Krylov method is set via the flag <tt>solver_name</tt>. This
+   * can be done at runtime (e.g., when parsing the solver from a
+   * ParameterList) and is similar to the deal.II class SolverSelector.
    *
    * @ingroup TrilinosWrappers
    * @author Martin Kronbichler, 2008, 2009
@@ -76,9 +74,7 @@ namespace TrilinosWrappers
     enum SolverName {cg, cgs, gmres, bicgstab, tfqmr} solver_name;
 
     /**
-     * Standardized data struct to
-     * pipe additional data to the
-     * solver.
+     * Standardized data struct to pipe additional data to the solver.
      */
 
     struct AdditionalData
@@ -135,11 +131,11 @@ namespace TrilinosWrappers
            const PreconditionBase &preconditioner);
 
     /**
-     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
-     * operator. This function can be used for matrix free
-     * computation. Depending on the information provided by derived classes
-     * and the object passed as a preconditioner, one of the linear solvers
-     * and preconditioners of Trilinos is chosen.
+     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+     * This function can be used for matrix free computation. Depending on the
+     * information provided by derived classes and the object passed as a
+     * preconditioner, one of the linear solvers and preconditioners of
+     * Trilinos is chosen.
      */
     void
     solve (Epetra_Operator        &A,
@@ -150,12 +146,12 @@ namespace TrilinosWrappers
     /**
      * Solve the linear system <tt>Ax=b</tt>. Depending on the information
      * provided by derived classes and the object passed as a preconditioner,
-     * one of the linear solvers and preconditioners of Trilinos is
-     * chosen. This class works with matrices according to the
-     * TrilinosWrappers format, but can take deal.II vectors as
-     * argument. Since deal.II are serial vectors (not distributed), this
-     * function does only what you expect in case the matrix is locally
-     * owned. Otherwise, an exception will be thrown.
+     * one of the linear solvers and preconditioners of Trilinos is chosen.
+     * This class works with matrices according to the TrilinosWrappers
+     * format, but can take deal.II vectors as argument. Since deal.II are
+     * serial vectors (not distributed), this function does only what you
+     * expect in case the matrix is locally owned. Otherwise, an exception
+     * will be thrown.
      */
     void
     solve (const SparseMatrix           &A,
@@ -164,15 +160,15 @@ namespace TrilinosWrappers
            const PreconditionBase       &preconditioner);
 
     /**
-     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
-     * operator. This function can be used for matrix free
-     * computations. Depending on the information provided by derived classes
-     * and the object passed as a preconditioner, one of the linear solvers
-     * and preconditioners of Trilinos is chosen. This class works with
-     * matrices according to the TrilinosWrappers format, but can take deal.II
-     * vectors as argument. Since deal.II are serial vectors (not
-     * distributed), this function does only what you expect in case the
-     * matrix is locally owned. Otherwise, an exception will be thrown.
+     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+     * This function can be used for matrix free computations. Depending on
+     * the information provided by derived classes and the object passed as a
+     * preconditioner, one of the linear solvers and preconditioners of
+     * Trilinos is chosen. This class works with matrices according to the
+     * TrilinosWrappers format, but can take deal.II vectors as argument.
+     * Since deal.II are serial vectors (not distributed), this function does
+     * only what you expect in case the matrix is locally owned. Otherwise, an
+     * exception will be thrown.
      */
     void
     solve (Epetra_Operator              &A,
@@ -193,11 +189,11 @@ namespace TrilinosWrappers
            const PreconditionBase                              &preconditioner);
 
     /**
-     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
-     * operator. This function can be used for matrix free
-     * computation. Depending on the information provided by derived classes
-     * and the object passed as a preconditioner, one of the linear solvers
-     * and preconditioners of Trilinos is chosen.
+     * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+     * This function can be used for matrix free computation. Depending on the
+     * information provided by derived classes and the object passed as a
+     * preconditioner, one of the linear solvers and preconditioners of
+     * Trilinos is chosen.
      */
     void
     solve (Epetra_Operator                                     &A,
@@ -260,8 +256,7 @@ namespace TrilinosWrappers
 
 
   /**
-   * An implementation of the solver interface using the Trilinos CG
-   * solver.
+   * An implementation of the solver interface using the Trilinos CG solver.
    *
    * @ingroup TrilinosWrappers
    * @author Martin Kronbichler, 2008
@@ -307,8 +302,7 @@ namespace TrilinosWrappers
 
 
   /**
-   * An implementation of the solver interface using the Trilinos CGS
-   * solver.
+   * An implementation of the solver interface using the Trilinos CGS solver.
    *
    * @ingroup TrilinosWrappers
    * @author Martin Kronbichler, 2008
@@ -497,15 +491,14 @@ namespace TrilinosWrappers
 
 
   /**
-   * An implementation of Trilinos direct solvers (using the Amesos
-   * package). The data field AdditionalData::solver_type can be used to
-   * specify the type of solver. It allows the use of built-in solvers
-   * Amesos_Klu as well as third-party solvers Amesos_Superludist or
-   * Amesos_Mumps.
+   * An implementation of Trilinos direct solvers (using the Amesos package).
+   * The data field AdditionalData::solver_type can be used to specify the
+   * type of solver. It allows the use of built-in solvers Amesos_Klu as well
+   * as third-party solvers Amesos_Superludist or Amesos_Mumps.
    *
-   * For instructions on how to install Trilinos for use with
-   * direct solvers other than KLU, see the link to the Trilinos
-   * installation instructions linked to from the deal.II ReadMe file.
+   * For instructions on how to install Trilinos for use with direct solvers
+   * other than KLU, see the link to the Trilinos installation instructions
+   * linked to from the deal.II ReadMe file.
    *
    * @ingroup TrilinosWrappers
    * @author Martin Kronbichler, 2009, Uwe K&ouml;cher, 2014
@@ -536,16 +529,16 @@ namespace TrilinosWrappers
        * Set the solver type (for third party solver support of Trilinos
        * Amesos package). Possibilities are:
        * <ul>
-       *   <li>  "Amesos_Lapack" </li>
-       *   <li>  "Amesos_Scalapack" </li>
-       *   <li>  "Amesos_Klu" </li>
-       *   <li>  "Amesos_Umfpack" </li>
-       *   <li>  "Amesos_Pardiso" </li>
-       *   <li>  "Amesos_Taucs" </li>
-       *   <li>  "Amesos_Superlu" </li>
-       *   <li>  "Amesos_Superludist" </li>
-       *   <li>  "Amesos_Dscpack" </li>
-       *   <li>  "Amesos_Mumps" </li>
+       * <li>  "Amesos_Lapack" </li>
+       * <li>  "Amesos_Scalapack" </li>
+       * <li>  "Amesos_Klu" </li>
+       * <li>  "Amesos_Umfpack" </li>
+       * <li>  "Amesos_Pardiso" </li>
+       * <li>  "Amesos_Taucs" </li>
+       * <li>  "Amesos_Superlu" </li>
+       * <li>  "Amesos_Superludist" </li>
+       * <li>  "Amesos_Dscpack" </li>
+       * <li>  "Amesos_Mumps" </li>
        * </ul>
        * Note that the availability of these solvers in deal.II depends on
        * which solvers were set when configuring Trilinos.
@@ -599,8 +592,7 @@ namespace TrilinosWrappers
            const dealii::parallel::distributed::Vector<double> &b);
 
     /**
-     * Access to object that controls
-     * convergence.
+     * Access to object that controls convergence.
      */
     SolverControl &control() const;
 
index 13bde681942671591852ffe954ef9d04538544eb..e124590219b49cc4fe4b4b916226008b6ca0c353 100644 (file)
@@ -172,20 +172,20 @@ namespace TrilinosWrappers
 
     /**
      * General template for sparse matrix accessors. The first template
-     * argument denotes the underlying numeric type, the second the
-     * constness of the matrix.
+     * argument denotes the underlying numeric type, the second the constness
+     * of the matrix.
      *
-     * The general template is not implemented, only the specializations
-     * for the two possible values of the second template
-     * argument. Therefore, the interface listed here only serves as a
-     * template provided since doxygen does not link the specializations.
+     * The general template is not implemented, only the specializations for
+     * the two possible values of the second template argument. Therefore, the
+     * interface listed here only serves as a template provided since doxygen
+     * does not link the specializations.
      */
     template <bool Constess>
     class Accessor : public AccessorBase
     {
       /**
-      * Value of this matrix entry.
-      */
+       * Value of this matrix entry.
+       */
       TrilinosScalar value() const;
 
       /**
@@ -318,9 +318,9 @@ namespace TrilinosWrappers
     };
 
     /**
-     * STL conforming iterator. This class acts as an iterator walking
-     * over the elements of Trilinos matrices. The implementation of this
-     * class is similar to the one for PETSc matrices.
+     * STL conforming iterator. This class acts as an iterator walking over
+     * the elements of Trilinos matrices. The implementation of this class is
+     * similar to the one for PETSc matrices.
      *
      * Note that Trilinos stores the elements within each row in ascending
      * order. This is opposed to the deal.II sparse matrix style where the
@@ -425,30 +425,28 @@ namespace TrilinosWrappers
 
 
   /**
-   * This class implements a wrapper to use the Trilinos distributed
-   * sparse matrix class Epetra_FECrsMatrix. This is precisely the kind of
-   * matrix we deal with all the time - we most likely get it from some
-   * assembly process, where also entries not locally owned might need to
-   * be written and hence need to be forwarded to the owner process.  This
-   * class is designed to be used in a distributed memory architecture
-   * with an MPI compiler on the bottom, but works equally well also for
-   * serial processes. The only requirement for this class to work is that
-   * Trilinos has been installed with the same compiler as is used for
-   * generating deal.II.
+   * This class implements a wrapper to use the Trilinos distributed sparse
+   * matrix class Epetra_FECrsMatrix. This is precisely the kind of matrix we
+   * deal with all the time - we most likely get it from some assembly
+   * process, where also entries not locally owned might need to be written
+   * and hence need to be forwarded to the owner process.  This class is
+   * designed to be used in a distributed memory architecture with an MPI
+   * compiler on the bottom, but works equally well also for serial processes.
+   * The only requirement for this class to work is that Trilinos has been
+   * installed with the same compiler as is used for generating deal.II.
    *
-   * The interface of this class is modeled after the existing
-   * SparseMatrix class in deal.II. It has almost the same member
-   * functions, and is often exchangable. However, since Trilinos only
-   * supports a single scalar type (double), it is not templated, and only
-   * works with doubles.
+   * The interface of this class is modeled after the existing SparseMatrix
+   * class in deal.II. It has almost the same member functions, and is often
+   * exchangable. However, since Trilinos only supports a single scalar type
+   * (double), it is not templated, and only works with doubles.
    *
-   * Note that Trilinos only guarantees that operations do what you expect
-   * if the functions @p GlobalAssemble has been called after matrix
-   * assembly.  Therefore, you need to call SparseMatrix::compress()
-   * before you actually use the matrix. This also calls @p FillComplete
-   * that compresses the storage format for sparse matrices by discarding
-   * unused elements. Trilinos allows to continue with assembling the
-   * matrix after calls to these functions, though.
+   * Note that Trilinos only guarantees that operations do what you expect if
+   * the functions @p GlobalAssemble has been called after matrix assembly.
+   * Therefore, you need to call SparseMatrix::compress() before you actually
+   * use the matrix. This also calls @p FillComplete that compresses the
+   * storage format for sparse matrices by discarding unused elements.
+   * Trilinos allows to continue with assembling the matrix after calls to
+   * these functions, though.
    *
    * <h3>Thread safety of Trilinos matrices</h3>
    *
@@ -460,23 +458,22 @@ namespace TrilinosWrappers
    * rows of the matrix from several threads simultaneously under the
    * following three conditions:
    * <ul>
-   *   <li> The matrix uses only one MPI process.
-   *   <li> The matrix has been initialized with the reinit() method
-   *   with a CompressedSimpleSparsityPattern (that includes the set of locally
-   *   relevant rows, i.e., the rows that an assembly routine will possibly
-   *   write into).
-   *   <li> The matrix has been initialized from a
-   *   TrilinosWrappers::SparsityPattern object that in turn has been
-   *   initialized with the reinit function specifying three index sets, one
-   *   for the rows, one for the columns and for the larger set of @p
-   *   writeable_rows, and the operation is an addition. At some point in the
-   *   future, Trilinos support might be complete enough such that initializing
-   *   from a
-   *   TrilinosWrappers::SparsityPattern that has been filled by a function
-   *   similar to DoFTools::make_sparsity_pattern always results in a matrix
-   *   that allows several processes to write into the same matrix row. However,
-   *   Trilinos until version at least 11.12 does not correctly support this
-   *   feature.
+   * <li> The matrix uses only one MPI process.
+   * <li> The matrix has been initialized with the reinit() method with a
+   * CompressedSimpleSparsityPattern (that includes the set of locally
+   * relevant rows, i.e., the rows that an assembly routine will possibly
+   * write into).
+   * <li> The matrix has been initialized from a
+   * TrilinosWrappers::SparsityPattern object that in turn has been
+   * initialized with the reinit function specifying three index sets, one for
+   * the rows, one for the columns and for the larger set of @p
+   * writeable_rows, and the operation is an addition. At some point in the
+   * future, Trilinos support might be complete enough such that initializing
+   * from a TrilinosWrappers::SparsityPattern that has been filled by a
+   * function similar to DoFTools::make_sparsity_pattern always results in a
+   * matrix that allows several processes to write into the same matrix row.
+   * However, Trilinos until version at least 11.12 does not correctly support
+   * this feature.
    * </ul>
    *
    * Note that all other reinit methods and constructors of
@@ -582,10 +579,10 @@ namespace TrilinosWrappers
      * meant for use in serial programs, where there is no need to specify how
      * the matrix is going to be distributed among different processors. This
      * function works in %parallel, too, but it is recommended to manually
-     * specify the %parallel partioning of the matrix using an
-     * Epetra_Map. When run in %parallel, it is currently necessary that each
-     * processor holds the sparsity_pattern structure because each processor
-     * sets its rows.
+     * specify the %parallel partioning of the matrix using an Epetra_Map.
+     * When run in %parallel, it is currently necessary that each processor
+     * holds the sparsity_pattern structure because each processor sets its
+     * rows.
      *
      * This is a collective operation that needs to be called on all
      * processors in order to avoid a dead lock.
@@ -630,11 +627,11 @@ namespace TrilinosWrappers
      * processors in order to avoid a deadlock.
      *
      * @note If a different sparsity pattern is given in the last argument
-     * (i.e., one that differs from the one used in the sparse matrix given
-     * in the first argument), then the resulting Trilinos matrix will have
-     * the sparsity pattern so given. This of course also means that all
-     * entries in the given matrix that are not part of this separate
-     * sparsity pattern will in fact be dropped.
+     * (i.e., one that differs from the one used in the sparse matrix given in
+     * the first argument), then the resulting Trilinos matrix will have the
+     * sparsity pattern so given. This of course also means that all entries
+     * in the given matrix that are not part of this separate sparsity pattern
+     * will in fact be dropped.
      */
     template <typename number>
     void reinit (const ::dealii::SparseMatrix<number> &dealii_sparse_matrix,
@@ -655,23 +652,23 @@ namespace TrilinosWrappers
      */
 //@{
     /**
-     * Constructor using an Epetra_Map to describe the %parallel
-     * partitioning. The parameter @p n_max_entries_per_row sets the number of
-     * nonzero entries in each row that will be allocated. Note that this
-     * number does not need to be exact, and it is even allowed that the
-     * actual matrix structure has more nonzero entries than specified in the
-     * constructor. However it is still advantageous to provide good estimates
-     * here since this will considerably increase the performance of the
-     * matrix setup. However, there is no effect in the performance of
-     * matrix-vector products, since Trilinos reorganizes the matrix memory
-     * prior to use (in the compress() step).
+     * Constructor using an Epetra_Map to describe the %parallel partitioning.
+     * The parameter @p n_max_entries_per_row sets the number of nonzero
+     * entries in each row that will be allocated. Note that this number does
+     * not need to be exact, and it is even allowed that the actual matrix
+     * structure has more nonzero entries than specified in the constructor.
+     * However it is still advantageous to provide good estimates here since
+     * this will considerably increase the performance of the matrix setup.
+     * However, there is no effect in the performance of matrix-vector
+     * products, since Trilinos reorganizes the matrix memory prior to use (in
+     * the compress() step).
      */
     SparseMatrix (const Epetra_Map  &parallel_partitioning,
                   const size_type    n_max_entries_per_row = 0);
 
     /**
-     * Same as before, but now set a value of nonzeros for each matrix
-     * row. Since we know the number of elements in the matrix exactly in this
+     * Same as before, but now set a value of nonzeros for each matrix row.
+     * Since we know the number of elements in the matrix exactly in this
      * case, we can already allocate the right amount of memory, which makes
      * the creation process including the insertion of nonzero elements by the
      * respective SparseMatrix::reinit call considerably faster.
@@ -724,15 +721,14 @@ namespace TrilinosWrappers
      * programs following the style of the tutorial programs, this function
      * (and the respective call for a rectangular matrix) are the natural way
      * to initialize the matrix size, its distribution among the MPI processes
-     * (if run in %parallel) as well as the locatoin of non-zero
-     * elements. Trilinos stores the sparsity pattern internally, so it won't
-     * be needed any more after this call, in contrast to the deal.II own
-     * object. The optional argument @p exchange_data can be used for
-     * reinitialization with a sparsity pattern that is not fully
-     * constructed. This feature is only implemented for input sparsity
-     * patterns of type CompressedSimpleSparsityPattern. If the flag is not
-     * set, each processor just sets the elements in the sparsity pattern that
-     * belong to its rows.
+     * (if run in %parallel) as well as the locatoin of non-zero elements.
+     * Trilinos stores the sparsity pattern internally, so it won't be needed
+     * any more after this call, in contrast to the deal.II own object. The
+     * optional argument @p exchange_data can be used for reinitialization
+     * with a sparsity pattern that is not fully constructed. This feature is
+     * only implemented for input sparsity patterns of type
+     * CompressedSimpleSparsityPattern. If the flag is not set, each processor
+     * just sets the elements in the sparsity pattern that belong to its rows.
      *
      * If the sparsity pattern given to this function is of type
      * CompressedSimpleSparsity pattern, then a matrix will be created that
@@ -821,9 +817,9 @@ namespace TrilinosWrappers
      * actual matrix structure has more nonzero entries than specified in the
      * constructor. However it is still advantageous to provide good estimates
      * here since this will considerably increase the performance of the
-     * matrix setup. However, there is no effect in the performance of
-     * matrix-vector products, since Trilinos reorganizes the matrix memory
-     * prior to use (in the compress() step).
+     * matrix setup. However, there is no effect in the performance of matrix-
+     * vector products, since Trilinos reorganizes the matrix memory prior to
+     * use (in the compress() step).
      */
     SparseMatrix (const IndexSet    &parallel_partitioning,
                   const MPI_Comm    &communicator = MPI_COMM_WORLD,
@@ -1073,8 +1069,8 @@ namespace TrilinosWrappers
      * in matrix-vector products.
      * <li> If the matrix structure has already been fixed (either by
      * initialization with a sparsity pattern or by calling compress() during
-     * the setup phase), this command does the %parallel exchange of
-     * data. This is necessary when we perform assembly on more than one (MPI)
+     * the setup phase), this command does the %parallel exchange of data.
+     * This is necessary when we perform assembly on more than one (MPI)
      * process, because then some non-local row data will accumulate on nodes
      * that belong to the current's processor element, but are actually held
      * by another. This command is usually called after all elements have been
@@ -1082,12 +1078,12 @@ namespace TrilinosWrappers
      * </ul>
      *
      * In both cases, this function compresses the data structures and allows
-     * the resulting matrix to be used in all other operations like
-     * matrix-vector products. This is a collective operation, i.e., it needs
-     * to be run on all processors when used in %parallel.
+     * the resulting matrix to be used in all other operations like matrix-
+     * vector products. This is a collective operation, i.e., it needs to be
+     * run on all processors when used in %parallel.
      *
-     * See @ref GlossCompress "Compressing distributed objects"
-     * for more information.
+     * See @ref GlossCompress "Compressing distributed objects" for more
+     * information.
      */
     void compress (::dealii::VectorOperation::values operation);
 
@@ -1195,9 +1191,9 @@ namespace TrilinosWrappers
      *
      * Just as the respective call in deal.II SparseMatrix<Number> class (but
      * in contrast to the situation for PETSc based matrices), this function
-     * throws an exception if an entry does not exist in the sparsity
-     * pattern. Moreover, if <tt>value</tt> is not a finite number an
-     * exception is thrown.
+     * throws an exception if an entry does not exist in the sparsity pattern.
+     * Moreover, if <tt>value</tt> is not a finite number an exception is
+     * thrown.
      */
     void add (const size_type      i,
               const size_type      j,
@@ -1284,8 +1280,7 @@ namespace TrilinosWrappers
     SparseMatrix &operator /= (const TrilinosScalar factor);
 
     /**
-     * Copy the given (Trilinos) matrix
-     * (sparsity pattern and entries).
+     * Copy the given (Trilinos) matrix (sparsity pattern and entries).
      */
     void copy_from (const SparseMatrix &source);
 
@@ -1346,11 +1341,11 @@ namespace TrilinosWrappers
 
     /**
      * Return the value of the entry (<i>i,j</i>).  This may be an expensive
-     * operation and you should always take care where to call this
-     * function. As in the deal.II sparse matrix class, we throw an exception
-     * if the respective entry doesn't exist in the sparsity pattern of this
-     * class, which is requested from Trilinos. Moreover, an exception will be
-     * thrown when the requested element is not saved on the calling process.
+     * operation and you should always take care where to call this function.
+     * As in the deal.II sparse matrix class, we throw an exception if the
+     * respective entry doesn't exist in the sparsity pattern of this class,
+     * which is requested from Trilinos. Moreover, an exception will be thrown
+     * when the requested element is not saved on the calling process.
      */
     TrilinosScalar operator () (const size_type i,
                                 const size_type j) const;
@@ -1458,8 +1453,8 @@ namespace TrilinosWrappers
      *
      * In case of a localized Vector (i.e., TrilinosWrappers::Vector or
      * Vector<double>), this function will only work when running on one
-     * processor, since the matrix object is inherently
-     * distributed. Otherwise, and exception will be thrown.
+     * processor, since the matrix object is inherently distributed.
+     * Otherwise, and exception will be thrown.
      *
      */
     template<typename VectorType>
@@ -1486,8 +1481,8 @@ namespace TrilinosWrappers
      *
      * In case of a localized Vector (i.e., TrilinosWrappers::Vector or
      * Vector<double>), this function will only work when running on one
-     * processor, since the matrix object is inherently
-     * distributed. Otherwise, and exception will be thrown.
+     * processor, since the matrix object is inherently distributed.
+     * Otherwise, and exception will be thrown.
      */
     template <typename VectorType>
     void Tvmult_add (VectorType       &dst,
@@ -1562,40 +1557,40 @@ namespace TrilinosWrappers
                              const VectorBase &b) const;
 
     /**
-    * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
-    * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
-    * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
-    *
-    * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
-    * have compatible sizes. The size of <tt>C</tt> will be set within this
-    * function.
-    *
-    * The content as well as the sparsity pattern of the matrix C will be
-    * changed by this function, so make sure that the sparsity pattern is not
-    * used somewhere else in your program. This is an expensive operation, so
-    * think twice before you use this function.
-    */
+     * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
+     * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
+     * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+     *
+     * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+     * have compatible sizes. The size of <tt>C</tt> will be set within this
+     * function.
+     *
+     * The content as well as the sparsity pattern of the matrix C will be
+     * changed by this function, so make sure that the sparsity pattern is not
+     * used somewhere else in your program. This is an expensive operation, so
+     * think twice before you use this function.
+     */
     void mmult (SparseMatrix       &C,
                 const SparseMatrix &B,
                 const VectorBase   &V = VectorBase()) const;
 
 
     /**
-    * Perform the matrix-matrix multiplication with the transpose of
-    * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
-    * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>,
-    * where <tt>diag(V)</tt> defines a diagonal matrix with the vector
-    * entries.
-    *
-    * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
-    * have compatible sizes. The size of <tt>C</tt> will be set within this
-    * function.
-    *
-    * The content as well as the sparsity pattern of the matrix C will be
-    * changed by this function, so make sure that the sparsity pattern is not
-    * used somewhere else in your program. This is an expensive operation, so
-    * think twice before you use this function.
-    */
+     * Perform the matrix-matrix multiplication with the transpose of
+     * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
+     * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>,
+     * where <tt>diag(V)</tt> defines a diagonal matrix with the vector
+     * entries.
+     *
+     * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+     * have compatible sizes. The size of <tt>C</tt> will be set within this
+     * function.
+     *
+     * The content as well as the sparsity pattern of the matrix C will be
+     * changed by this function, so make sure that the sparsity pattern is not
+     * used somewhere else in your program. This is an expensive operation, so
+     * think twice before you use this function.
+     */
     void Tmmult (SparseMatrix       &C,
                  const SparseMatrix &B,
                  const VectorBase   &V = VectorBase()) const;
@@ -1768,7 +1763,8 @@ namespace TrilinosWrappers
                 const bool    write_extended_trilinos_info = false) const;
 
 //@}
-    /** @addtogroup Exceptions
+    /**
+     * @addtogroup Exceptions
      *
      */
 //@{
@@ -1825,21 +1821,22 @@ namespace TrilinosWrappers
   protected:
 
     /**
-    * For some matrix storage formats, in particular for the PETSc distributed
-    * blockmatrices, set and add operations on individual elements can not be
-    * freely mixed. Rather, one has to synchronize operations when one wants
-    * to switch from setting elements to adding to elements.  BlockMatrixBase
-    * automatically synchronizes the access by calling this helper function
-    * for each block.  This function ensures that the matrix is in a state
-    * that allows adding elements; if it previously already was in this state,
-    * the function does nothing.
-    */
+     * For some matrix storage formats, in particular for the PETSc
+     * distributed blockmatrices, set and add operations on individual
+     * elements can not be freely mixed. Rather, one has to synchronize
+     * operations when one wants to switch from setting elements to adding to
+     * elements.  BlockMatrixBase automatically synchronizes the access by
+     * calling this helper function for each block.  This function ensures
+     * that the matrix is in a state that allows adding elements; if it
+     * previously already was in this state, the function does nothing.
+     */
     void prepare_add();
 
     /**
-    * Same as prepare_add() but prepare the matrix for setting elements if the
-    * representation of elements in this class requires such an operation.
-    */
+     * Same as prepare_add() but prepare the matrix for setting elements if
+     * the representation of elements in this class requires such an
+     * operation.
+     */
     void prepare_set();
 
 
@@ -1860,9 +1857,9 @@ namespace TrilinosWrappers
     std_cxx11::shared_ptr<Epetra_FECrsMatrix> matrix;
 
     /**
-     * A sparse matrix object in Trilinos to be used for collecting the
-     * non-local elements if the matrix was constructed from a Trilinos
-     * sparsity pattern with the respective option.
+     * A sparse matrix object in Trilinos to be used for collecting the non-
+     * local elements if the matrix was constructed from a Trilinos sparsity
+     * pattern with the respective option.
      */
     std_cxx11::shared_ptr<Epetra_CrsMatrix> nonlocal_matrix;
 
@@ -1891,7 +1888,7 @@ namespace TrilinosWrappers
     bool compressed;
 
     /**
-     *  To allow calling protected prepare_add() and prepare_set().
+     * To allow calling protected prepare_add() and prepare_set().
      */
     friend class BlockMatrixBase<SparseMatrix>;
   };
index 450c5dc8f19b3d102645d7e06ec2e57eef85c6f8..6f82725df358c3e6f7390667f4a70664304ba7a9 100644 (file)
@@ -59,13 +59,13 @@ namespace TrilinosWrappers
     class Iterator;
 
     /**
-     * Accessor class for iterators into sparsity patterns. This class is
-     * also the base class for both const and non-const accessor classes
-     * into sparse matrices.
+     * Accessor class for iterators into sparsity patterns. This class is also
+     * the base class for both const and non-const accessor classes into
+     * sparse matrices.
      *
      * Note that this class only allows read access to elements, providing
-     * their row and column number. It does not allow modifying the
-     * sparsity pattern itself.
+     * their row and column number. It does not allow modifying the sparsity
+     * pattern itself.
      *
      * @ingroup TrilinosWrappers
      * @author Wolfgang Bangerth, Martin Kronbichler, Guido Kanschat
@@ -165,9 +165,9 @@ namespace TrilinosWrappers
     };
 
     /**
-     * Iterator class for sparsity patterns of type TrilinosWrappers::SparsityPattern.
-     * Access to individual elements of the sparsity pattern is handled by the
-     * Accessor class in this namespace.
+     * Iterator class for sparsity patterns of type
+     * TrilinosWrappers::SparsityPattern. Access to individual elements of the
+     * sparsity pattern is handled by the Accessor class in this namespace.
      */
     class Iterator
     {
@@ -252,10 +252,10 @@ namespace TrilinosWrappers
   /**
    * This class implements a wrapper class to use the Trilinos distributed
    * sparsity pattern class Epetra_FECrsGraph. This class is designed to be
-   * used for construction of %parallel Trilinos matrices. The functionality of
-   * this class is modeled after the existing sparsity pattern classes, with
-   * the difference that this class can work fully in %parallel according to a
-   * partitioning of the sparsity pattern rows.
+   * used for construction of %parallel Trilinos matrices. The functionality
+   * of this class is modeled after the existing sparsity pattern classes,
+   * with the difference that this class can work fully in %parallel according
+   * to a partitioning of the sparsity pattern rows.
    *
    * This class has many similarities to the compressed sparsity pattern
    * classes of deal.II (i.e., the classes CompressedSparsityPattern,
@@ -279,8 +279,7 @@ namespace TrilinosWrappers
     typedef dealii::types::global_dof_index size_type;
 
     /**
-     * Declare a typedef for the
-     * iterator class.
+     * Declare a typedef for the iterator class.
      */
     typedef SparsityPatternIterators::Iterator const_iterator;
 
@@ -415,10 +414,10 @@ namespace TrilinosWrappers
     /**
      * Constructor for a square sparsity pattern using an Epetra_map for the
      * description of the %parallel partitioning. Moreover, the number of
-     * nonzero entries in the rows of the sparsity pattern can be
-     * specified. Note that this number does not need to be exact, and it is
-     * allowed that the actual sparsity structure has more nonzero entries
-     * than specified in the constructor (the usual case when the function
+     * nonzero entries in the rows of the sparsity pattern can be specified.
+     * Note that this number does not need to be exact, and it is allowed that
+     * the actual sparsity structure has more nonzero entries than specified
+     * in the constructor (the usual case when the function
      * DoFTools::make_sparsity_pattern() is called). However it is still
      * advantageous to provide good estimates here since a good value will
      * avoid repeated allocation of memory, which considerably increases the
@@ -428,14 +427,14 @@ namespace TrilinosWrappers
                      const size_type   n_entries_per_row = 0);
 
     /**
-     * Same as before, but now use the exact number of nonzeros in each m
-     * row. Since we know the number of elements in the sparsity pattern
-     * exactly in this case, we can already allocate the right amount of
-     * memory, which makes the creation process by the respective
-     * SparsityPattern::reinit call considerably faster. However, this is a
-     * rather unusual situation, since knowing the number of entries in each
-     * row is usually connected to knowing the indices of nonzero entries,
-     * which the sparsity pattern is designed to describe.
+     * Same as before, but now use the exact number of nonzeros in each m row.
+     * Since we know the number of elements in the sparsity pattern exactly in
+     * this case, we can already allocate the right amount of memory, which
+     * makes the creation process by the respective SparsityPattern::reinit
+     * call considerably faster. However, this is a rather unusual situation,
+     * since knowing the number of entries in each row is usually connected to
+     * knowing the indices of nonzero entries, which the sparsity pattern is
+     * designed to describe.
      */
     SparsityPattern (const Epetra_Map             &parallel_partitioning,
                      const std::vector<size_type> &n_entries_per_row);
@@ -478,13 +477,12 @@ namespace TrilinosWrappers
     /**
      * Reinitialization function for generating a square sparsity pattern
      * using an Epetra_Map for the description of the %parallel partitioning
-     * and the number of nonzero entries in the rows of the sparsity
-     * pattern. Note that this number does not need to be exact, and it is
-     * even allowed that the actual sparsity structure has more nonzero
-     * entries than specified in the constructor. However it is still
-     * advantageous to provide good estimates here since this will
-     * considerably increase the performance when creating the sparsity
-     * pattern.
+     * and the number of nonzero entries in the rows of the sparsity pattern.
+     * Note that this number does not need to be exact, and it is even allowed
+     * that the actual sparsity structure has more nonzero entries than
+     * specified in the constructor. However it is still advantageous to
+     * provide good estimates here since this will considerably increase the
+     * performance when creating the sparsity pattern.
      *
      * This function does not create any entries by itself, but provides the
      * correct data structures that can be used by the respective add()
@@ -495,14 +493,14 @@ namespace TrilinosWrappers
             const size_type   n_entries_per_row = 0);
 
     /**
-     * Same as before, but now use the exact number of nonzeros in each m
-     * row. Since we know the number of elements in the sparsity pattern
-     * exactly in this case, we can already allocate the right amount of
-     * memory, which makes process of adding entries to the sparsity pattern
-     * considerably faster. However, this is a rather unusual situation, since
-     * knowing the number of entries in each row is usually connected to
-     * knowing the indices of nonzero entries, which the sparsity pattern is
-     * designed to describe.
+     * Same as before, but now use the exact number of nonzeros in each m row.
+     * Since we know the number of elements in the sparsity pattern exactly in
+     * this case, we can already allocate the right amount of memory, which
+     * makes process of adding entries to the sparsity pattern considerably
+     * faster. However, this is a rather unusual situation, since knowing the
+     * number of entries in each row is usually connected to knowing the
+     * indices of nonzero entries, which the sparsity pattern is designed to
+     * describe.
      */
     void
     reinit (const Epetra_Map             &parallel_partitioning,
@@ -581,29 +579,28 @@ namespace TrilinosWrappers
 
     /**
      * Constructor for a square sparsity pattern using an IndexSet and an MPI
-     * communicator for the description of the %parallel
-     * partitioning. Moreover, the number of nonzero entries in the rows of
-     * the sparsity pattern can be specified. Note that this number does not
-     * need to be exact, and it is even allowed that the actual sparsity
-     * structure has more nonzero entries than specified in the
-     * constructor. However it is still advantageous to provide good estimates
-     * here since a good value will avoid repeated allocation of memory, which
-     * considerably increases the performance when creating the sparsity
-     * pattern.
+     * communicator for the description of the %parallel partitioning.
+     * Moreover, the number of nonzero entries in the rows of the sparsity
+     * pattern can be specified. Note that this number does not need to be
+     * exact, and it is even allowed that the actual sparsity structure has
+     * more nonzero entries than specified in the constructor. However it is
+     * still advantageous to provide good estimates here since a good value
+     * will avoid repeated allocation of memory, which considerably increases
+     * the performance when creating the sparsity pattern.
      */
     SparsityPattern (const IndexSet  &parallel_partitioning,
                      const MPI_Comm  &communicator = MPI_COMM_WORLD,
                      const size_type  n_entries_per_row = 0);
 
     /**
-     * Same as before, but now use the exact number of nonzeros in each m
-     * row. Since we know the number of elements in the sparsity pattern
-     * exactly in this case, we can already allocate the right amount of
-     * memory, which makes the creation process by the respective
-     * SparsityPattern::reinit call considerably faster. However, this is a
-     * rather unusual situation, since knowing the number of entries in each
-     * row is usually connected to knowing the indices of nonzero entries,
-     * which the sparsity pattern is designed to describe.
+     * Same as before, but now use the exact number of nonzeros in each m row.
+     * Since we know the number of elements in the sparsity pattern exactly in
+     * this case, we can already allocate the right amount of memory, which
+     * makes the creation process by the respective SparsityPattern::reinit
+     * call considerably faster. However, this is a rather unusual situation,
+     * since knowing the number of entries in each row is usually connected to
+     * knowing the indices of nonzero entries, which the sparsity pattern is
+     * designed to describe.
      */
     SparsityPattern (const IndexSet                  &parallel_partitioning,
                      const MPI_Comm                  &communicator,
@@ -645,11 +642,11 @@ namespace TrilinosWrappers
                      const std::vector<size_type> &n_entries_per_row);
 
     /**
-     * This constructor constructs general sparsity patterns, possible
-     * non-square ones. Constructing a sparsity pattern this way allows the
-     * user to explicitly specify the rows into which we are going to add
-     * elements. This set is required to be a superset of the first index set
-     * @p row_parallel_partitioning that includes also rows that are owned by
+     * This constructor constructs general sparsity patterns, possible non-
+     * square ones. Constructing a sparsity pattern this way allows the user
+     * to explicitly specify the rows into which we are going to add elements.
+     * This set is required to be a superset of the first index set @p
+     * row_parallel_partitioning that includes also rows that are owned by
      * another processor (ghost rows). Note that elements can only be added to
      * rows specified by @p writable_rows.
      *
@@ -697,14 +694,14 @@ namespace TrilinosWrappers
             const size_type  n_entries_per_row = 0);
 
     /**
-     * Same as before, but now use the exact number of nonzeros in each m
-     * row. Since we know the number of elements in the sparsity pattern
-     * exactly in this case, we can already allocate the right amount of
-     * memory, which makes process of adding entries to the sparsity pattern
-     * considerably faster. However, this is a rather unusual situation, since
-     * knowing the number of entries in each row is usually connected to
-     * knowing the indices of nonzero entries, which the sparsity pattern is
-     * designed to describe.
+     * Same as before, but now use the exact number of nonzeros in each m row.
+     * Since we know the number of elements in the sparsity pattern exactly in
+     * this case, we can already allocate the right amount of memory, which
+     * makes process of adding entries to the sparsity pattern considerably
+     * faster. However, this is a rather unusual situation, since knowing the
+     * number of entries in each row is usually connected to knowing the
+     * indices of nonzero entries, which the sparsity pattern is designed to
+     * describe.
      */
     void
     reinit (const IndexSet               &parallel_partitioning,
@@ -734,12 +731,12 @@ namespace TrilinosWrappers
             const size_type  n_entries_per_row = 0);
 
     /**
-     * This reinit function is used to specify general matrices, possibly
-     * non-square ones. In addition to the arguments of the other reinit
-     * method above, it allows the user to explicitly specify the rows into
-     * which we are going to add elements. This set is a superset of the first
-     * index set @p row_parallel_partitioning that includes also rows that are
-     * owned by another processor (ghost rows).
+     * This reinit function is used to specify general matrices, possibly non-
+     * square ones. In addition to the arguments of the other reinit method
+     * above, it allows the user to explicitly specify the rows into which we
+     * are going to add elements. This set is a superset of the first index
+     * set @p row_parallel_partitioning that includes also rows that are owned
+     * by another processor (ghost rows).
      *
      * This method is beneficial when the rows to which a processor is going
      * to write can be determined before actually inserting elements into the
@@ -748,10 +745,10 @@ namespace TrilinosWrappers
      * what we call the locally relevant dofs (see
      * DoFTools::extract_locally_relevant_dofs). Trilinos matrices allow to
      * add elements to arbitrary rows (as done by all the other reinit
-     * functions) and this is what all the other reinit methods do,
-     * too. However, this flexbility come at a cost, the most prominent being
-     * that adding elements into the same matrix from multiple threads in
-     * shared memory is not safe whenever MPI is used. For these settings, the
+     * functions) and this is what all the other reinit methods do, too.
+     * However, this flexbility come at a cost, the most prominent being that
+     * adding elements into the same matrix from multiple threads in shared
+     * memory is not safe whenever MPI is used. For these settings, the
      * current method is the one to choose: It will store the off-processor
      * data as an additional sparsity pattern (that is then passed to the
      * Trilinos matrix via the reinit mehtod) which can be organized in such a
@@ -941,8 +938,8 @@ namespace TrilinosWrappers
     /**
      * Return a const reference to the underlying Trilinos Epetra_Map that
      * sets the partitioning of the range space of this sparsity pattern,
-     * i.e., the partitioning of the vectors that are result from
-     * matrix-vector products.
+     * i.e., the partitioning of the vectors that are result from matrix-
+     * vector products.
      */
     const Epetra_Map &range_partitioner () const;
 
@@ -1041,8 +1038,10 @@ namespace TrilinosWrappers
     void print_gnuplot (std::ostream &out) const;
 
 //@}
-    /** @addtogroup Exceptions
-     * @{ */
+    /**
+     * @addtogroup Exceptions
+     * @{
+     */
     /**
      * Exception
      */
@@ -1102,7 +1101,9 @@ namespace TrilinosWrappers
 
     /**
      * A sparsity pattern object for the non-local part of the sparsity
-     * pattern that is going to be sent to the owning processor. Only used when the particular constructor or reinit method with writable_rows argument is set
+     * pattern that is going to be sent to the owning processor. Only used
+     * when the particular constructor or reinit method with writable_rows
+     * argument is set
      */
     std_cxx11::shared_ptr<Epetra_CrsGraph> nonlocal_graph;
 
index 6e3b20a4ebf11eee73f2edda5e32970809d4b887..e0007309f8e8363af70e16cd48e5ed70c1d05a67 100644 (file)
@@ -40,7 +40,7 @@ template <typename> class Vector;
 
 /**
  * @addtogroup TrilinosWrappers
- *@{
+ * @{
  */
 namespace TrilinosWrappers
 {
@@ -68,9 +68,9 @@ namespace TrilinosWrappers
   }
 
   /**
-   * Namespace for Trilinos vector classes that work in parallel over
-   * MPI. This namespace is restricted to vectors only, whereas matrices
-   * are always MPI based when run on more than one processor.
+   * Namespace for Trilinos vector classes that work in parallel over MPI.
+   * This namespace is restricted to vectors only, whereas matrices are always
+   * MPI based when run on more than one processor.
    *
    * @ingroup TrilinosWrappers
    * @author Martin Kronbichler, Wolfgang Bangerth, 2008
@@ -80,78 +80,77 @@ namespace TrilinosWrappers
     class BlockVector;
 
     /**
-     * This class implements a wrapper to use the Trilinos distributed
-     * vector class Epetra_FEVector. This class is derived from the
+     * This class implements a wrapper to use the Trilinos distributed vector
+     * class Epetra_FEVector. This class is derived from the
      * TrilinosWrappers::VectorBase class and provides all functionality
      * included there.
      *
      * Note that Trilinos only guarantees that operations do what you expect
-     * if the function @p GlobalAssemble has been called after vector
-     * assembly in order to distribute the data. This is necessary since
-     * some processes might have accumulated data of elements that are not
-     * owned by themselves, but must be sent to the owning process. In order
-     * to avoid using the wrong data, you need to call Vector::compress()
-     * before you actually use the vectors.
+     * if the function @p GlobalAssemble has been called after vector assembly
+     * in order to distribute the data. This is necessary since some processes
+     * might have accumulated data of elements that are not owned by
+     * themselves, but must be sent to the owning process. In order to avoid
+     * using the wrong data, you need to call Vector::compress() before you
+     * actually use the vectors.
      *
      * <h3>Parallel communication model</h3>
      *
      * The parallel functionality of Trilinos is built on top of the Message
      * Passing Interface (MPI). MPI's communication model is built on
-     * collective communications: if one process wants something from
-     * another, that other process has to be willing to accept this
-     * communication. A process cannot query data from another process by
-     * calling a remote function, without that other process expecting such
-     * a transaction. The consequence is that most of the operations in the
-     * base class of this class have to be called collectively. For example,
-     * if you want to compute the l2 norm of a parallel vector, @em all
-     * processes across which this vector is shared have to call the @p
-     * l2_norm function. If you don't do this, but instead only call the @p
-     * l2_norm function on one process, then the following happens: This one
-     * process will call one of the collective MPI functions and wait for
-     * all the other processes to join in on this. Since the other processes
-     * don't call this function, you will either get a time-out on the first
-     * process, or, worse, by the time the next a callto a Trilinos function
-     * generates an MPI message on the other processes, you will get a
-     * cryptic message that only a subset of processes attempted a
-     * communication. These bugs can be very hard to figure out, unless you
-     * are well-acquainted with the communication model of MPI, and know
-     * which functions may generate MPI messages.
+     * collective communications: if one process wants something from another,
+     * that other process has to be willing to accept this communication. A
+     * process cannot query data from another process by calling a remote
+     * function, without that other process expecting such a transaction. The
+     * consequence is that most of the operations in the base class of this
+     * class have to be called collectively. For example, if you want to
+     * compute the l2 norm of a parallel vector, @em all processes across
+     * which this vector is shared have to call the @p l2_norm function. If
+     * you don't do this, but instead only call the @p l2_norm function on one
+     * process, then the following happens: This one process will call one of
+     * the collective MPI functions and wait for all the other processes to
+     * join in on this. Since the other processes don't call this function,
+     * you will either get a time-out on the first process, or, worse, by the
+     * time the next a callto a Trilinos function generates an MPI message on
+     * the other processes, you will get a cryptic message that only a subset
+     * of processes attempted a communication. These bugs can be very hard to
+     * figure out, unless you are well-acquainted with the communication model
+     * of MPI, and know which functions may generate MPI messages.
      *
-     * One particular case, where an MPI message may be generated
-     * unexpectedly is discussed below.
+     * One particular case, where an MPI message may be generated unexpectedly
+     * is discussed below.
      *
      *
      * <h3>Accessing individual elements of a vector</h3>
      *
-     * Trilinos does of course allow read access to individual
-     * elements of a vector, but in the distributed case only to
-     * elements that are stored locally. We implement this through
-     * calls like <tt>d=vec(i)</tt>. However, if you access an element
-     * outside the locally stored range, an exception is generated.
+     * Trilinos does of course allow read access to individual elements of a
+     * vector, but in the distributed case only to elements that are stored
+     * locally. We implement this through calls like <tt>d=vec(i)</tt>.
+     * However, if you access an element outside the locally stored range, an
+     * exception is generated.
      *
      * In contrast to read access, Trilinos (and the respective deal.II
      * wrapper classes) allow to write (or add) to individual elements of
      * vectors, even if they are stored on a different process. You can do
      * this by writing into or adding to elements using the syntax
-     * <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>,
-     * or similar operations. There is one catch, however, that may lead to
-     * very confusing error messages: Trilinos requires application programs
-     * to call the compress() function when they switch from performing a set of
-     * operations that add to elements, to performing a set of operations
-     * that write to elements. The reasoning is that all processes
-     * might accumulate addition operations to elements, even if multiple
-     * processes write to the same elements. By the time we call compress()
-     * the next time, all these additions are executed. However, if one
-     * process adds to an element, and another overwrites to it, the order
-     * of execution would yield non-deterministic behavior if we don't make
-     * sure that a synchronization with compress() happens in between.
+     * <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or similar operations. There
+     * is one catch, however, that may lead to very confusing error messages:
+     * Trilinos requires application programs to call the compress() function
+     * when they switch from performing a set of operations that add to
+     * elements, to performing a set of operations that write to elements. The
+     * reasoning is that all processes might accumulate addition operations to
+     * elements, even if multiple processes write to the same elements. By the
+     * time we call compress() the next time, all these additions are
+     * executed. However, if one process adds to an element, and another
+     * overwrites to it, the order of execution would yield non-deterministic
+     * behavior if we don't make sure that a synchronization with compress()
+     * happens in between.
      *
      * In order to make sure these calls to compress() happen at the
-     * appropriate time, the deal.II wrappers keep a state variable that
-     * store which is the presently allowed operation: additions or
-     * writes. If it encounters an operation of the opposite kind, it calls
-     * compress() and flips the state. This can sometimes lead to very
-     * confusing behavior, in code that may for example look like this:
+     * appropriate time, the deal.II wrappers keep a state variable that store
+     * which is the presently allowed operation: additions or writes. If it
+     * encounters an operation of the opposite kind, it calls compress() and
+     * flips the state. This can sometimes lead to very confusing behavior, in
+     * code that may for example look like this:
      *
      * @code
      * TrilinosWrappers::Vector vector;
@@ -171,17 +170,16 @@ namespace TrilinosWrappers
      *
      * This code can run into trouble: by the time we see the first addition
      * operation, we need to flush the overwrite buffers for the vector, and
-     * the deal.II library will do so by calling compress(). However, it
-     * will only do so for all processes that actually do an addition -- if
-     * the condition is never true for one of the processes, then this one
-     * will not get to the actual compress() call, whereas all the other
-     * ones do. This gets us into trouble, since all the other processes
-     * hang in the call to flush the write buffers, while the one other
-     * process advances to the call to compute the l2 norm. At this time,
-     * you will get an error that some operation was attempted by only a
-     * subset of processes. This behavior may seem surprising, unless you
-     * know that write/addition operations on single elements may trigger
-     * this behavior.
+     * the deal.II library will do so by calling compress(). However, it will
+     * only do so for all processes that actually do an addition -- if the
+     * condition is never true for one of the processes, then this one will
+     * not get to the actual compress() call, whereas all the other ones do.
+     * This gets us into trouble, since all the other processes hang in the
+     * call to flush the write buffers, while the one other process advances
+     * to the call to compute the l2 norm. At this time, you will get an error
+     * that some operation was attempted by only a subset of processes. This
+     * behavior may seem surprising, unless you know that write/addition
+     * operations on single elements may trigger this behavior.
      *
      * The problem described here may be avoided by placing additional calls
      * to compress(), or making sure that all processes do the same type of
@@ -194,41 +192,41 @@ namespace TrilinosWrappers
      * Parallel vectors come in two kinds: without and with ghost elements.
      * Vectors without ghost elements uniquely partition the vector elements
      * between processors: each vector entry has exactly one processor that
-     * owns it. For such vectors, you can read those elements that
-     * the processor you are currently on owns, and you can write into
-     * any element whether you own it or not: if you don't own it, the
-     * value written or added to a vector element will be shipped to the
-     * processor that owns this vector element the next time you call
-     * compress(), as described above.
+     * owns it. For such vectors, you can read those elements that the
+     * processor you are currently on owns, and you can write into any element
+     * whether you own it or not: if you don't own it, the value written or
+     * added to a vector element will be shipped to the processor that owns
+     * this vector element the next time you call compress(), as described
+     * above.
      *
-     * What we call a 'ghosted' vector (see
-     * @ref GlossGhostedVector "vectors with ghost elements")
-     * is simply a view of the
-     * parallel vector where the element distributions overlap. The 'ghosted'
-     * Trilinos vector in itself has no idea of which entries are ghosted and
-     * which are locally owned. In fact, a ghosted vector
-     * may not even store all of the elements a non-ghosted vector would
-     * store on the current processor.  Consequently, for Trilinos vectors,
-     * there is no notion of an 'owner' of vector elements in the way we
-     * have it in the the non-ghost case view.
+     * What we call a 'ghosted' vector (see @ref GlossGhostedVector "vectors
+     * with ghost elements") is simply a view of the parallel vector where the
+     * element distributions overlap. The 'ghosted' Trilinos vector in itself
+     * has no idea of which entries are ghosted and which are locally owned.
+     * In fact, a ghosted vector may not even store all of the elements a non-
+     * ghosted vector would store on the current processor.  Consequently, for
+     * Trilinos vectors, there is no notion of an 'owner' of vector elements
+     * in the way we have it in the the non-ghost case view.
      *
      * This explains why we do not allow writing into ghosted vectors on the
      * Trilinos side: Who would be responsible for taking care of the
      * duplicated entries, given that there is not such information as locally
-     * owned indices? In other words, since a processor doesn't know which other
-     * processors own an element, who would it send a value to if one were to write
-     * to it? The only possibility would be to send this information to <i>all</i>
-     * other processors, but that is clearly not practical. Thus, we only allow
-     * reading from ghosted vectors, which however we do very often.
+     * owned indices? In other words, since a processor doesn't know which
+     * other processors own an element, who would it send a value to if one
+     * were to write to it? The only possibility would be to send this
+     * information to <i>all</i> other processors, but that is clearly not
+     * practical. Thus, we only allow reading from ghosted vectors, which
+     * however we do very often.
      *
      * So how do you fill a ghosted vector if you can't write to it? This only
-     * happens through the assignment with a non-ghosted vector. It can go both ways
-     * (non-ghosted is assigned to a ghosted vector, and a ghosted vector is assigned
-     * to a non-ghosted one; the latter one typically only requires taking out
-     * the locally owned part as most often ghosted vectors store a superset of
-     * elements of non-ghosted ones). In general, you send data around with that
-     * operation and it all depends on the different views of the two vectors.
-     * Trilinos also allows you to get subvectors out of a big vector that way.
+     * happens through the assignment with a non-ghosted vector. It can go
+     * both ways (non-ghosted is assigned to a ghosted vector, and a ghosted
+     * vector is assigned to a non-ghosted one; the latter one typically only
+     * requires taking out the locally owned part as most often ghosted
+     * vectors store a superset of elements of non-ghosted ones). In general,
+     * you send data around with that operation and it all depends on the
+     * different views of the two vectors. Trilinos also allows you to get
+     * subvectors out of a big vector that way.
      *
      *
      * <h3>Thread safety of Trilinos vectors</h3>
@@ -337,8 +335,8 @@ namespace TrilinosWrappers
        * Copy operator from a given localized vector (present on all
        * processes) in TrilinosWrappers format to the current distributed
        * vector. This function assumes that the calling vector (left hand
-       * object) already is of the same size as the right hand side
-       * vector. Otherwise, an exception will be thrown.
+       * object) already is of the same size as the right hand side vector.
+       * Otherwise, an exception will be thrown.
        */
       Vector &
       operator = (const ::dealii::TrilinosWrappers::Vector &V);
@@ -368,9 +366,9 @@ namespace TrilinosWrappers
        * then queried from the input vector. Note that you should not write to
        * the resulting vector any more, since the some data can be stored
        * several times on different processors, leading to unpredictable
-       * results. In particular, such a vector cannot be used for
-       * matrix-vector products as for example done during the solution of
-       * linear systems.
+       * results. In particular, such a vector cannot be used for matrix-
+       * vector products as for example done during the solution of linear
+       * systems.
        */
       void import_nonlocal_data_for_fe
       (const dealii::TrilinosWrappers::SparseMatrix &matrix,
@@ -387,9 +385,9 @@ namespace TrilinosWrappers
        * all we need to generate a parallel vector.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -402,9 +400,9 @@ namespace TrilinosWrappers
        * sets the partitioning details.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -416,9 +414,9 @@ namespace TrilinosWrappers
        * %parallel partitioning.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -431,9 +429,9 @@ namespace TrilinosWrappers
        * and generates a new one based on the input map.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -445,9 +443,9 @@ namespace TrilinosWrappers
        * the given vector, and copies all elements.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -466,9 +464,9 @@ namespace TrilinosWrappers
        * need to generate a %parallel vector.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -478,10 +476,10 @@ namespace TrilinosWrappers
       /**
        * Creates a ghosted parallel vector.
        *
-       * Depending on whether the @p ghost argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * Depending on whether the @p ghost argument uniquely subdivides
+       * elements among processors or not, the resulting vector may or may not
+       * have ghost elements. See the general documentation of this class for
+       * more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -496,9 +494,9 @@ namespace TrilinosWrappers
        * MPI communicator that set the partitioning details.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -511,9 +509,9 @@ namespace TrilinosWrappers
        * the given vector, and copies all the elements.
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -530,9 +528,9 @@ namespace TrilinosWrappers
        *
        *
        * Depending on whether the @p parallel_partitioning argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -544,14 +542,13 @@ namespace TrilinosWrappers
        * Reinit functionality. This function destroys the old vector content
        * and generates a new one based on the input partitioning. In addition
        * to just specifying one index set as in all the other methods above,
-       * this method allows to supply an additional set of ghost
-       * entries. There are two different versions of a vector that can be
-       * created. If the flag @p vector_writable is set to @p false, the
-       * vector only allows read access to the joint set of @p
-       * parallel_partitioning and @p ghost_entries. The effect of the reinit
-       * method is then equivalent to calling the other reinit method with an
-       * index set containing both the locally owned entries and the ghost
-       * entries.
+       * this method allows to supply an additional set of ghost entries.
+       * There are two different versions of a vector that can be created. If
+       * the flag @p vector_writable is set to @p false, the vector only
+       * allows read access to the joint set of @p parallel_partitioning and
+       * @p ghost_entries. The effect of the reinit method is then equivalent
+       * to calling the other reinit method with an index set containing both
+       * the locally owned entries and the ghost entries.
        *
        * If the flag @p vector_writable is set to true, this creates an
        * alternative storage scheme for ghost elements that allows multiple
@@ -559,9 +556,9 @@ namespace TrilinosWrappers
        * one thread is allowed to write into the ghost entries at a time).
        *
        * Depending on whether the @p ghost_entries argument uniquely
-       * subdivides elements among processors or not, the resulting vector
-       * may or may not have ghost elements. See the general documentation of
-       * this class for more information.
+       * subdivides elements among processors or not, the resulting vector may
+       * or may not have ghost elements. See the general documentation of this
+       * class for more information.
        *
        * @see @ref GlossGhostedVector "vectors with ghost elements"
        */
@@ -579,9 +576,9 @@ namespace TrilinosWrappers
 
 
     /**
-     * Global function @p swap which overloads the default implementation
-     * of the C++ standard library which uses a temporary object. The
-     * function simply exchanges the data of the two vectors.
+     * Global function @p swap which overloads the default implementation of
+     * the C++ standard library which uses a temporary object. The function
+     * simply exchanges the data of the two vectors.
      *
      * @relates TrilinosWrappers::MPI::Vector
      * @author Martin Kronbichler, Wolfgang Bangerth, 2008
@@ -673,10 +670,10 @@ namespace TrilinosWrappers
 
   /**
    * This class is a specialization of a Trilinos vector to a localized
-   * version. The purpose of this class is to provide a copy interface
-   * from the possibly parallel Vector class to a local vector on each
-   * processor, in order to be able to access all elements in the vector
-   * or to apply certain deal.II functions.
+   * version. The purpose of this class is to provide a copy interface from
+   * the possibly parallel Vector class to a local vector on each processor,
+   * in order to be able to access all elements in the vector or to apply
+   * certain deal.II functions.
    *
    * @ingroup TrilinosWrappers
    * @ingroup Vectors
@@ -715,24 +712,24 @@ namespace TrilinosWrappers
     explicit Vector (const size_type n);
 
     /**
-     * This constructor takes as input the number of elements in the
-     * vector. If the map is not localized, i.e., if there are some elements
-     * that are not present on all processes, only the global size of the map
-     * will be taken and a localized map will be generated internally.
-     * In other words, which element of the @p partitioning argument
-     * are set is in fact ignored, the only thing that matters is the size of
-     * the index space described by this argument.
+     * This constructor takes as input the number of elements in the vector.
+     * If the map is not localized, i.e., if there are some elements that are
+     * not present on all processes, only the global size of the map will be
+     * taken and a localized map will be generated internally. In other words,
+     * which element of the @p partitioning argument are set is in fact
+     * ignored, the only thing that matters is the size of the index space
+     * described by this argument.
      */
     explicit Vector (const Epetra_Map &partitioning);
 
     /**
-     * This constructor takes as input the number of elements in the
-     * vector. If the index set is not localized, i.e., if there are some
-     * elements that are not present on all processes, only the global size of
-     * the index set will be taken and a localized version will be generated
-     * internally. In other words, which element of the @p partitioning argument
-     * are set is in fact ignored, the only thing that matters is the size of
-     * the index space described by this argument.
+     * This constructor takes as input the number of elements in the vector.
+     * If the index set is not localized, i.e., if there are some elements
+     * that are not present on all processes, only the global size of the
+     * index set will be taken and a localized version will be generated
+     * internally. In other words, which element of the @p partitioning
+     * argument are set is in fact ignored, the only thing that matters is the
+     * size of the index space described by this argument.
      */
     explicit Vector (const IndexSet &partitioning,
                      const MPI_Comm &communicator = MPI_COMM_WORLD);
@@ -766,9 +763,9 @@ namespace TrilinosWrappers
      * <tt>fast</tt> determines whether the vector should be filled with zero
      * or left untouched.
      *
-     * Which element of the @p input_map argument
-     * are set is in fact ignored, the only thing that matters is the size of
-     * the index space described by this argument.
+     * Which element of the @p input_map argument are set is in fact ignored,
+     * the only thing that matters is the size of the index space described by
+     * this argument.
      */
     void reinit (const Epetra_Map &input_map,
                  const bool        fast = false);
@@ -782,9 +779,9 @@ namespace TrilinosWrappers
      * <tt>fast</tt> determines whether the vector should be filled with zero
      * (false) or left untouched (true).
      *
-     * Which element of the @p input_map argument
-     * are set is in fact ignored, the only thing that matters is the size of
-     * the index space described by this argument.
+     * Which element of the @p input_map argument are set is in fact ignored,
+     * the only thing that matters is the size of the index space described by
+     * this argument.
      */
     void reinit (const IndexSet   &input_map,
                  const MPI_Comm   &communicator = MPI_COMM_WORLD,
@@ -807,8 +804,8 @@ namespace TrilinosWrappers
     Vector &operator = (const TrilinosScalar s);
 
     /**
-     * Sets the left hand argument to the (parallel) Trilinos
-     * Vector. Equivalent to the @p reinit function.
+     * Sets the left hand argument to the (parallel) Trilinos Vector.
+     * Equivalent to the @p reinit function.
      */
     Vector &
     operator = (const MPI::Vector &V);
@@ -847,9 +844,9 @@ namespace TrilinosWrappers
 
 
   /**
-   * Global function @p swap which overloads the default implementation
-   * of the C++ standard library which uses a temporary object. The
-   * function simply exchanges the data of the two vectors.
+   * Global function @p swap which overloads the default implementation of the
+   * C++ standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates TrilinosWrappers::Vector
    * @author Martin Kronbichler, Wolfgang Bangerth, 2008
index 5fbdf728ec305168c9bbdebaa621fe8ea2953e1e..bc71a473540d070db1406c2a37b025d18ba9162c 100644 (file)
@@ -49,7 +49,7 @@ template <typename number> class Vector;
 
 /**
  * @addtogroup TrilinosWrappers
- *@{
+ * @{
  */
 namespace TrilinosWrappers
 {
@@ -61,8 +61,8 @@ namespace TrilinosWrappers
    */
 
   /**
-   * A namespace for internal implementation details of the
-   * TrilinosWrapper members.
+   * A namespace for internal implementation details of the TrilinosWrapper
+   * members.
    *
    * @ingroup TrilinosWrappers
    */
@@ -182,31 +182,29 @@ namespace TrilinosWrappers
 
 
   /**
-   * Base class for the two types of Trilinos vectors, the distributed
-   * memory vector MPI::Vector and a localized vector Vector. The latter
-   * is designed for use in either serial implementations or as a
-   * localized copy on each processor.  The implementation of this class
-   * is based on the Trilinos vector class Epetra_FEVector, the (parallel)
-   * partitioning of which is governed by an Epetra_Map. This means that
-   * the vector type is generic and can be done in this base class, while
-   * the definition of the partition map (and hence, the constructor and
-   * reinit function) will have to be done in the derived classes. The
-   * Epetra_FEVector is precisely the kind of vector we deal with all the
-   * time - we probably get it from some assembly process, where also
-   * entries not locally owned might need to written and hence need to be
-   * forwarded to the owner. The only requirement for this class to work
-   * is that Trilinos is installed with the same compiler as is used for
-   * compilation of deal.II.
+   * Base class for the two types of Trilinos vectors, the distributed memory
+   * vector MPI::Vector and a localized vector Vector. The latter is designed
+   * for use in either serial implementations or as a localized copy on each
+   * processor.  The implementation of this class is based on the Trilinos
+   * vector class Epetra_FEVector, the (parallel) partitioning of which is
+   * governed by an Epetra_Map. This means that the vector type is generic and
+   * can be done in this base class, while the definition of the partition map
+   * (and hence, the constructor and reinit function) will have to be done in
+   * the derived classes. The Epetra_FEVector is precisely the kind of vector
+   * we deal with all the time - we probably get it from some assembly
+   * process, where also entries not locally owned might need to written and
+   * hence need to be forwarded to the owner. The only requirement for this
+   * class to work is that Trilinos is installed with the same compiler as is
+   * used for compilation of deal.II.
    *
-   * The interface of this class is modeled after the existing Vector
-   * class in deal.II. It has almost the same member functions, and is
-   * often exchangable. However, since Trilinos only supports a single
-   * scalar type (double), it is not templated, and only works with that
-   * type.
+   * The interface of this class is modeled after the existing Vector class in
+   * deal.II. It has almost the same member functions, and is often
+   * exchangable. However, since Trilinos only supports a single scalar type
+   * (double), it is not templated, and only works with that type.
    *
-   * Note that Trilinos only guarantees that operations do what you expect
-   * if the function @p GlobalAssemble has been called after vector
-   * assembly in order to distribute the data. Therefore, you need to call
+   * Note that Trilinos only guarantees that operations do what you expect if
+   * the function @p GlobalAssemble has been called after vector assembly in
+   * order to distribute the data. Therefore, you need to call
    * Vector::compress() before you actually use the vectors.
    *
    * @ingroup TrilinosWrappers
@@ -267,10 +265,10 @@ namespace TrilinosWrappers
                  const bool        fast = false);
 
     /**
-     * Compress the underlying representation of the Trilinos object,
-     * i.e. flush the buffers of the vector object if it has any. This
-     * function is necessary after writing into a vector element-by-element
-     * and before anything else can be done on it.
+     * Compress the underlying representation of the Trilinos object, i.e.
+     * flush the buffers of the vector object if it has any. This function is
+     * necessary after writing into a vector element-by-element and before
+     * anything else can be done on it.
      *
      * The (defaulted) argument can be used to specify the compress mode
      * (<code>Add</code> or <code>Insert</code>) in case the vector has not
@@ -278,20 +276,20 @@ namespace TrilinosWrappers
      * argument is ignored if the vector has been added or written to since
      * the last time compress() was called.
      *
-     * See @ref GlossCompress "Compressing distributed objects"
-     * for more information.
+     * See @ref GlossCompress "Compressing distributed objects" for more
+     * information.
      */
     void compress (::dealii::VectorOperation::values operation);
 
     /**
-     * @deprecated: Use the compress(VectorOperation::values) function
-     * above instead.
+     * @deprecated: Use the compress(VectorOperation::values) function above
+     * instead.
      */
     void compress() DEAL_II_DEPRECATED;
 
     /**
-    * @deprecated Use compress(dealii::VectorOperation::values) instead.
-    */
+     * @deprecated Use compress(dealii::VectorOperation::values) instead.
+     */
     void compress (const Epetra_CombineMode last_action) DEAL_II_DEPRECATED;
 
     /**
@@ -377,18 +375,16 @@ namespace TrilinosWrappers
      * <code>i</code> is the first element of the vector stored on this
      * processor, corresponding to the half open interval $[i,i+n)$
      *
-     * @note The description above is true most of the time, but
-     * not always. In particular, Trilinos vectors need not store
-     * contiguous ranges of elements such as $[i,i+n)$. Rather, it
-     * can store vectors where the elements are distributed in
-     * an arbitrary way across all processors and each processor
-     * simply stores a particular subset, not necessarily contiguous.
-     * In this case, this function clearly makes no sense since it
-     * could, at best, return a range that includes all elements
-     * that are stored locally. Thus, the function only succeeds
-     * if the locally stored range is indeed contiguous. It will
-     * trigger an assertion if the local portion of the vector
-     * is not contiguous.
+     * @note The description above is true most of the time, but not always.
+     * In particular, Trilinos vectors need not store contiguous ranges of
+     * elements such as $[i,i+n)$. Rather, it can store vectors where the
+     * elements are distributed in an arbitrary way across all processors and
+     * each processor simply stores a particular subset, not necessarily
+     * contiguous. In this case, this function clearly makes no sense since it
+     * could, at best, return a range that includes all elements that are
+     * stored locally. Thus, the function only succeeds if the locally stored
+     * range is indeed contiguous. It will trigger an assertion if the local
+     * portion of the vector is not contiguous.
      */
     std::pair<size_type, size_type> local_range () const;
 
@@ -396,21 +392,20 @@ namespace TrilinosWrappers
      * Return whether @p index is in the local range or not, see also
      * local_range().
      *
-     * @note The same limitation for the applicability of this
-     * function applies as listed in the documentation of local_range().
+     * @note The same limitation for the applicability of this function
+     * applies as listed in the documentation of local_range().
      */
     bool in_local_range (const size_type index) const;
 
     /**
-     * Return an index set that describes which elements of this vector
-     * are owned by the current processor. Note that this index set does
-     * not include elements this vector may store locally as ghost
-     * elements but that are in fact owned by another processor.
-     * As a consequence, the index sets returned on different
-     * processors if this is a distributed vector will form disjoint
-     * sets that add up to the complete index set.
-     * Obviously, if a vector is created on only one processor, then
-     * the result would satisfy
+     * Return an index set that describes which elements of this vector are
+     * owned by the current processor. Note that this index set does not
+     * include elements this vector may store locally as ghost elements but
+     * that are in fact owned by another processor. As a consequence, the
+     * index sets returned on different processors if this is a distributed
+     * vector will form disjoint sets that add up to the complete index set.
+     * Obviously, if a vector is created on only one processor, then the
+     * result would satisfy
      * @code
      *   vec.locally_owned_elements() == complete_index_set (vec.size())
      * @endcode
@@ -488,8 +483,8 @@ namespace TrilinosWrappers
                                 const VectorBase    &W);
 
     /**
-     * Return whether the vector contains only elements with value
-     * zero. This is a collective operation. This function is expensive, because
+     * Return whether the vector contains only elements with value zero. This
+     * is a collective operation. This function is expensive, because
      * potentially all elements have to be checked.
      */
     bool all_zero () const;
@@ -512,10 +507,10 @@ namespace TrilinosWrappers
      * Provide access to a given element, both read and write.
      *
      * When using a vector distributed with MPI, this operation only makes
-     * sense for elements that are actually present on the calling
-     * processor. Otherwise, an exception is thrown. This is different from
-     * the <code>el()</code> function below that always succeeds (but returns
-     * zero on non-local elements).
+     * sense for elements that are actually present on the calling processor.
+     * Otherwise, an exception is thrown. This is different from the
+     * <code>el()</code> function below that always succeeds (but returns zero
+     * on non-local elements).
      */
     reference
     operator () (const size_type index);
@@ -524,10 +519,10 @@ namespace TrilinosWrappers
      * Provide read-only access to an element.
      *
      * When using a vector distributed with MPI, this operation only makes
-     * sense for elements that are actually present on the calling
-     * processor. Otherwise, an exception is thrown. This is different from
-     * the <code>el()</code> function below that always succeeds (but returns
-     * zero on non-local elements).
+     * sense for elements that are actually present on the calling processor.
+     * Otherwise, an exception is thrown. This is different from the
+     * <code>el()</code> function below that always succeeds (but returns zero
+     * on non-local elements).
      */
     TrilinosScalar
     operator () (const size_type index) const;
@@ -550,8 +545,8 @@ namespace TrilinosWrappers
 
     /**
      * A collective get operation: instead of getting individual elements of a
-     * vector, this function allows to get a whole set of elements at
-     * once. The indices of the elements to be read are stated in the first
+     * vector, this function allows to get a whole set of elements at once.
+     * The indices of the elements to be read are stated in the first
      * argument, the corresponding values are returned in the second.
      */
     void extract_subvector_to (const std::vector<size_type> &indices,
@@ -570,9 +565,9 @@ namespace TrilinosWrappers
      * Return the value of the vector entry <i>i</i>. Note that this function
      * does only work properly when we request a data stored on the local
      * processor. In case the elements sits on another process, this function
-     * returns 0 which might or might not be appropriate in a given
-     * situation. If you rely on consistent results, use the access functions
-     * () or [] that throw an assertion in case a non-local element is used.
+     * returns 0 which might or might not be appropriate in a given situation.
+     * If you rely on consistent results, use the access functions () or []
+     * that throw an assertion in case a non-local element is used.
      */
     TrilinosScalar el (const size_type index) const;
 
@@ -589,14 +584,14 @@ namespace TrilinosWrappers
     iterator begin ();
 
     /**
-     * Return constant iterator to the start of the locally owned elements
-     * of the vector.
+     * Return constant iterator to the start of the locally owned elements of
+     * the vector.
      */
     const_iterator begin () const;
 
     /**
-     * Return an iterator pointing to the element past the end of the array
-     * of locally owned entries.
+     * Return an iterator pointing to the element past the end of the array of
+     * locally owned entries.
      */
     iterator end ();
 
@@ -616,9 +611,9 @@ namespace TrilinosWrappers
 
     /**
      * A collective set operation: instead of setting individual elements of a
-     * vector, this function allows to set a whole set of elements at
-     * once. The indices of the elements to be set are stated in the first
-     * argument, the corresponding values in the second.
+     * vector, this function allows to set a whole set of elements at once.
+     * The indices of the elements to be set are stated in the first argument,
+     * the corresponding values in the second.
      */
     void set (const std::vector<size_type>    &indices,
               const std::vector<TrilinosScalar>  &values);
@@ -695,9 +690,10 @@ namespace TrilinosWrappers
      * then it is possible to add data from a vector that uses a different
      * map, i.e., a vector whose elements are split across processors
      * differently. This may include vectors with ghost elements, for example.
-     * In general, however, adding vectors with a different element-to-processor
-     * map requires communicating data among processors and, consequently,
-     * is a slower operation than when using vectors using the same map.
+     * In general, however, adding vectors with a different element-to-
+     * processor map requires communicating data among processors and,
+     * consequently, is a slower operation than when using vectors using the
+     * same map.
      */
     void add (const VectorBase &V,
               const bool        allow_different_maps = false);
@@ -811,8 +807,8 @@ namespace TrilinosWrappers
     const Epetra_Map &vector_partitioner () const;
 
     /**
-     *  Output of vector in user-defined format in analogy to the
-     *  dealii::Vector class.
+     * Output of vector in user-defined format in analogy to the
+     * dealii::Vector class.
      */
     void print (const char *format = 0) const;
 
@@ -916,10 +912,9 @@ namespace TrilinosWrappers
     bool has_ghosts;
 
     /**
-     * Pointer to the actual Epetra vector object. This may represent a
-     * vector that is in fact distributed among multiple processors. The
-     * object requires an existing Epetra_Map for
-     * storing data when setting it up.
+     * Pointer to the actual Epetra vector object. This may represent a vector
+     * that is in fact distributed among multiple processors. The object
+     * requires an existing Epetra_Map for storing data when setting it up.
      */
     std_cxx11::shared_ptr<Epetra_FEVector> vector;
 
@@ -944,9 +939,9 @@ namespace TrilinosWrappers
 // ------------------- inline and template functions --------------
 
   /**
-   * Global function swap which overloads the default implementation of
-   * the C standard library which uses a temporary object. The function
-   * simply exchanges the data of the two vectors.
+   * Global function swap which overloads the default implementation of the C
+   * standard library which uses a temporary object. The function simply
+   * exchanges the data of the two vectors.
    *
    * @relates TrilinosWrappers::VectorBase
    * @author Martin Kronbichler, Wolfgang Bangerth, 2008
index 4c037a8e3b59b2008e2fae54115d21f86d3c6918..7f30f9f15cdedccf35b2d44bf727e1ac69aed9c4 100644 (file)
@@ -85,23 +85,21 @@ struct VectorOperation
 
 
 /**
- * Numerical vector of data.  For this class there are different types
- * of functions available. The first type of function initializes the
- * vector, changes its size, or computes the norm
- * of the vector in order to measure its length in a suitable norm. The
- * second type helps us to manipulate the components of the vector. The
- * third type defines the algebraic operations for vectors, while the
- * last type defines a few input and output functions.
- * As opposed to the array of the C++ standard library called
- * @p vector (with a lowercase "v"), this class implements an element
- * of a vector space suitable for numerical computations.
+ * Numerical vector of data.  For this class there are different types of
+ * functions available. The first type of function initializes the vector,
+ * changes its size, or computes the norm of the vector in order to measure
+ * its length in a suitable norm. The second type helps us to manipulate the
+ * components of the vector. The third type defines the algebraic operations
+ * for vectors, while the last type defines a few input and output functions.
+ * As opposed to the array of the C++ standard library called @p vector (with
+ * a lowercase "v"), this class implements an element of a vector space
+ * suitable for numerical computations.
  *
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
  *
  * @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth
  */
@@ -125,24 +123,22 @@ public:
   /**
    * Declare a type that has holds real-valued numbers with the same precision
    * as the template argument to this class. If the template argument of this
-   * class is a real data type, then real_type equals the template
-   * argument. If the template argument is a std::complex type then real_type
-   * equals the type underlying the complex numbers.
+   * class is a real data type, then real_type equals the template argument.
+   * If the template argument is a std::complex type then real_type equals the
+   * type underlying the complex numbers.
    *
    * This typedef is used to represent the return type of norms.
    */
   typedef typename numbers::NumberTraits<Number>::real_type real_type;
 
   /**
-   * A variable that indicates whether this vector
-   * supports distributed data storage. If true, then
-   * this vector also needs an appropriate compress()
-   * function that allows communicating recent set or
-   * add operations to individual elements to be communicated
-   * to other processors.
+   * A variable that indicates whether this vector supports distributed data
+   * storage. If true, then this vector also needs an appropriate compress()
+   * function that allows communicating recent set or add operations to
+   * individual elements to be communicated to other processors.
    *
-   * For the current class, the variable equals
-   * false, since it does not support parallel data storage.
+   * For the current class, the variable equals false, since it does not
+   * support parallel data storage.
    */
   static const bool supports_distributed_data = false;
 
@@ -153,7 +149,7 @@ public:
    */
   //@{
   /**
-   *  Constructor. Create a vector of dimension zero.
+   * Constructor. Create a vector of dimension zero.
    */
   Vector ();
 
@@ -208,9 +204,9 @@ public:
 
 #ifdef DEAL_II_WITH_TRILINOS
   /**
-   * Another copy constructor: copy the values from a Trilinos wrapper
-   * vector. This copy constructor is only available if Trilinos was detected
-   * during configuration time.
+   * Another copy constructor: copy the values from a Trilinos wrapper vector.
+   * This copy constructor is only available if Trilinos was detected during
+   * configuration time.
    *
    * Note that due to the communication model used in MPI, this operation can
    * only succeed if all processes do it at the same time. This means that it
@@ -322,9 +318,8 @@ public:
    *
    * Since the semantics of assigning a scalar to a vector are not immediately
    * clear, this operator should really only be used if you want to set the
-   * entire vector to zero. This allows the intuitive notation
-   * <tt>v=0</tt>. Assigning other values is deprecated and may be disallowed
-   * in the future.
+   * entire vector to zero. This allows the intuitive notation <tt>v=0</tt>.
+   * Assigning other values is deprecated and may be disallowed in the future.
    *
    * @dealiiOperationIsMultithreaded
    */
@@ -431,9 +426,9 @@ public:
    * For complex vectors, the scalar product is implemented as
    * $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   template <typename Number2>
   Number operator * (const Vector<Number2> &V) const;
@@ -441,27 +436,27 @@ public:
   /**
    * Return square of the $l_2$-norm.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   real_type norm_sqr () const;
 
   /**
    * Mean value of the elements of this vector.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   Number mean_value () const;
 
   /**
    * $l_1$-norm of the vector. The sum of the absolute values.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   real_type l1_norm () const;
 
@@ -469,9 +464,9 @@ public:
    * $l_2$-norm of the vector. The square root of the sum of the squares of
    * the elements.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   real_type l2_norm () const;
 
@@ -479,9 +474,9 @@ public:
    * $l_p$-norm of the vector. The pth root of the sum of the pth powers of
    * the absolute values of the elements.
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   real_type lp_norm (const real_type p) const;
 
@@ -491,9 +486,9 @@ public:
   real_type linfty_norm () const;
 
   /**
-   * Performs a combined operation of a vector addition and a subsequent
-   * inner product, returning the value of the inner product. In other words,
-   * the result of this function is the same as if the user called
+   * Performs a combined operation of a vector addition and a subsequent inner
+   * product, returning the value of the inner product. In other words, the
+   * result of this function is the same as if the user called
    * @code
    * this->add(a, V);
    * return_value = *this * W;
@@ -506,9 +501,9 @@ public:
    * most vector operations are memory transfer limited, this reduces the time
    * by 25\% (or 50\% if @p W equals @p this).
    *
-   * @dealiiOperationIsMultithreaded The algorithm uses pairwise
-   * summation with the same order of summation in every run, which gives
-   * fully repeatable results from one run to another.
+   * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+   * with the same order of summation in every run, which gives fully
+   * repeatable results from one run to another.
    */
   Number add_and_dot (const Number          a,
                       const Vector<Number> &V,
@@ -815,8 +810,8 @@ public:
    */
   //@{
   /**
-   *  Output of vector in user-defined format. For complex-valued vectors, the
-   *  format should include specifiers for both the real and imaginary parts.
+   * Output of vector in user-defined format. For complex-valued vectors, the
+   * format should include specifiers for both the real and imaginary parts.
    */
   void print (const char *format = 0) const;
 
@@ -894,22 +889,19 @@ public:
   bool in_local_range (const size_type global_index) const;
 
   /**
-   * Return an index set that describes which elements of this vector
-   * are owned by the current processor. Note that this index set does
-   * not include elements this vector may store locally as ghost
-   * elements but that are in fact owned by another processor.
-   * As a consequence, the index sets returned on different
-   * processors if this is a distributed vector will form disjoint
-   * sets that add up to the complete index set.
-   * Obviously, if a vector is created on only one processor, then
-   * the result would satisfy
+   * Return an index set that describes which elements of this vector are
+   * owned by the current processor. Note that this index set does not include
+   * elements this vector may store locally as ghost elements but that are in
+   * fact owned by another processor. As a consequence, the index sets
+   * returned on different processors if this is a distributed vector will
+   * form disjoint sets that add up to the complete index set. Obviously, if a
+   * vector is created on only one processor, then the result would satisfy
    * @code
    *   vec.locally_owned_elements() == complete_index_set (vec.size())
    * @endcode
    *
-   * Since the current data type does not support parallel data storage
-   * across different processors, the returned index set is the
-   * complete index set.
+   * Since the current data type does not support parallel data storage across
+   * different processors, the returned index set is the complete index set.
    */
   IndexSet locally_owned_elements () const;
 
@@ -1382,9 +1374,9 @@ Vector<Number>::load (Archive &ar, const unsigned int)
 
 
 /**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
  *
  * @relates Vector
  * @author Wolfgang Bangerth, 2000
index c5385551c63ba1ccdecc3dd3c1e5bc848d3cfedd..bf238454d969d03c5577212a68fbff9225bbbebb 100644 (file)
@@ -33,95 +33,85 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Memory management base class for vectors. This is an abstract base
- * class used, among other places, by all iterative methods to
- * allocate space for auxiliary vectors.
+ * Memory management base class for vectors. This is an abstract base class
+ * used, among other places, by all iterative methods to allocate space for
+ * auxiliary vectors.
  *
- * The purpose of this class is as follows: in iterative solvers and
- * other places, one needs to allocate temporary storage for vectors,
- * for example for auxiliary vectors. One could allocate and release
- * them anew every time, but this may be expensive in some situations
- * if it has to happen very frequently. A common case for this is when
- * an iterative method is used to invert a matrix in each iteration an
- * outer solver, such as when inverting a matrix block for a Schur
- * complement solver.
+ * The purpose of this class is as follows: in iterative solvers and other
+ * places, one needs to allocate temporary storage for vectors, for example
+ * for auxiliary vectors. One could allocate and release them anew every time,
+ * but this may be expensive in some situations if it has to happen very
+ * frequently. A common case for this is when an iterative method is used to
+ * invert a matrix in each iteration an outer solver, such as when inverting a
+ * matrix block for a Schur complement solver.
  *
- * In such situations, allocating and deallocating vectors anew in
- * each call to the inner solver is expensive and leads to memory
- * fragmentation. The present class allows to avoid this by offering
- * an interface that other classes can use to allocate and deallocate
- * vectors. Different derived classes then implement different
- * strategies to provide temporary storage vectors to using
- * classes.
+ * In such situations, allocating and deallocating vectors anew in each call
+ * to the inner solver is expensive and leads to memory fragmentation. The
+ * present class allows to avoid this by offering an interface that other
+ * classes can use to allocate and deallocate vectors. Different derived
+ * classes then implement different strategies to provide temporary storage
+ * vectors to using classes.
  *
  * For example, the PrimitiveVectorMemory class simply allocates and
  * deallocated vectors each time it is asked for a vector. It is an
- * appropriate implementation to use for iterative solvers that are
- * called only once, or very infrequently.
+ * appropriate implementation to use for iterative solvers that are called
+ * only once, or very infrequently.
  *
- * On the other hand, the GrowingVectorMemory class never returns
- * memory space to the operating system memory management subsystem
- * during its lifetime; it only marks them as unused and allows them
- * to be reused next time a vector is requested.
+ * On the other hand, the GrowingVectorMemory class never returns memory space
+ * to the operating system memory management subsystem during its lifetime; it
+ * only marks them as unused and allows them to be reused next time a vector
+ * is requested.
  *
- * Yet other classes, when implemented, could provide even other
- * strategies for memory management.
+ * Yet other classes, when implemented, could provide even other strategies
+ * for memory management.
  *
  * @author Guido Kanschat, 1998-2003
-*/
+ */
 template<class VECTOR = dealii::Vector<double> >
 class VectorMemory : public Subscriptor
 {
 public:
 
   /**
-   * Virtual destructor is needed
-   * as there are virtual functions
-   * in this class.
+   * Virtual destructor is needed as there are virtual functions in this
+   * class.
    */
   virtual ~VectorMemory () {}
 
   /**
-   * Return a pointer to a new
-   * vector. The number of elements
-   * or their subdivision into
-   * blocks (if applicable) is
-   * unspecified and users of this
-   * function should reset vectors
-   * to their proper size. The same
-   * holds for the contents of
-   * vectors: they are unspecified.
+   * Return a pointer to a new vector. The number of elements or their
+   * subdivision into blocks (if applicable) is unspecified and users of this
+   * function should reset vectors to their proper size. The same holds for
+   * the contents of vectors: they are unspecified.
    */
   virtual VECTOR *alloc () = 0;
 
   /**
-   * Return a vector and indicate
-   * that it is not going to be
-   * used any further by the
-   * instance that called alloc()
-   * to get a pointer to it.
+   * Return a vector and indicate that it is not going to be used any further
+   * by the instance that called alloc() to get a pointer to it.
    */
   virtual void free (const VECTOR *const) = 0;
 
-  /** @addtogroup Exceptions
-   * @{ */
+  /**
+   * @addtogroup Exceptions
+   * @{
+   */
 
   /**
    * No more available vectors.
    */
   DeclException0(ExcNoMoreVectors);
   /**
-   * Vector was not allocated from
-   * this memory pool.
+   * Vector was not allocated from this memory pool.
    */
   DeclException0(ExcNotAllocatedHere);
 
   //@}
   /**
-   * Pointer to vectors allocated from VectorMemory objects. This
-   * pointer is safe in the sense that it automatically calls free()
-   * when it is destroyed, thus relieving the user from using vector
-   * management functions at all.
+   * Pointer to vectors allocated from VectorMemory objects. This pointer is
+   * safe in the sense that it automatically calls free() when it is
+   * destroyed, thus relieving the user from using vector management functions
+   * at all.
    *
    * @author Guido Kanschat, 2009
    */
@@ -129,15 +119,11 @@ public:
   {
   public:
     /**
-     * Constructor, automatically
-     * allocating a vector from
-     * @p mem.
+     * Constructor, automatically allocating a vector from @p mem.
      */
     Pointer(VectorMemory<VECTOR> &mem);
     /**
-     * Destructor, automatically
-     * releasing the vector from
-     * the memory #pool.
+     * Destructor, automatically releasing the vector from the memory #pool.
      */
     ~Pointer();
 
@@ -170,12 +156,11 @@ public:
 
 
 /**
- * Simple memory management. See the documentation of the base class
- * for a description of its purpose.
+ * Simple memory management. See the documentation of the base class for a
+ * description of its purpose.
  *
- * This class allocates and deletes
- * vectors as needed from the global heap, i.e. performs no
- * specially adapted actions for memory management.
+ * This class allocates and deletes vectors as needed from the global heap,
+ * i.e. performs no specially adapted actions for memory management.
  */
 template<class VECTOR = dealii::Vector<double> >
 class PrimitiveVectorMemory : public VectorMemory<VECTOR>
@@ -187,20 +172,13 @@ public:
   PrimitiveVectorMemory () {}
 
   /**
-   * Return a pointer to a new
-   * vector. The number of elements
-   * or their subdivision into
-   * blocks (if applicable) is
-   * unspecified and users of this
-   * function should reset vectors
-   * to their proper size. The same
-   * holds for the contents of
-   * vectors: they are unspecified.
+   * Return a pointer to a new vector. The number of elements or their
+   * subdivision into blocks (if applicable) is unspecified and users of this
+   * function should reset vectors to their proper size. The same holds for
+   * the contents of vectors: they are unspecified.
    *
-   * For the present class, calling
-   * this function will allocate a
-   * new vector on the heap and
-   * returning a pointer to it.
+   * For the present class, calling this function will allocate a new vector
+   * on the heap and returning a pointer to it.
    */
   virtual VECTOR *alloc ()
   {
@@ -208,16 +186,12 @@ public:
   }
 
   /**
-   * Return a vector and indicate
-   * that it is not going to be
-   * used any further by the
-   * instance that called alloc()
-   * to get a pointer to it.
+   * Return a vector and indicate that it is not going to be used any further
+   * by the instance that called alloc() to get a pointer to it.
    *
    *
-   * For the present class, this
-   * means that the vector is
-   * returned to the global heap.
+   * For the present class, this means that the vector is returned to the
+   * global heap.
    */
   virtual void free (const VECTOR *const v)
   {
@@ -228,28 +202,26 @@ public:
 
 
 /**
- * A pool based memory management class. See the documentation of the
- * base class for a description of its purpose.
+ * A pool based memory management class. See the documentation of the base
+ * class for a description of its purpose.
  *
- * Each time a vector is requested from this class, it checks if it
- * has one available and returns its address, or allocates a new one
- * on the heap. If a vector is returned, through the free() member
- * function, it doesn't return it to the operating system memory
- * subsystem, but keeps it around unused for later use if alloc() is
- * called again, or until the object is destroyed. The class therefore
- * avoid the overhead of repeatedly allocating memory on the heap if
- * temporary vectors are required and released frequently; on the
- * other hand, it doesn't release once-allocated memory at the
- * earliest possible time and may therefore lead to an increased
- * overall memory consumption.
+ * Each time a vector is requested from this class, it checks if it has one
+ * available and returns its address, or allocates a new one on the heap. If a
+ * vector is returned, through the free() member function, it doesn't return
+ * it to the operating system memory subsystem, but keeps it around unused for
+ * later use if alloc() is called again, or until the object is destroyed. The
+ * class therefore avoid the overhead of repeatedly allocating memory on the
+ * heap if temporary vectors are required and released frequently; on the
+ * other hand, it doesn't release once-allocated memory at the earliest
+ * possible time and may therefore lead to an increased overall memory
+ * consumption.
  *
- * All GrowingVectorMemory objects of the same vector type use the
- * same memory Pool. Therefore, functions can create such a
- * VectorMemory object whenever needed without performance penalty. A
- * drawback of this policy might be that vectors once allocated are
- * only released at the end of the program run. Nevertheless, the
- * since they are reused, this should be of no concern. Additionally,
- * the destructor of the Pool warns about memory leaks.
+ * All GrowingVectorMemory objects of the same vector type use the same memory
+ * Pool. Therefore, functions can create such a VectorMemory object whenever
+ * needed without performance penalty. A drawback of this policy might be that
+ * vectors once allocated are only released at the end of the program run.
+ * Nevertheless, the since they are reused, this should be of no concern.
+ * Additionally, the destructor of the Pool warns about memory leaks.
  *
  * @author Guido Kanschat, 1999, 2007
  */
@@ -263,86 +235,60 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Constructor.  The argument
-   * allows to preallocate a
-   * certain number of vectors. The
-   * default is not to do this.
+   * Constructor.  The argument allows to preallocate a certain number of
+   * vectors. The default is not to do this.
    */
   GrowingVectorMemory (const size_type initial_size = 0,
                        const bool log_statistics = false);
 
   /**
-   * Destructor.
-   * Release all vectors.
-   * This destructor also offers
-   * some statistic on the number
-   * of allocated vectors.
+   * Destructor. Release all vectors. This destructor also offers some
+   * statistic on the number of allocated vectors.
    *
-   * The log file will also contain
-   * a warning message, if there
-   * are allocated vectors left.
+   * The log file will also contain a warning message, if there are allocated
+   * vectors left.
    */
   virtual ~GrowingVectorMemory();
 
   /**
-   * Return a pointer to a new
-   * vector. The number of elements
-   * or their subdivision into
-   * blocks (if applicable) is
-   * unspecified and users of this
-   * function should reset vectors
-   * to their proper size. The same
-   * holds for the contents of
-   * vectors: they are unspecified.
+   * Return a pointer to a new vector. The number of elements or their
+   * subdivision into blocks (if applicable) is unspecified and users of this
+   * function should reset vectors to their proper size. The same holds for
+   * the contents of vectors: they are unspecified.
    */
   virtual VECTOR *alloc ();
 
   /**
-   * Return a vector and indicate
-   * that it is not going to be
-   * used any further by the
-   * instance that called alloc()
-   * to get a pointer to it.
+   * Return a vector and indicate that it is not going to be used any further
+   * by the instance that called alloc() to get a pointer to it.
    *
-   * For the present class, this
-   * means retaining the vector for
-   * later reuse by the alloc()
-   * method.
+   * For the present class, this means retaining the vector for later reuse by
+   * the alloc() method.
    */
   virtual void free (const VECTOR *const);
 
   /**
-   * Release all vectors that are
-   * not currently in use.
+   * Release all vectors that are not currently in use.
    */
   static void release_unused_memory ();
 
   /**
-   * Memory consumed by this class
-   * and all currently allocated
-   * vectors.
+   * Memory consumed by this class and all currently allocated vectors.
    */
   virtual std::size_t memory_consumption() const;
 
 private:
   /**
-   * Type to enter into the
-   * array. First component will be
-   * a flag telling whether the
-   * vector is used, second the
-   * vector itself.
+   * Type to enter into the array. First component will be a flag telling
+   * whether the vector is used, second the vector itself.
    */
   typedef std::pair<bool, VECTOR *> entry_type;
 
   /**
-   * The class providing the actual
-   * storage for the memory pool.
+   * The class providing the actual storage for the memory pool.
    *
-   * This is where the actual
-   * storage for GrowingVectorMemory
-   * is provided. Only one of these
-   * pools is used for each vector
-   * type, thus allocating all
+   * This is where the actual storage for GrowingVectorMemory is provided.
+   * Only one of these pools is used for each vector type, thus allocating all
    * vectors from the same storage.
    *
    * @author Guido Kanschat, 2007
@@ -350,25 +296,19 @@ private:
   struct Pool
   {
     /**
-     * Standard constructor
-     * creating an empty pool
+     * Standard constructor creating an empty pool
      */
     Pool();
     /**
-     * Destructor. Frees memory
-     * and warns about memory
-     * leaks
+     * Destructor. Frees memory and warns about memory leaks
      */
     ~Pool();
     /**
-     * Create data vector; does
-     * nothing after first
-     * initialization
+     * Create data vector; does nothing after first initialization
      */
     void initialize(const size_type size);
     /**
-     * Pointer to the storage
-     * object
+     * Pointer to the storage object
      */
     std::vector<entry_type> *data;
   };
@@ -379,31 +319,24 @@ private:
   static Pool pool;
 
   /**
-   * Overall number of
-   * allocations. Only used for
-   * bookkeeping and to generate
-   * output at the end of an
-   * object's lifetime.
+   * Overall number of allocations. Only used for bookkeeping and to generate
+   * output at the end of an object's lifetime.
    */
   size_type total_alloc;
   /**
-   * Number of vectors currently
-   * allocated in this object; used
-   * for detecting memory leaks.
+   * Number of vectors currently allocated in this object; used for detecting
+   * memory leaks.
    */
   size_type current_alloc;
 
   /**
-   * A flag controlling the logging
-   * of statistics by the
-   * destructor.
+   * A flag controlling the logging of statistics by the destructor.
    */
   bool log_statistics;
 
   /**
-   * Mutex to synchronise access to
-   * internal data of this object
-   * from multiple threads.
+   * Mutex to synchronise access to internal data of this object from multiple
+   * threads.
    */
   static Threads::Mutex mutex;
 };
index a57ef9cae8e97032b1f0b0864c6ce725180c19ac..7232e07863f8a774067a7fa693a00e230c424b4d 100644 (file)
@@ -32,103 +32,98 @@ DEAL_II_NAMESPACE_OPEN
  */
 
 /**
- * View of a numerical vector of data. This class provides an
- * interface compatible with the Vector<double> class (from which it
- * is inherited), that allows fast access to locations of memory
- * already allocated with arrays of type Number.
+ * View of a numerical vector of data. This class provides an interface
+ * compatible with the Vector<double> class (from which it is inherited), that
+ * allows fast access to locations of memory already allocated with arrays of
+ * type Number.
  *
- * This is in the same style of the vector view in the Trilinos
- * library.
+ * This is in the same style of the vector view in the Trilinos library.
  *
- * You should consider using the VectorView object ONLY when ALL of
- * the following requirements are met:
+ * You should consider using the VectorView object ONLY when ALL of the
+ * following requirements are met:
  *
  * 1. Your application requires a Vector<Number> object.
  *
  * 2. All you have at your disposal is a Number* pointer.
  *
- * 3. You are ABSOLUTELY SURE that the above pointer points to a
- * valid area of memory of the correct size.
+ * 3. You are ABSOLUTELY SURE that the above pointer points to a valid area of
+ * memory of the correct size.
  *
- * 4. You really believe that making a copy of that memory would be
- * too expensive.
+ * 4. You really believe that making a copy of that memory would be too
+ * expensive.
  *
  * 5. You really know what you are doing.
  *
- * Notice that NO CHECKS are performed on the actual memory, and if
- * you try to access illegal areas of memory, your computer will
- * suffer from it. Once again, use this class ONLY if you know exactly
- * what you are doing.
+ * Notice that NO CHECKS are performed on the actual memory, and if you try to
+ * access illegal areas of memory, your computer will suffer from it. Once
+ * again, use this class ONLY if you know exactly what you are doing.
  *
- * Two constructors are provided. One for read-write access, and one
- * for read only access, and you are allowed to use this class on
- * objects of type const Number*. However you should be aware of the
- * fact that the constness of the array pointed to is ignored, which
- * means that you should only use the const constructor when the
- * actual object you are constructing is itself a constant object.
- * As a corollary, you will be allowed to call even functions of
- * the base class that change data of the array; this being a violation
- * of the C++ type model, you should make sure that this only happens
- * if it is really valid and, in general, if
- * you know what you are doing.
+ * Two constructors are provided. One for read-write access, and one for read
+ * only access, and you are allowed to use this class on objects of type const
+ * Number*. However you should be aware of the fact that the constness of the
+ * array pointed to is ignored, which means that you should only use the const
+ * constructor when the actual object you are constructing is itself a
+ * constant object. As a corollary, you will be allowed to call even functions
+ * of the base class that change data of the array; this being a violation of
+ * the C++ type model, you should make sure that this only happens if it is
+ * really valid and, in general, if you know what you are doing.
  *
- * Since this class does not own the memory that you are accessing,
- * you have to make sure that the lifetime of the section of memory you
- * are viewing is longer than this object. No attempt is made to
- * ensure that this is the case.
+ * Since this class does not own the memory that you are accessing, you have
+ * to make sure that the lifetime of the section of memory you are viewing is
+ * longer than this object. No attempt is made to ensure that this is the
+ * case.
  *
  * An example usage of this class is the following:
  *
- @code
- // Create an array of length 5;
- double * array = new double[5];
- // Now create a view of the above array that is compatible with the
- // Vector<double> class
- VectorView<double> view(5, array);
-
- view(1) = 4;
-
- // The following line should output 4.
- cout << array[1] << endl;
-
- // If debug mode is on, then the following triggers an execption:
- view(6) = 4;
-
- // But notice that no checks are performed, so this is legal but WILL
- // NOT work
- VectorView<double> wrong_view(10, array);
-
- // Now no assert will be thrown if you type wrong_view(6), but most
- // likely a seg fault will occur.
- view(6) = 4;
-
- // Notice that this construction is legal. It will create a copy of
- // the array.
- const Vector<double> const_copy(view);
-
- // Now this is the correct way to instantiate a constant view of the
- // above vector:
- const VectorView<double> correct_const_copy_view(5, const_copy.begin());
-
- // While this will compile, BUT WILL NOT COMPLAIN if you try to write
- // on it!
- VectorView<double> wrong_const_copy_view(5, const_copy.begin());
-
- // Now writing to elements of wrong_const_copy_view is allowed, and
- // will change the same memory as the const_copy object.
- wrong_const_copy_view(1) = 5;
-
- if(copy_view(1) == wrong_const_copy_view(1)) cout << "Tautology";
-
- @endcode
+ * @code
+ * // Create an array of length 5;
+ * double * array = new double[5];
+ * // Now create a view of the above array that is compatible with the
+ * // Vector<double> class
+ * VectorView<double> view(5, array);
+ *
+ * view(1) = 4;
+ *
+ * // The following line should output 4.
+ * cout << array[1] << endl;
+ *
+ * // If debug mode is on, then the following triggers an execption:
+ * view(6) = 4;
  *
+ * // But notice that no checks are performed, so this is legal but WILL
+ * // NOT work
+ * VectorView<double> wrong_view(10, array);
  *
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * // Now no assert will be thrown if you type wrong_view(6), but most
+ * // likely a seg fault will occur.
+ * view(6) = 4;
+ *
+ * // Notice that this construction is legal. It will create a copy of
+ * // the array.
+ * const Vector<double> const_copy(view);
+ *
+ * // Now this is the correct way to instantiate a constant view of the
+ * // above vector:
+ * const VectorView<double> correct_const_copy_view(5, const_copy.begin());
+ *
+ * // While this will compile, BUT WILL NOT COMPLAIN if you try to write
+ * // on it!
+ * VectorView<double> wrong_const_copy_view(5, const_copy.begin());
+ *
+ * // Now writing to elements of wrong_const_copy_view is allowed, and
+ * // will change the same memory as the const_copy object.
+ * wrong_const_copy_view(1) = 5;
+ *
+ * if(copy_view(1) == wrong_const_copy_view(1)) cout << "Tautology";
+ *
+ * @endcode
+ *
+ *
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
  *
  * @author Luca Heltai, 2009
  */
@@ -143,58 +138,44 @@ public:
   typedef types::global_dof_index size_type;
 
   /**
-   * Read write constructor. Takes the size
-   * of the vector, just like the standard
-   * one, but the data is picked starting
-   * from the location of the pointer @p
-   * ptr.
+   * Read write constructor. Takes the size of the vector, just like the
+   * standard one, but the data is picked starting from the location of the
+   * pointer @p ptr.
    */
   VectorView(const size_type new_size, Number *ptr);
 
   /**
-   * The constant constructor is the same
-   * as above, however you will not be able
-   * to access the data for write access.
+   * The constant constructor is the same as above, however you will not be
+   * able to access the data for write access.
    *
-   * You should only use this class by
-   * constructing it as a const
+   * You should only use this class by constructing it as a const
    * VectorView<double>(size, ptr) object.
    *
-   * Undefined behavior will occur if you
-   * construct it as a non const object or
-   * attempt to write on it.
+   * Undefined behavior will occur if you construct it as a non const object
+   * or attempt to write on it.
    */
   VectorView(const size_type new_size, const Number *ptr);
 
   /**
-   * This desctructor will only reset the
-   * internal sizes and the internal
-   * pointers, but it will NOT clear the
-   * memory. */
+   * This desctructor will only reset the internal sizes and the internal
+   * pointers, but it will NOT clear the memory.
+   */
   ~VectorView();
 
   /**
-   * The reinit function of this object has
-   * a behavior which is different from the
-   * one of the base class. VectorView does
-   * not handle memory, and you should not
-   * attempt to resize the memory that is
-   * pointed to by this object using the
-   * reinit function. You can, however,
-   * resize the view that you have of the
-   * original object. Notice that it is
-   * your own responsibility to ensure that
-   * the memory you are pointing to is big
-   * enough.
+   * The reinit function of this object has a behavior which is different from
+   * the one of the base class. VectorView does not handle memory, and you
+   * should not attempt to resize the memory that is pointed to by this object
+   * using the reinit function. You can, however, resize the view that you
+   * have of the original object. Notice that it is your own responsibility to
+   * ensure that the memory you are pointing to is big enough.
    *
-   * Similarly to what happens in the base
-   * class, if fast is false, then the
-   * entire content of the vector is set to
-   * 0, otherwise the content of the memory
-   * is left unchanged.
+   * Similarly to what happens in the base class, if fast is false, then the
+   * entire content of the vector is set to 0, otherwise the content of the
+   * memory is left unchanged.
    *
-   * Notice that the following snippet of
-   * code may not produce what you expect:
+   * Notice that the following snippet of code may not produce what you
+   * expect:
    *
    * @code
    * // Create a vector of length 1.
@@ -210,51 +191,37 @@ public:
    * view_of_long_vector.reinit(100, true);
    * @endcode
    *
-   * In the above case, the
-   * Vector<double>::reinit method is
-   * called, and a NEW area of memory is
-   * reserved, possibly not starting at the
-   * same place as before. Hoever, the
-   * VectorView<double> object keeps
-   * pointing to the same old area. After
-   * the two reinits, any call to
-   * view_of_long_vector(i), with i>0 might
-   * cause an attempt to access invalid
-   * areas of memory, or might function
-   * properly, depending on whether or not
-   * the system was able to allocate some
-   * memory consecutively after the
-   * original allocation.
+   * In the above case, the Vector<double>::reinit method is called, and a NEW
+   * area of memory is reserved, possibly not starting at the same place as
+   * before. Hoever, the VectorView<double> object keeps pointing to the same
+   * old area. After the two reinits, any call to view_of_long_vector(i), with
+   * i>0 might cause an attempt to access invalid areas of memory, or might
+   * function properly, depending on whether or not the system was able to
+   * allocate some memory consecutively after the original allocation.
    *
-   * In any case, you should not rely on
-   * this behavior, and you should only
-   * call this reinit function if you
-   * really know what you are doing.
+   * In any case, you should not rely on this behavior, and you should only
+   * call this reinit function if you really know what you are doing.
    */
   virtual void reinit (const size_type N,
                        const bool         fast=false);
 
-  /** This reinit function is
-      equivalent to constructing a
-      new object with the given
-      size, starting from the
-      pointer ptr. */
+  /**
+   * This reinit function is equivalent to constructing a new object with the
+   * given size, starting from the pointer ptr.
+   */
   void reinit(const size_type N, Number *ptr);
 
-  /** This reinit function is
-      equivalent to constructing a
-      new object with the given
-      size, starting from the
-      pointer ptr. The same
-      considerations made for the
-      constructor apply here. */
+  /**
+   * This reinit function is equivalent to constructing a new object with the
+   * given size, starting from the pointer ptr. The same considerations made
+   * for the constructor apply here.
+   */
   void reinit(const size_type N, const Number *ptr);
 
   /**
-   * This function is here to prevent
-   * memory corruption. It should never be
-   * called, and will throw an exception if
-   * you try to do so. */
+   * This function is here to prevent memory corruption. It should never be
+   * called, and will throw an exception if you try to do so.
+   */
   virtual void swap (Vector<Number> &v);
 };
 
index 959b4a215ff3f4a708e5811ec74bf305858526ab..c3dff785c475f65ef3b70c0bafc4d6caad9ef58f 100644 (file)
@@ -206,8 +206,8 @@ namespace internal
       /**
        * This helper function determines a block size if the user decided not
        * to force a block size through MatrixFree::AdditionalData. This is
-       * computed based on the number of hardware threads on the system
-       *  and the number of macro cells that we should work on.
+       * computed based on the number of hardware threads on the system and
+       * the number of macro cells that we should work on.
        */
       void guess_block_size (const SizeInfo &size_info,
                              TaskInfo       &task_info);
@@ -240,11 +240,11 @@ namespace internal
        *
        * The strategy is based on a two-level approach. The outer level is
        * subdivided into partitions similar to the type of neighbors in
-       * Cuthill-McKee, and the inner level is again subdivided into
-       * Cuthill-McKee-like partitions (partitions whose level differs by more
-       * than 2 can be worked on independently). One task is represented by a
-       * chunk of cells. The cell chunks are formed after subdivision into the
-       * two levels of partitions.
+       * Cuthill-McKee, and the inner level is again subdivided into Cuthill-
+       * McKee-like partitions (partitions whose level differs by more than 2
+       * can be worked on independently). One task is represented by a chunk
+       * of cells. The cell chunks are formed after subdivision into the two
+       * levels of partitions.
        */
       void
       make_thread_graph_partition_partition (SizeInfo                  &size_info,
@@ -314,13 +314,12 @@ namespace internal
        * <tt>n_locally_owned_dofs</tt> to
        * <tt>n_locally_owned_dofs+n_ghost_dofs</tt>. The translation between
        * this MPI-local index space and the global numbering of degrees of
-       * freedom is stored in the @p vector_partitioner data structure.
-
-       * This array also includes the indirect contributions from constraints,
+       * freedom is stored in the @p vector_partitioner data structure.  This
+       * array also includes the indirect contributions from constraints,
        * which are described by the @p constraint_indicator field. Because of
-       * variable lengths of rows, this would be a vector of a
-       * vector. However, we use one contiguous memory region and store the
-       * rowstart in the variable @p row_starts.
+       * variable lengths of rows, this would be a vector of a vector.
+       * However, we use one contiguous memory region and store the rowstart
+       * in the variable @p row_starts.
        */
       std::vector<unsigned int> dof_indices;
 
index c63d3ec5dc2bc4ffa2b2fa68e6b89920fc283d82..9b4df70e3bc920da216a72cd982c72a9601657c2 100644 (file)
@@ -65,10 +65,9 @@ template <int dim, int fe_degree, int n_q_points_1d = fe_degree+1,
  * @param dim Dimension in which this class is to be used
  *
  * @param n_components Number of vector components when solving a system of
- *                  PDEs. If the same operation is applied to several
- *                  components of a PDE (e.g. a vector Laplace equation), they
- *                  can be applied simultaneously with one call (and often
- *                  more efficiently)
+ * PDEs. If the same operation is applied to several components of a PDE (e.g.
+ * a vector Laplace equation), they can be applied simultaneously with one
+ * call (and often more efficiently)
  *
  * @param Number Number format, usually @p double or @p float
  *
@@ -136,8 +135,8 @@ public:
   unsigned int get_cell_data_number() const;
 
   /**
-   * Returns the type of the cell the @p reinit function has been called
-   * for. Valid values are @p cartesian for Cartesian cells (which allows for
+   * Returns the type of the cell the @p reinit function has been called for.
+   * Valid values are @p cartesian for Cartesian cells (which allows for
    * considerable data compression), @p affine for cells with affine mappings,
    * and @p general for general cells without any compressed storage applied.
    */
@@ -172,10 +171,10 @@ public:
    *
    * If some constraints on the vector are inhomogeneous, use the function
    * read_dof_values_plain instead and provide the vector with useful data
-   * also in constrained positions by calling
-   * ConstraintMatrix::distribute. When accessing vector entries during the
-   * solution of linear systems, the temporary solution should always have
-   * homogeneous constraints and this method is the correct one.
+   * also in constrained positions by calling ConstraintMatrix::distribute.
+   * When accessing vector entries during the solution of linear systems, the
+   * temporary solution should always have homogeneous constraints and this
+   * method is the correct one.
    *
    * If this class was constructed without a MatrixFree object and the
    * information is acquired on the fly through a
@@ -407,11 +406,11 @@ public:
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies what
-   * is tested by all basis function gradients on the current cell and
-   * integrated over.
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies what is
+   * tested by all basis function gradients on the current cell and integrated
+   * over.
    *
    * Note that the derived class FEEvaluationAccess overloads this operation
    * with specializations for the scalar case (n_components == 1) and for the
@@ -482,12 +481,12 @@ public:
   const VectorizedArray<Number> *begin_dof_values () const;
 
   /**
-   * Returns a read and write pointer to the first field of the dof
-   * values. This is the data field the read_dof_values() functions write
-   * into. First come the the dof values for the first component, then all
-   * values for the second component, and so on. This is related to the
-   * internal data structures used in this class. In general, it is safer to
-   * use the get_dof_value() function instead.
+   * Returns a read and write pointer to the first field of the dof values.
+   * This is the data field the read_dof_values() functions write into. First
+   * come the the dof values for the first component, then all values for the
+   * second component, and so on. This is related to the internal data
+   * structures used in this class. In general, it is safer to use the
+   * get_dof_value() function instead.
    */
   VectorizedArray<Number> *begin_dof_values ();
 
@@ -544,9 +543,9 @@ public:
   /**
    * Returns a read-only pointer to the first field of function hessians on
    * quadrature points. First comes the xx-component of the hessian for the
-   * first component on all quadrature points, then the yy-component,
-   * zz-component in (3D), then the xy-component, and so on. Next comes the
-   * xx-component of the second component, and so on. This is related to the
+   * first component on all quadrature points, then the yy-component, zz-
+   * component in (3D), then the xy-component, and so on. Next comes the xx-
+   * component of the second component, and so on. This is related to the
    * internal data structures used in this class. The raw data after a call to
    * @p evaluate only contains unit cell operations, so possible
    * transformations, quadrature weights etc. must be applied manually. In
@@ -558,9 +557,9 @@ public:
   /**
    * Returns a read and write pointer to the first field of function hessians
    * on quadrature points. First comes the xx-component of the hessian for the
-   * first component on all quadrature points, then the yy-component,
-   * zz-component in (3D), then the xy-component, and so on. Next comes the
-   * xx-component of the second component, and so on. This is related to the
+   * first component on all quadrature points, then the yy-component, zz-
+   * component in (3D), then the xy-component, and so on. Next comes the xx-
+   * component of the second component, and so on. This is related to the
    * internal data structures used in this class. The raw data after a call to
    * @p evaluate only contains unit cell operations, so possible
    * transformations, quadrature weights etc. must be applied manually. In
@@ -597,8 +596,8 @@ protected:
   /**
    * Constructor that comes with reduced functionality and works similar as
    * FEValues. The arguments are similar to the ones passed to the constructor
-   * of FEValues, with the notable difference that FEEvaluation expects a
-   * one-dimensional quadrature formula, Quadrature<1>, instead of a @p dim
+   * of FEValues, with the notable difference that FEEvaluation expects a one-
+   * dimensional quadrature formula, Quadrature<1>, instead of a @p dim
    * dimensional one. The finite element can be both scalar or vector valued,
    * but this method always only selects a scalar base element at a time (with
    * @p n_components copies as specified by the class template argument). For
@@ -612,10 +611,10 @@ protected:
    * degrees of freedom of the current class known. If the iterator includes
    * DoFHandler information (i.e., it is a DoFHandler::cell_iterator or
    * similar), the initialization allows to also read from or write to vectors
-   * in the standard way for DoFHandler::active_cell_iterator types for
-   * one cell at a time. However, this approach is much slower than the path
-   * with MatrixFree with MPI since index translation has to be done. As only
-   * one cell at a time is used, this method does not vectorize over several
+   * in the standard way for DoFHandler::active_cell_iterator types for one
+   * cell at a time. However, this approach is much slower than the path with
+   * MatrixFree with MPI since index translation has to be done. As only one
+   * cell at a time is used, this method does not vectorize over several
    * elements (which is most efficient for vector operations), but only
    * possibly within the element if the evaluate/integrate routines are
    * combined inside user code (e.g. for computing cell matrices).
@@ -681,9 +680,8 @@ protected:
 
   /**
    * This field stores the values of the finite element function on quadrature
-   * points after applying unit cell transformations or before
-   * integrating. The methods get_value() and submit_value() access this
-   * field.
+   * points after applying unit cell transformations or before integrating.
+   * The methods get_value() and submit_value() access this field.
    */
   VectorizedArray<Number> *values_quad[n_components];
 
@@ -732,17 +730,17 @@ protected:
   const MatrixFree<dim,Number> *matrix_info;
 
   /**
-   * Stores a pointer to the underlying DoF indices and constraint
-   * description for the component specified at construction. Also contained
-   * in matrix_info, but it simplifies code if we store a reference to it.
+   * Stores a pointer to the underlying DoF indices and constraint description
+   * for the component specified at construction. Also contained in
+   * matrix_info, but it simplifies code if we store a reference to it.
    */
   const internal::MatrixFreeFunctions::DoFInfo *dof_info;
 
   /**
-   * Stores a pointer to the underlying transformation data from unit to
-   * real cells for the given quadrature formula specified at construction.
-   * Also contained in matrix_info, but it simplifies code if we store a
-   * reference to it.
+   * Stores a pointer to the underlying transformation data from unit to real
+   * cells for the given quadrature formula specified at construction. Also
+   * contained in matrix_info, but it simplifies code if we store a reference
+   * to it.
    */
   const internal::MatrixFreeFunctions::MappingInfo<dim,Number> *mapping_info;
 
@@ -799,8 +797,8 @@ protected:
 
   /**
    * A pointer to the upper diagonal part of the Jacobian gradient on the
-   * present cell. Only set to a useful value if on a general cell with
-   * non-constant Jacobian.
+   * present cell. Only set to a useful value if on a general cell with non-
+   * constant Jacobian.
    */
   const Tensor<1,(dim>1?dim*(dim-1)/2:1),Tensor<1,dim,VectorizedArray<Number> > > * jacobian_grad_upper;
 
@@ -860,8 +858,8 @@ protected:
 
   /**
    * Debug information to track whether gradients on quadrature points have
-   * been submitted for integration before the integration is actually
-   * stared. Used to control exceptions when uninitialized data is used.
+   * been submitted for integration before the integration is actually stared.
+   * Used to control exceptions when uninitialized data is used.
    */
   bool gradients_quad_submitted;
 
@@ -899,10 +897,9 @@ protected:
 
 
 /**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Generic access is achieved through the base class, and
- * specializations for scalar and vector-valued elements are defined
- * separately.
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Generic access is achieved through the base class, and specializations for
+ * scalar and vector-valued elements are defined separately.
  *
  * @author Katharina Kormann and Martin Kronbichler, 2010, 2011
  */
@@ -953,9 +950,9 @@ protected:
 
 
 /**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for scalar fields that defines access with
- * simple data fields, i.e., scalars for the values and Tensor<1,dim> for the
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for scalar fields that defines access with simple
+ * data fields, i.e., scalars for the values and Tensor<1,dim> for the
  * gradients.
  *
  * @author Katharina Kormann and Martin Kronbichler, 2010, 2011
@@ -1016,11 +1013,11 @@ public:
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies what
-   * is tested by all basis function gradients on the current cell and
-   * integrated over.
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies what is
+   * tested by all basis function gradients on the current cell and integrated
+   * over.
    */
   void submit_gradient(const gradient_type grad_in,
                        const unsigned int  q_point);
@@ -1091,11 +1088,11 @@ protected:
 
 
 /**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for fields with as many components as the
- * underlying space dimension, i.e., values are of type Tensor<1,dim> and
- * gradients of type Tensor<2,dim>. Provides some additional functions for
- * access, like the symmetric gradient and divergence.
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for fields with as many components as the underlying
+ * space dimension, i.e., values are of type Tensor<1,dim> and gradients of
+ * type Tensor<2,dim>. Provides some additional functions for access, like the
+ * symmetric gradient and divergence.
  *
  * @author Katharina Kormann and Martin Kronbichler, 2010, 2011
  */
@@ -1155,21 +1152,21 @@ public:
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies what
-   * is tested by all basis function gradients on the current cell and
-   * integrated over.
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies what is
+   * tested by all basis function gradients on the current cell and integrated
+   * over.
    */
   void submit_gradient(const gradient_type grad_in,
                        const unsigned int  q_point);
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. This function is an alternative to the other submit_gradient
-   * function when using a system of fixed number of equations which happens
-   * to coincide with the dimension for some dimensions, but not all. To allow
+   * containing the values on quadrature points with component @p q_point.
+   * This function is an alternative to the other submit_gradient function
+   * when using a system of fixed number of equations which happens to
+   * coincide with the dimension for some dimensions, but not all. To allow
    * for dimension-independent programming, this function can be used instead.
    */
   void submit_gradient(const Tensor<1,dim,Tensor<1,dim,VectorizedArray<Number> > > grad_in,
@@ -1177,20 +1174,20 @@ public:
 
   /**
    * Write a constribution that is tested by the divergence to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies what
-   * is tested by all basis function gradients on the current cell and
-   * integrated over.
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies what is
+   * tested by all basis function gradients on the current cell and integrated
+   * over.
    */
   void submit_divergence (const VectorizedArray<Number> div_in,
                           const unsigned int q_point);
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies the
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies the
    * gradient which is tested by all basis function gradients on the current
    * cell and integrated over.
    */
@@ -1238,12 +1235,13 @@ protected:
 
 
 /**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for scalar fields in 1d that defines access with
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for scalar fields in 1d that defines access with
  * simple data fields, i.e., scalars for the values and Tensor<1,1> for the
  * gradients.
  *
- * @author Katharina Kormann and Martin Kronbichler, 2010, 2011, Shiva Rudraraju, 2014
+ * @author Katharina Kormann and Martin Kronbichler, 2010, 2011, Shiva
+ * Rudraraju, 2014
  */
 template <typename Number>
 class FEEvaluationAccess<1,1,Number> : public FEEvaluationBase<1,1,Number>
@@ -1301,11 +1299,11 @@ public:
 
   /**
    * Write a contribution that is tested by the gradient to the field
-   * containing the values on quadrature points with component @p
-   * q_point. Access to the same field as through @p get_gradient. If applied
-   * before the function @p integrate(...,true) is called, this specifies what
-   * is tested by all basis function gradients on the current cell and
-   * integrated over.
+   * containing the values on quadrature points with component @p q_point.
+   * Access to the same field as through @p get_gradient. If applied before
+   * the function @p integrate(...,true) is called, this specifies what is
+   * tested by all basis function gradients on the current cell and integrated
+   * over.
    */
   void submit_gradient(const gradient_type grad_in,
                        const unsigned int  q_point);
@@ -1392,8 +1390,8 @@ protected:
  * for applying a vector operation for several cells at once. This setting is
  * explained in the step-37 and step-48 tutorial programs. For vector-valued
  * problems, the deal.II test suite includes a few additional examples as
- * well, e.g. the Stokes operator found at
- * https://github.com/dealii/dealii/blob/master/tests/matrix_free/matrix_vector_stokes_noflux.cc
+ * well, e.g. the Stokes operator found at https://github.com/dealii/dealii/bl
+ * ob/master/tests/matrix_free/matrix_vector_stokes_noflux.cc
  *
  * For most operator evaluation tasks, this path provides the most efficient
  * solution by combining pre-computed data for the mapping (Jacobian
@@ -1414,9 +1412,9 @@ protected:
  * MatrixFree class may not be desired. In such a case, the cost to initialize
  * the necessary geometry data on the fly is comparably low and thus avoiding
  * a global object MatrixFree can be useful. When used in this way, reinit
- * methods reminiscent from FEValues with a cell iterator are to be
- * used. However, note that this model results in working on a single cell at
- * time, with geometry data duplicated in all components of the vectorized
+ * methods reminiscent from FEValues with a cell iterator are to be used.
+ * However, note that this model results in working on a single cell at a
+ * time, with geometry data duplicated in all components of the vectorized
  * array. Thus, vectorization is only useful when it can apply the same
  * operation on different data, e.g. when performing matrix assembly.
  *
@@ -1512,19 +1510,18 @@ protected:
  * @param dim Dimension in which this class is to be used
  *
  * @param fe_degree Degree of the tensor product finite element with
- *                  fe_degree+1 degrees of freedom per coordinate direction
+ * fe_degree+1 degrees of freedom per coordinate direction
  *
  * @param n_q_points_1d Number of points in the quadrature formula in 1D,
- *                   defaults to fe_degree+1
+ * defaults to fe_degree+1
  *
  * @param n_components Number of vector components when solving a system of
- *                  PDEs. If the same operation is applied to several
- *                  components of a PDE (e.g. a vector Laplace equation), they
- *                  can be applied simultaneously with one call (and often
- *                  more efficiently). Defaults to 1.
+ * PDEs. If the same operation is applied to several components of a PDE (e.g.
+ * a vector Laplace equation), they can be applied simultaneously with one
+ * call (and often more efficiently). Defaults to 1.
  *
- * @param Number Number format, usually @p double or @p float.
- *                  Defaults to @p double
+ * @param Number Number format, usually @p double or @p float. Defaults to @p
+ * double
  *
  * @author Katharina Kormann and Martin Kronbichler, 2010, 2011
  */
@@ -1555,15 +1552,15 @@ public:
   /**
    * Constructor that comes with reduced functionality and works similar as
    * FEValues. The arguments are similar to the ones passed to the constructor
-   * of FEValues, with the notable difference that FEEvaluation expects a
-   * one-dimensional quadrature formula, Quadrature<1>, instead of a @p dim
+   * of FEValues, with the notable difference that FEEvaluation expects a one-
+   * dimensional quadrature formula, Quadrature<1>, instead of a @p dim
    * dimensional one. The finite element can be both scalar or vector valued,
    * but this method always only selects a scalar base element at a time (with
-   * @p n_components copies as specified by the class template). For
-   * vector-valued elements, the optional argument @p first_selected_component
-   * allows to specify the index of the base element to be used for
-   * evaluation. Note that the internal data structures always assume that the
-   * base element is primitive, non-primitive are not supported currently.
+   * @p n_components copies as specified by the class template). For vector-
+   * valued elements, the optional argument @p first_selected_component allows
+   * to specify the index of the base element to be used for evaluation. Note
+   * that the internal data structures always assume that the base element is
+   * primitive, non-primitive are not supported currently.
    *
    * As known from FEValues, a call to the reinit method with a
    * Triangulation<dim>::cell_iterator is necessary to make the geometry and
index 0fc2c44c52c2bda0176a5ea98714c82c96858361..ac61d3fe2f3d013e13d2a98eadf92efb0c67c3bf 100644 (file)
@@ -37,10 +37,9 @@ namespace internal
     template <typename Number> struct ConstraintValues;
 
     /**
-     * A struct that collects all information
-     * related to parallelization with threads:
-     * The work is subdivided into tasks that can
-     * be done independently.
+     * A struct that collects all information related to parallelization with
+     * threads: The work is subdivided into tasks that can be done
+     * independently.
      */
     struct TaskInfo
     {
@@ -50,14 +49,12 @@ namespace internal
       TaskInfo ();
 
       /**
-       * Clears all the data fields and resets them
-       * to zero.
+       * Clears all the data fields and resets them to zero.
        */
       void clear ();
 
       /**
-       * Returns the memory consumption of
-       * the class.
+       * Returns the memory consumption of the class.
        */
       std::size_t memory_consumption () const;
 
@@ -85,9 +82,8 @@ namespace internal
 
 
     /**
-     * A struct that collects all information
-     * related to the size of the problem and MPI
-     * parallelization.
+     * A struct that collects all information related to the size of the
+     * problem and MPI parallelization.
      */
     struct SizeInfo
     {
@@ -97,23 +93,20 @@ namespace internal
       SizeInfo ();
 
       /**
-       * Clears all data fields and resets the sizes
-       * to zero.
+       * Clears all data fields and resets the sizes to zero.
        */
       void clear();
 
       /**
-       * Prints minimum, average, and
-       * maximal memory consumption over the
-       * MPI processes.
+       * Prints minimum, average, and maximal memory consumption over the MPI
+       * processes.
        */
       template <typename STREAM>
       void print_memory_statistics (STREAM     &out,
                                     std::size_t data_length) const;
 
       /**
-       * Determines the position of cells
-       * with ghosts for distributed-memory
+       * Determines the position of cells with ghosts for distributed-memory
        * calculations.
        */
       void make_layout (const unsigned int n_active_cells_in,
@@ -128,9 +121,8 @@ namespace internal
       unsigned int vectorization_length;
 
       /**
-       * index sets to describe the layout of cells:
-       * locally owned cells and locally active
-       * cells
+       * index sets to describe the layout of cells: locally owned cells and
+       * locally active cells
        */
       IndexSet locally_owned_cells;
       IndexSet ghost_cells;
@@ -150,15 +142,16 @@ namespace internal
 
 
     /**
-     * A class that is used to compare floating point arrays (e.g. std::vectors,
-     * Tensor<1,dim>, etc.). The idea of this class is to consider two arrays as
-     * equal if they are the same within a given tolerance. We use this
-     * comparator class within an std::map<> of the given arrays. Note that this
-     * comparison operator does not satisfy all the mathematical properties one
-     * usually wants to have (consider e.g. the numbers a=0, b=0.1, c=0.2 with
-     * tolerance 0.15; the operator gives a<c, but neither of a<b? or b<c? is
-     * satisfied). This is not a problem in the use cases for this class, but be
-     * careful when using it in other contexts.
+     * A class that is used to compare floating point arrays (e.g.
+     * std::vectors, Tensor<1,dim>, etc.). The idea of this class is to
+     * consider two arrays as equal if they are the same within a given
+     * tolerance. We use this comparator class within an std::map<> of the
+     * given arrays. Note that this comparison operator does not satisfy all
+     * the mathematical properties one usually wants to have (consider e.g.
+     * the numbers a=0, b=0.1, c=0.2 with tolerance 0.15; the operator gives
+     * a<c, but neither of a<b? or b<c? is satisfied). This is not a problem
+     * in the use cases for this class, but be careful when using it in other
+     * contexts.
      */
     template<typename Number>
     struct FPArrayComparator
index 678b971c1b2a9512bcd9dc9e94db39ae59e5abdb..feaf34450beea75a5dada9bb56ecd73bb05595b5 100644 (file)
@@ -60,8 +60,9 @@ namespace internal
     public:
       /**
        * Constructor, similar to FEValues. Since this class only evaluates the
-       * geometry, no finite element has to be specified and the simplest element,
-       * FE_Nothing, is used internally for the underlying FEValues object.
+       * geometry, no finite element has to be specified and the simplest
+       * element, FE_Nothing, is used internally for the underlying FEValues
+       * object.
        */
       MappingDataOnTheFly (const Mapping<dim> &mapping,
                            const Quadrature<1> &quadrature,
@@ -91,16 +92,16 @@ namespace internal
 
       /**
        * Return a reference to the underlying FEValues object that evaluates
-       * certain quantities (only mapping-related ones like Jacobians or mapped
-       * quadrature points are accessible, as no finite element data is actually
-       * used).
+       * certain quantities (only mapping-related ones like Jacobians or
+       * mapped quadrature points are accessible, as no finite element data is
+       * actually used).
        */
       const FEValues<dim> &get_fe_values () const;
 
       /**
-       * Return a vector of inverse transpose Jacobians. For compatibility with
-       * FEEvaluation, it returns tensors of vectorized arrays, even though all
-       * components are equal.
+       * Return a vector of inverse transpose Jacobians. For compatibility
+       * with FEEvaluation, it returns tensors of vectorized arrays, even
+       * though all components are equal.
        */
       const AlignedVector<Tensor<2,dim,VectorizedArray<Number> > > &
       get_inverse_jacobians() const;
@@ -114,17 +115,17 @@ namespace internal
       get_JxW_values() const;
 
       /**
-       * Return a vector of quadrature points in real space on the given
-       * cell. For compatibility with FEEvaluation, it returns tensors of
-       * vectorized arrays, even though all components are equal.
+       * Return a vector of quadrature points in real space on the given cell.
+       * For compatibility with FEEvaluation, it returns tensors of vectorized
+       * arrays, even though all components are equal.
        */
       const AlignedVector<Point<dim,VectorizedArray<Number> > > &
       get_quadrature_points() const;
 
       /**
-       * Return a vector of quadrature points in real space on the given
-       * cell. For compatibility with FEEvaluation, it returns tensors of
-       * vectorized arrays, even though all components are equal.
+       * Return a vector of quadrature points in real space on the given cell.
+       * For compatibility with FEEvaluation, it returns tensors of vectorized
+       * arrays, even though all components are equal.
        */
       const AlignedVector<Tensor<1,dim,VectorizedArray<Number> > > &
       get_normal_vectors() const;
index 861ec4bc073bd78c02c5bbd0e3cc0af86590eca5..0b89cf63fcdf23e8492a7d35180546f849954118 100644 (file)
@@ -52,13 +52,14 @@ namespace internal
       static const std::size_t  n_cell_type_bits = 2;
 
       /**
-       * Determines how many types of different cells can be detected at
-       * most. Corresponds to the number of bits we reserved for it.
+       * Determines how many types of different cells can be detected at most.
+       * Corresponds to the number of bits we reserved for it.
        */
       static const unsigned int n_cell_types = 1U<<n_cell_type_bits;
 
       /**
-       * An abbreviation for the length of vector lines of the current data type.
+       * An abbreviation for the length of vector lines of the current data
+       * type.
        */
       static const unsigned int n_vector_elements = VectorizedArray<Number>::n_array_elements;
 
@@ -188,9 +189,9 @@ namespace internal
         /**
          * Stores the diagonal part of the gradient of the inverse Jacobian
          * transformation. The first index runs over the derivatives
-         * $\partial^2/\partial x_i^2$, the second over the space
-         * coordinate. Needed for computing the Laplacian of FE functions on
-         * the real cell. Uses a separate storage from the off-diagonal part
+         * $\partial^2/\partial x_i^2$, the second over the space coordinate.
+         * Needed for computing the Laplacian of FE functions on the real
+         * cell. Uses a separate storage from the off-diagonal part
          * $\partial^2/\partial x_i \partial x_j, i\neq j$ because that is
          * only needed for computing a full Hessian.
          */
index d5c5b698b845a9b4423766cff5a8e86641a96e81..875bfd046d39b0a22007c63d04f1bd3bfc9d1c62 100644 (file)
@@ -69,26 +69,25 @@ DEAL_II_NAMESPACE_OPEN
  * The stored data can be subdivided into three main components:
  *
  * - DoFInfo: It stores how local degrees of freedom relate to global degrees
- *   of freedom. It includes a description of constraints that are evaluated
- *   as going through all local degrees of freedom on a cell.
+ * of freedom. It includes a description of constraints that are evaluated as
+ * going through all local degrees of freedom on a cell.
  *
  * - MappingInfo: It stores the transformations from real to unit cells that
- *   are necessary in order to build derivatives of finite element functions
- *   and find location of quadrature weights in physical space.
+ * are necessary in order to build derivatives of finite element functions and
+ * find location of quadrature weights in physical space.
  *
  * - ShapeInfo: It contains the shape functions of the finite element,
- *   evaluated on the unit cell.
+ * evaluated on the unit cell.
  *
- * Besides the initialization routines, this class implements only a
- * single operation, namely a loop over all cells (cell_loop()). This
- * loop is scheduled in such a way that cells that share degrees of
- * freedom are not worked on simultaneously, which implies that it is
- * possible to write to vectors (or matrices) in parallel without
- * having to explicitly synchronize access to these vectors and
- * matrices. This class does not implement any shape values, all it
- * does is to cache the respective data. To implement finite element
- * operations, use the class FEEvaluation (or some of the related
- * classes).
+ * Besides the initialization routines, this class implements only a single
+ * operation, namely a loop over all cells (cell_loop()). This loop is
+ * scheduled in such a way that cells that share degrees of freedom are not
+ * worked on simultaneously, which implies that it is possible to write to
+ * vectors (or matrices) in parallel without having to explicitly synchronize
+ * access to these vectors and matrices. This class does not implement any
+ * shape values, all it does is to cache the respective data. To implement
+ * finite element operations, use the class FEEvaluation (or some of the
+ * related classes).
  *
  * This class traverses the cells in a different order than the usual
  * Triangulation class in deal.II, in order to be flexible with respect to
@@ -173,13 +172,12 @@ public:
     MPI_Comm            mpi_communicator;
 
     /**
-     * Sets the scheme for task parallelism. There are four options
-     * available. If set to @p none, the operator application is done in
-     * serial without shared memory parallelism. If this class is used
-     * together with MPI and MPI is also used for parallelism within the
-     * nodes, this flag should be set to @p none. The default value is @p
-     * partition_partition, i.e. we actually use multithreading with the first
-     * option described below.
+     * Sets the scheme for task parallelism. There are four options available.
+     * If set to @p none, the operator application is done in serial without
+     * shared memory parallelism. If this class is used together with MPI and
+     * MPI is also used for parallelism within the nodes, this flag should be
+     * set to @p none. The default value is @p partition_partition, i.e. we
+     * actually use multithreading with the first option described below.
      *
      * The first option @p partition_partition is to partition the cells on
      * two levels in onion-skin-like partitions and forming chunks of
@@ -206,10 +204,9 @@ public:
     /**
      * Sets the number of so-called macro cells that should form one
      * partition. If zero size is given, the class tries to find a good size
-     * for the blocks based on
-     * multithread_info.n_threads() and the number of cells
-     * present. Otherwise, the given number is used. If the given number is
-     * larger than one third of the number of total cells, this means no
+     * for the blocks based on multithread_info.n_threads() and the number of
+     * cells present. Otherwise, the given number is used. If the given number
+     * is larger than one third of the number of total cells, this means no
      * parallelism. Note that in the case vectorization is used, a macro cell
      * consists of more than one physical cell.
      */
@@ -275,26 +272,27 @@ public:
   MatrixFree ();
 
   /**
-  * Destructor.
-  */
+   * Destructor.
+   */
   ~MatrixFree();
 
   /**
-  * Extracts the information needed to perform loops over cells. The
-  * DoFHandler and ConstraintMatrix describe the layout of degrees of freedom,
-  * the DoFHandler and the mapping describe the transformations from unit to
-  * real cell, and the finite element underlying the DoFHandler together with
-  * the quadrature formula describe the local operations. Note that the finite
-  * element underlying the DoFHandler must either be scalar or contain several
-  * copies of the same element. Mixing several different elements into one
-  * FESystem is not allowed. In that case, use the initialization function
-  * with several DoFHandler arguments.
-  *
-  * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
-  * partitioning with MPI. Usually, this needs not be specified, and the other
-  * initialization function without and @p IndexSet description can be used,
-  * which gets the partitioning information builtin into the DoFHandler.
-  */
+   * Extracts the information needed to perform loops over cells. The
+   * DoFHandler and ConstraintMatrix describe the layout of degrees of
+   * freedom, the DoFHandler and the mapping describe the transformations from
+   * unit to real cell, and the finite element underlying the DoFHandler
+   * together with the quadrature formula describe the local operations. Note
+   * that the finite element underlying the DoFHandler must either be scalar
+   * or contain several copies of the same element. Mixing several different
+   * elements into one FESystem is not allowed. In that case, use the
+   * initialization function with several DoFHandler arguments.
+   *
+   * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
+   * partitioning with MPI. Usually, this needs not be specified, and the
+   * other initialization function without and @p IndexSet description can be
+   * used, which gets the partitioning information builtin into the
+   * DoFHandler.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const Mapping<dim>     &mapping,
                const DH               &dof_handler,
@@ -304,9 +302,9 @@ public:
                const AdditionalData    additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as above, but with index set stored
-  * in the DoFHandler for describing the locally owned degrees of freedom.
-  */
+   * Initializes the data structures. Same as above, but with index set stored
+   * in the DoFHandler for describing the locally owned degrees of freedom.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const Mapping<dim>     &mapping,
                const DH               &dof_handler,
@@ -315,9 +313,9 @@ public:
                const AdditionalData    additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as above, but with mapping @p
-  * MappingQ1.
-  */
+   * Initializes the data structures. Same as above, but with mapping @p
+   * MappingQ1.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const DH               &dof_handler,
                const ConstraintMatrix &constraint,
@@ -325,31 +323,31 @@ public:
                const AdditionalData    additional_data = AdditionalData());
 
   /**
-  * Extracts the information needed to perform loops over cells. The
-  * DoFHandler and ConstraintMatrix describe the layout of degrees of freedom,
-  * the DoFHandler and the mapping describe the transformations from unit to
-  * real cell, and the finite element underlying the DoFHandler together with
-  * the quadrature formula describe the local operations. As opposed to the
-  * scalar case treated with the other initialization functions, this function
-  * allows for problems with two or more different finite elements. The
-  * DoFHandlers to each element must be passed as pointers to the
-  * initialization function. Note that the finite element underlying an
-  * DoFHandler must either be scalar or contain several copies of the same
-  * element. Mixing several different elements into one @p FE_System is not
-  * allowed.
-  *
-  * This function also allows for using several quadrature formulas, e.g. when
-  * the description contains independent integrations of elements of different
-  * degrees. However, the number of different quadrature formulas can be sets
-  * independently from the number of DoFHandlers, when several elements are
-  * always integrated with the same quadrature formula.
-  *
-  * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
-  * partitioning with MPI. Usually, this needs not be specified, and the other
-  * initialization function without and @p IndexSet description can be used,
-  * which gets the partitioning information from the DoFHandler. This is the
-  * most general initialization function.
-  */
+   * Extracts the information needed to perform loops over cells. The
+   * DoFHandler and ConstraintMatrix describe the layout of degrees of
+   * freedom, the DoFHandler and the mapping describe the transformations from
+   * unit to real cell, and the finite element underlying the DoFHandler
+   * together with the quadrature formula describe the local operations. As
+   * opposed to the scalar case treated with the other initialization
+   * functions, this function allows for problems with two or more different
+   * finite elements. The DoFHandlers to each element must be passed as
+   * pointers to the initialization function. Note that the finite element
+   * underlying an DoFHandler must either be scalar or contain several copies
+   * of the same element. Mixing several different elements into one @p
+   * FE_System is not allowed.
+   *
+   * This function also allows for using several quadrature formulas, e.g.
+   * when the description contains independent integrations of elements of
+   * different degrees. However, the number of different quadrature formulas
+   * can be sets independently from the number of DoFHandlers, when several
+   * elements are always integrated with the same quadrature formula.
+   *
+   * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
+   * partitioning with MPI. Usually, this needs not be specified, and the
+   * other initialization function without and @p IndexSet description can be
+   * used, which gets the partitioning information from the DoFHandler. This
+   * is the most general initialization function.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const Mapping<dim>                         &mapping,
                const std::vector<const DH *>               &dof_handler,
@@ -359,10 +357,10 @@ public:
                const AdditionalData                        additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as before, but now the index set
-  * description of the locally owned range of degrees of freedom is taken from
-  * the DoFHandler.
-  */
+   * Initializes the data structures. Same as before, but now the index set
+   * description of the locally owned range of degrees of freedom is taken
+   * from the DoFHandler.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const Mapping<dim>                         &mapping,
                const std::vector<const DH *>               &dof_handler,
@@ -371,9 +369,9 @@ public:
                const AdditionalData                        additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as above, but with mapping @p
-  * MappingQ1.
-  */
+   * Initializes the data structures. Same as above, but with mapping @p
+   * MappingQ1.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const std::vector<const DH *>               &dof_handler,
                const std::vector<const ConstraintMatrix *> &constraint,
@@ -381,12 +379,12 @@ public:
                const AdditionalData                        additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as before, but now the index set
-  * description of the locally owned range of degrees of freedom is taken from
-  * the DoFHandler. Moreover, only a single quadrature formula is used, as
-  * might be necessary when several components in a vector-valued problem are
-  * integrated together based on the same quadrature formula.
-  */
+   * Initializes the data structures. Same as before, but now the index set
+   * description of the locally owned range of degrees of freedom is taken
+   * from the DoFHandler. Moreover, only a single quadrature formula is used,
+   * as might be necessary when several components in a vector-valued problem
+   * are integrated together based on the same quadrature formula.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const Mapping<dim>                         &mapping,
                const std::vector<const DH *>               &dof_handler,
@@ -395,9 +393,9 @@ public:
                const AdditionalData                        additional_data = AdditionalData());
 
   /**
-  * Initializes the data structures. Same as above, but with mapping @p
-  * MappingQ1.
-  */
+   * Initializes the data structures. Same as above, but with mapping @p
+   * MappingQ1.
+   */
   template <typename DH, typename Quadrature>
   void reinit (const std::vector<const DH *>               &dof_handler,
                const std::vector<const ConstraintMatrix *> &constraint,
@@ -568,8 +566,8 @@ public:
   get_constrained_dofs (const unsigned int fe_component = 0) const;
 
   /**
-   * Calls renumber_dofs function in dof_info which renumbers the degrees
-   * of freedom according to the ordering for parallelization.
+   * Calls renumber_dofs function in dof_info which renumbers the degrees of
+   * freedom according to the ordering for parallelization.
    */
   void renumber_dofs (std::vector<types::global_dof_index> &renumbering,
                       const unsigned int vector_component = 0);
index d8609b4cdf55e6d670ea526a40556590b412ed4c..dec85a1a6e08c8ad8909b8328381bb88b1750765 100644 (file)
@@ -30,19 +30,19 @@ DEAL_II_NAMESPACE_OPEN
 namespace MatrixFreeOperators
 {
   /**
-   * This class implements the operation of the action of the inverse of a mass
-   * matrix on an element for the special case of an evaluation object with as
-   * many quadrature points as there are cell degrees of freedom. It uses
-   * algorithms from FEEvaluation and produces the exact mass matrix for DGQ
-   * elements. This algorithm uses tensor products of inverse 1D shape matrices
-   * over quadrature points, so the inverse operation is exactly as expensive as
-   * applying the forward operator on each cell. Of course, for continuous
-   * finite elements this operation does not produce the inverse of a mass
-   * operation as the coupling between the elements cannot be considered by this
-   * operation.
+   * This class implements the operation of the action of the inverse of a
+   * mass matrix on an element for the special case of an evaluation object
+   * with as many quadrature points as there are cell degrees of freedom. It
+   * uses algorithms from FEEvaluation and produces the exact mass matrix for
+   * DGQ elements. This algorithm uses tensor products of inverse 1D shape
+   * matrices over quadrature points, so the inverse operation is exactly as
+   * expensive as applying the forward operator on each cell. Of course, for
+   * continuous finite elements this operation does not produce the inverse of
+   * a mass operation as the coupling between the elements cannot be
+   * considered by this operation.
    *
-   * The equation may contain variable coefficients, so the user is required to
-   * provide an array for the inverse of the local coefficient (this class
+   * The equation may contain variable coefficients, so the user is required
+   * to provide an array for the inverse of the local coefficient (this class
    * provide a helper method 'fill_inverse_JxW_values' to get the inverse of a
    * constant-coefficient operator).
    *
@@ -62,9 +62,9 @@ namespace MatrixFreeOperators
      * Applies the inverse mass matrix operation on an input array. It is
      * assumed that the passed input and output arrays are of correct size,
      * namely FEEval::dofs_per_cell * n_components long. The inverse of the
-     * local coefficient (also containing the inverse JxW values) must be passed
-     * as first argument. Passing more than one component in the coefficient is
-     * allowed.
+     * local coefficient (also containing the inverse JxW values) must be
+     * passed as first argument. Passing more than one component in the
+     * coefficient is allowed.
      */
     void apply(const AlignedVector<VectorizedArray<Number> > &inverse_coefficient,
                const unsigned int             n_actual_components,
index f9f5b308a4ad277081b636f9f4f5f40c999c63df..7d14d79fa187e3679623326042bef89017d72a86 100644 (file)
@@ -74,9 +74,9 @@ namespace internal
       /**
        * Initializes the data fields. Takes a one-dimensional quadrature
        * formula and a finite element as arguments and evaluates the shape
-       * functions, gradients and Hessians on the one-dimensional unit
-       * cell. This function assumes that the finite element is derived from a
-       * one-dimensional element by a tensor product and that the zeroth shape
+       * functions, gradients and Hessians on the one-dimensional unit cell.
+       * This function assumes that the finite element is derived from a one-
+       * dimensional element by a tensor product and that the zeroth shape
        * function in zero evaluates to one.
        */
       template <int dim>
@@ -131,8 +131,8 @@ namespace internal
       AlignedVector<VectorizedArray<Number> > shape_val_evenodd;
 
       /**
-       * Stores the shape gradients in a different format, namely the
-       * so-called even-odd scheme where the symmetries in shape_gradients are
+       * Stores the shape gradients in a different format, namely the so-
+       * called even-odd scheme where the symmetries in shape_gradients are
        * used for faster evaluation.
        */
       AlignedVector<VectorizedArray<Number> > shape_gra_evenodd;
index 1354435d12a1971a22bf23463f37b06a71e32333..c729f451e85f4f3fa5ec7272abe3de694b043122 100644 (file)
@@ -33,51 +33,49 @@ namespace MeshWorker
 {
   /**
    * The namespace containing objects that can be used to assemble data
-   * computed on cells and faces into global objects. This can reach
-   * from collecting the total error estimate from cell and face
-   * contributions to assembling matrices and multilevel matrices.
+   * computed on cells and faces into global objects. This can reach from
+   * collecting the total error estimate from cell and face contributions to
+   * assembling matrices and multilevel matrices.
    *
    * <h3>Data models</h3>
    *
-   * The class chosen from this namespace determines which data model is
-   * used. For the local as well as the global objects, we have the
-   * choice between two models:
+   * The class chosen from this namespace determines which data model is used.
+   * For the local as well as the global objects, we have the choice between
+   * two models:
    *
    * <h4>The comprehensive data model</h4>
    *
-   * This is the structure set up by the FESystem class. Globally, this
-   * means, data is assembled into one residual vector and into one
-   * matrix. These objects may be block vectors and block matrices, but
-   * the process of assembling ignores this fact.
+   * This is the structure set up by the FESystem class. Globally, this means,
+   * data is assembled into one residual vector and into one matrix. These
+   * objects may be block vectors and block matrices, but the process of
+   * assembling ignores this fact.
    *
    * Similarly, there is only a single cell vector and cell matrix,
-   * respectively, which is indexed by all degrees of freedom of the
-   * FESystem. When building the cell matrix, it is necessary to
-   * distinguish between the different components of the system and
-   * select the right operator for each pair.
+   * respectively, which is indexed by all degrees of freedom of the FESystem.
+   * When building the cell matrix, it is necessary to distinguish between the
+   * different components of the system and select the right operator for each
+   * pair.
    *
    * <h4>The blocked data model</h4>
    *
-   * Here, all the blocks are treated separately (in spite of using
-   * FESystem for its convenience in other places). For instance, no
-   * block matrix is assembled, but a list of blocks, which can be
-   * combined later by BlockMatrixArray. Locally, this means, that each
-   * matrix block of a system is generated separately and assembled into
-   * the corresponding global block.
+   * Here, all the blocks are treated separately (in spite of using FESystem
+   * for its convenience in other places). For instance, no block matrix is
+   * assembled, but a list of blocks, which can be combined later by
+   * BlockMatrixArray. Locally, this means, that each matrix block of a system
+   * is generated separately and assembled into the corresponding global
+   * block.
    *
-   * This approach is advantageous, if the number of matrices for each
-   * block position in the global system is different. For instance,
-   * block preconditioners for the Oseen problem require 3 pressure
-   * matrices, but only one divergence and one advection-diffusion
-   * operator for velocities.
+   * This approach is advantageous, if the number of matrices for each block
+   * position in the global system is different. For instance, block
+   * preconditioners for the Oseen problem require 3 pressure matrices, but
+   * only one divergence and one advection-diffusion operator for velocities.
    *
    * Additionally, this approach enables the construction of a system of
-   * equations from building blocks for each equation and coupling
-   * operator.
+   * equations from building blocks for each equation and coupling operator.
    *
-   * Nevertheless, since a separate FEValues object must be created for
-   * each base element, it is not quite clear a priori, which data model
-   * is more efficient.
+   * Nevertheless, since a separate FEValues object must be created for each
+   * base element, it is not quite clear a priori, which data model is more
+   * efficient.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -87,18 +85,17 @@ namespace MeshWorker
     /**
      * Assemble local residuals into global residuals.
      *
-     * The global residuals are expected as an FEVectors object.
-     * The local residuals are block vectors.
+     * The global residuals are expected as an FEVectors object. The local
+     * residuals are block vectors.
      *
      * Depending on whether the BlockInfo object was initialize with
-     * BlockInfo::initialize_local(), the comprehensive or block data
-     * model is used locally.
+     * BlockInfo::initialize_local(), the comprehensive or block data model is
+     * used locally.
      *
-     * In the block model, each of the blocks of the local vectors
-     * corresponds to the restriction of a single block of the system to
-     * this cell (@ref GlossBlock). Thus, the size of this local block is
-     * the number of degrees of freedom of the corresponding base element
-     * of the FESystem.
+     * In the block model, each of the blocks of the local vectors corresponds
+     * to the restriction of a single block of the system to this cell (@ref
+     * GlossBlock). Thus, the size of this local block is the number of
+     * degrees of freedom of the corresponding base element of the FESystem.
      *
      * @todo Comprehensive model currently not implemented.
      *
@@ -110,9 +107,7 @@ namespace MeshWorker
     {
     public:
       /**
-       * Copy the BlockInfo and the
-       * matrix pointers into local
-       * variables.
+       * Copy the BlockInfo and the matrix pointers into local variables.
        */
       void initialize(const BlockInfo *block_info,
                       NamedData<VECTOR *> &residuals);
@@ -121,49 +116,38 @@ namespace MeshWorker
        */
       void initialize(const ConstraintMatrix &constraints);
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
 
 
       /**
-       * Assemble the local residuals
-       * into the global residuals.
+       * Assemble the local residuals into the global residuals.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local residuals
-       * into the global residuals.
+       * Assemble both local residuals into the global residuals.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
                     const DOFINFO &info2);
     private:
       /**
-       * Assemble a single local
-       * residual into the global.
+       * Assemble a single local residual into the global.
        */
       void assemble(VECTOR &global,
                     const BlockVector<double> &local,
                     const std::vector<types::global_dof_index> &dof);
 
       /**
-       * The global matrices,
-       * stored as a vector of
-       * pointers.
+       * The global matrices, stored as a vector of pointers.
        */
       NamedData<SmartPointer<VECTOR,
                 ResidualLocalBlocksToGlobalBlocks<VECTOR> > > residuals;
@@ -184,26 +168,26 @@ namespace MeshWorker
     /**
      * A helper class assembling local matrices into global matrices.
      *
-     * The global matrices are expected as a vector of MatrixBlock
-     * objects, each containing a matrix object with a function
-     * corresponding to SparseMatrix::add() and information on the block
-     * row and column this matrix represents in a block system.
+     * The global matrices are expected as a vector of MatrixBlock objects,
+     * each containing a matrix object with a function corresponding to
+     * SparseMatrix::add() and information on the block row and column this
+     * matrix represents in a block system.
      *
      * The local matrices are expected as a similar vector of MatrixBlock
      * objects, but containing a FullMatrix.
      *
-     * Like with ResidualLocalBlocksToGlobalBlocks, the initialization of
-     * the BlockInfo object decides whether the comprehensive data model
-     * or the block model is used.
+     * Like with ResidualLocalBlocksToGlobalBlocks, the initialization of the
+     * BlockInfo object decides whether the comprehensive data model or the
+     * block model is used.
      *
      * In the comprehensive model, each of the LocalMatrixBlocks has
      * coordinates (0,0) and dimensions equal to the number of degrees of
      * freedom of the FESystem.
      *
-     * In the comprehensive model, each block has its own block
-     * coordinates and the size depends on the associated
-     * FESystem::base_element(). These blocks can be generated separately
-     * and will be assembled into the correct matrix block by this object.
+     * In the comprehensive model, each block has its own block coordinates
+     * and the size depends on the associated FESystem::base_element(). These
+     * blocks can be generated separately and will be assembled into the
+     * correct matrix block by this object.
      *
      * @ingroup MeshWorker
      * @author Guido Kanschat, 2009
@@ -213,19 +197,14 @@ namespace MeshWorker
     {
     public:
       /**
-       * Constructor, initializing
-       * the #threshold, which
-       * limits how small numbers
-       * may be to be entered into
-       * the matrix.
+       * Constructor, initializing the #threshold, which limits how small
+       * numbers may be to be entered into the matrix.
        */
       MatrixLocalBlocksToGlobalBlocks(double threshold = 1.e-12);
 
       /**
-       * Copy the BlockInfo and the
-       * matrix pointers into local
-       * variables and initialize
-       * cell matrix vectors.
+       * Copy the BlockInfo and the matrix pointers into local variables and
+       * initialize cell matrix vectors.
        */
       void initialize(const BlockInfo *block_info,
                       MatrixBlockVector<MATRIX> &matrices);
@@ -235,32 +214,24 @@ namespace MeshWorker
        */
       void initialize(const ConstraintMatrix &constraints);
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
 
 
       /**
-       * Assemble the local matrices
-       * into the global matrices.
+       * Assemble the local matrices into the global matrices.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble all local matrices
-       * into the global matrices.
+       * Assemble all local matrices into the global matrices.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
@@ -268,8 +239,7 @@ namespace MeshWorker
 
     private:
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble(
         MatrixBlock<MATRIX> &global,
@@ -280,9 +250,7 @@ namespace MeshWorker
         const std::vector<types::global_dof_index> &dof2);
 
       /**
-       * The global matrices,
-       * stored as a vector of
-       * pointers.
+       * The global matrices, stored as a vector of pointers.
        */
       SmartPointer<MatrixBlockVector<MATRIX>,
                    MatrixLocalBlocksToGlobalBlocks<MATRIX, number> > matrices;
@@ -299,12 +267,8 @@ namespace MeshWorker
                    MatrixLocalBlocksToGlobalBlocks<MATRIX,number> > constraints;
 
       /**
-       * The smallest positive
-       * number that will be
-       * entered into the global
-       * matrix. All smaller
-       * absolute values will be
-       * treated as zero and will
+       * The smallest positive number that will be entered into the global
+       * matrix. All smaller absolute values will be treated as zero and will
        * not be assembled.
        */
       const double threshold;
@@ -314,21 +278,21 @@ namespace MeshWorker
     /**
      * A helper class assembling local matrices into global multilevel
      * matrices. This class is the multilevel equivalent of
-     * MatrixLocalBlocksToGlobalBlocks and documentation of that class
-     * applies here to a large extend.
+     * MatrixLocalBlocksToGlobalBlocks and documentation of that class applies
+     * here to a large extend.
      *
      * The global matrices are expected as a vector of pointers to MatrixBlock
      * objects, each containing a MGLevelObject with matrices with a function
-     * corresponding to SparseMatrix::add() and information on the block
-     * row and column this matrix represents in a block system.
+     * corresponding to SparseMatrix::add() and information on the block row
+     * and column this matrix represents in a block system.
      *
      * The local matrices are a similar vector of MatrixBlock objects, but
      * containing a FullMatrix.
      *
-     * If local refinement occurs, the Multigrid method needs more
-     * matrices, two for continuous elements and another two if numerical
-     * fluxes are computed on interfaces. The second set can be added
-     * using initialize_edge_flux(). Once added, the contributions in all
+     * If local refinement occurs, the Multigrid method needs more matrices,
+     * two for continuous elements and another two if numerical fluxes are
+     * computed on interfaces. The second set can be added using
+     * initialize_edge_flux(). Once added, the contributions in all
      * participating matrices will be assembled from the cell and face
      * matrices automatically.
      *
@@ -344,81 +308,55 @@ namespace MeshWorker
       MatrixPtrVectorPtr;
 
       /**
-       * Constructor, initializing
-       * the #threshold, which
-       * limits how small numbers
-       * may be to be entered into
-       * the matrix.
+       * Constructor, initializing the #threshold, which limits how small
+       * numbers may be to be entered into the matrix.
        */
       MGMatrixLocalBlocksToGlobalBlocks(double threshold = 1.e-12);
 
       /**
-       * Copy the BlockInfo and the
-       * matrix pointers into local
-       * variables and initialize
-       * cell matrix vectors.
+       * Copy the BlockInfo and the matrix pointers into local variables and
+       * initialize cell matrix vectors.
        */
       void initialize(const BlockInfo *block_info,
                       MatrixPtrVector &matrices);
 
       /**
-       * Initialize the multilevel
-       * constraints.
+       * Initialize the multilevel constraints.
        */
       void initialize(const MGConstrainedDoFs &mg_constrained_dofs);
 
       /**
-       * Multigrid methods on
-       * locally refined meshes
-       * need additional
-       * matrices. For
-       * discontinuous Galerkin
-       * methods, these are two
-       * flux matrices across the
-       * refinement edge, which are
-       * set by this method.
+       * Multigrid methods on locally refined meshes need additional matrices.
+       * For discontinuous Galerkin methods, these are two flux matrices
+       * across the refinement edge, which are set by this method.
        */
       void initialize_edge_flux(MatrixPtrVector &up, MatrixPtrVector &down);
 
       /**
-       * Multigrid methods on
-       * locally refined meshes
-       * need additional
-       * matrices. For
-       * discontinuous Galerkin
-       * methods, these are two
-       * flux matrices across the
-       * refinement edge, which are
-       * set by this method.
+       * Multigrid methods on locally refined meshes need additional matrices.
+       * For discontinuous Galerkin methods, these are two flux matrices
+       * across the refinement edge, which are set by this method.
        */
       void initialize_interfaces (MatrixPtrVector &interface_in, MatrixPtrVector &interface_out);
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
 
 
       /**
-       * Assemble the local matrices
-       * into the global matrices.
+       * Assemble the local matrices into the global matrices.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble all local matrices
-       * into the global matrices.
+       * Assemble all local matrices into the global matrices.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
@@ -426,8 +364,7 @@ namespace MeshWorker
 
     private:
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble(
         MATRIX &global,
@@ -441,8 +378,7 @@ namespace MeshWorker
         bool transpose = false);
 
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble_fluxes(
         MATRIX &global,
@@ -455,8 +391,7 @@ namespace MeshWorker
         const unsigned int level2);
 
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble_up(
         MATRIX &global,
@@ -469,8 +404,7 @@ namespace MeshWorker
         const unsigned int level2);
 
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble_down(
         MATRIX &global,
@@ -483,8 +417,7 @@ namespace MeshWorker
         const unsigned int level2);
 
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble_in(
         MATRIX &global,
@@ -497,8 +430,7 @@ namespace MeshWorker
         const unsigned int level2);
 
       /**
-       * Assemble a single local
-       * matrix into a global one.
+       * Assemble a single local matrix into a global one.
        */
       void assemble_out(
         MATRIX &global,
@@ -511,37 +443,31 @@ namespace MeshWorker
         const unsigned int level2);
 
       /**
-       * The level matrices,
-       * stored as a vector of
-       * pointers.
+       * The level matrices, stored as a vector of pointers.
        */
       MatrixPtrVectorPtr matrices;
 
       /**
-       * The flux matrix between
-       * the fine and the coarse
-       * level at refinement edges.
+       * The flux matrix between the fine and the coarse level at refinement
+       * edges.
        */
       MatrixPtrVectorPtr flux_down;
 
       /**
-       * The flux matrix between
-       * the coarse and the fine
-       * level at refinement edges.
+       * The flux matrix between the coarse and the fine level at refinement
+       * edges.
        */
       MatrixPtrVectorPtr flux_up;
 
       /**
-       * The interface matrix between
-       * the fine and the coarse
-       * level at refinement edges.
+       * The interface matrix between the fine and the coarse level at
+       * refinement edges.
        */
       MatrixPtrVectorPtr interface_out;
 
       /**
-       * The interface matrix between
-       * the coarse and the fine
-       * level at refinement edges.
+       * The interface matrix between the coarse and the fine level at
+       * refinement edges.
        */
       MatrixPtrVectorPtr interface_in;
 
@@ -557,12 +483,8 @@ namespace MeshWorker
 
 
       /**
-       * The smallest positive
-       * number that will be
-       * entered into the global
-       * matrix. All smaller
-       * absolute values will be
-       * treated as zero and will
+       * The smallest positive number that will be entered into the global
+       * matrix. All smaller absolute values will be treated as zero and will
        * not be assembled.
        */
       const double threshold;
index 25f51a233d093398792b2f43a714d8a4b9c53db7..6c5e31490a64ae47c003098a94643bb38054962a 100644 (file)
@@ -33,35 +33,33 @@ namespace MeshWorker
 
 
   /**
-   * A class containing information on geometry and degrees of freedom
-   * of a mesh object.
+   * A class containing information on geometry and degrees of freedom of a
+   * mesh object.
    *
-   * The information in these objects is usually used by one of the
-   * Assembler classes. It is also the kind of information which is
-   * needed in mesh based matrices (often referred to as matrix free
-   * methods).
+   * The information in these objects is usually used by one of the Assembler
+   * classes. It is also the kind of information which is needed in mesh based
+   * matrices (often referred to as matrix free methods).
    *
    * In addition to the information on degrees of freedom stored in this
-   * class, it also provides the local computation space for the worker
-   * object operating on it in LocalResults. This base class will automatically
-   * be reinitialized on each cell, but initial setup is up to the user and
+   * class, it also provides the local computation space for the worker object
+   * operating on it in LocalResults. This base class will automatically be
+   * reinitialized on each cell, but initial setup is up to the user and
    * should be done when initialize() for this class is called.
    *
-   * This class operates in two different modes, corresponding to the
-   * data models discussed in the Assembler namespace documentation.
+   * This class operates in two different modes, corresponding to the data
+   * models discussed in the Assembler namespace documentation.
    *
    * The choice of the local data model is triggered by the vector
    * BlockInfo::local_renumbering, which in turn is usually filled by
-   * BlockInfo::initialize_local(). If this function has been used, or
-   * the vector has been changed from zero-length, then local dof
-   * indices stored in this object will automatically be renumbered to
-   * reflect local block structure. This means, the first entries in
-   * @p indices will refer to the first block of the system, then comes
-   * the second block and so on.
+   * BlockInfo::initialize_local(). If this function has been used, or the
+   * vector has been changed from zero-length, then local dof indices stored
+   * in this object will automatically be renumbered to reflect local block
+   * structure. This means, the first entries in @p indices will refer to the
+   * first block of the system, then comes the second block and so on.
    *
-   * The BlockInfo object is stored as a pointer. Therefore, if the
-   * block structure changes, for instance because of mesh refinement,
-   * the DoFInfo class will automatically use the new structures.
+   * The BlockInfo object is stored as a pointer. Therefore, if the block
+   * structure changes, for instance because of mesh refinement, the DoFInfo
+   * class will automatically use the new structures.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -77,25 +75,18 @@ namespace MeshWorker
     typename Triangulation<dim, spacedim>::face_iterator face;
 
     /**
-     * The number of the current
-     * face on the current cell.
+     * The number of the current face on the current cell.
      *
-     * This number is
-     * deal_II_numbers::invalid_unsigned_int
-     * if the info object was
-     * initialized with a cell.
+     * This number is deal_II_numbers::invalid_unsigned_int if the info object
+     * was initialized with a cell.
      */
     unsigned int face_number;
 
     /**
-     * The number of the current
-     * subface on the current
-     * face
+     * The number of the current subface on the current face
      *
-     * This number is
-     * deal_II_numbers::invalid_unsigned_int
-     * if the info object was not
-     * initialized with a subface.
+     * This number is deal_II_numbers::invalid_unsigned_int if the info object
+     * was not initialized with a subface.
      */
     unsigned int sub_number;
 
@@ -106,28 +97,24 @@ namespace MeshWorker
     std::vector<types::global_dof_index> indices;
 
     /**
-     * The DoF indices on the current cell, organized by local blocks.
-     * The size of this vector is zero, unless local blocks are used.
+     * The DoF indices on the current cell, organized by local blocks. The
+     * size of this vector is zero, unless local blocks are used.
      */
     std::vector<std::vector<types::global_dof_index> > indices_by_block;
 
     /**
-     * Constructor setting the
-     * #block_info pointer.
+     * Constructor setting the #block_info pointer.
      */
     DoFInfo(const BlockInfo &block_info);
 
     /**
-     * Constructor
-     * leaving the #block_info
-     * pointer empty, but setting
-     * the #aux_local_indices.
+     * Constructor leaving the #block_info pointer empty, but setting the
+     * #aux_local_indices.
      */
     DoFInfo (const DoFHandler<dim, spacedim> &dof_handler);
 
     /**
-     * Set the current cell and
-     * fill @p indices.
+     * Set the current cell and fill @p indices.
      */
     template <class DHCellIterator>
     void reinit(const DHCellIterator &c);
@@ -141,8 +128,7 @@ namespace MeshWorker
                 const unsigned int face_no);
 
     /**
-     * Set the current subface and fill @p indices if the #cell
-     * changed.
+     * Set the current subface and fill @p indices if the #cell changed.
      */
     template <class DHCellIterator, class DHFaceIterator>
     void reinit(const DHCellIterator &c,
@@ -151,16 +137,16 @@ namespace MeshWorker
                 const unsigned int subface_no);
 
     /**
-     * Switch to a new face of the same cell. Does not change @p
-     * indices and does not reset data in LocalResults.
+     * Switch to a new face of the same cell. Does not change @p indices and
+     * does not reset data in LocalResults.
      */
     template <class DHFaceIterator>
     void set_face (const DHFaceIterator &f,
                    const unsigned int face_no);
 
     /**
-     * Switch to a new subface of the same cell. Does not change @p
-     * indices and does not reset data in LocalResults.
+     * Switch to a new subface of the same cell. Does not change @p indices
+     * and does not reset data in LocalResults.
      */
     template <class DHFaceIterator>
     void set_subface (const DHFaceIterator &f,
@@ -174,16 +160,15 @@ namespace MeshWorker
     SmartPointer<const BlockInfo,DoFInfo<dim,spacedim> > block_info;
 
     /**
-     * The structure refers to a cell with level data instead of
-     * active data.
+     * The structure refers to a cell with level data instead of active data.
      */
     bool level_cell;
 
   private:
     /**
-     * Standard constructor, not setting any block indices. Use of
-     * this constructor is not recommended, but it is needed for the
-     * arrays in DoFInfoBox.
+     * Standard constructor, not setting any block indices. Use of this
+     * constructor is not recommended, but it is needed for the arrays in
+     * DoFInfoBox.
      */
     DoFInfo ();
 
@@ -198,12 +183,9 @@ namespace MeshWorker
     std::vector<types::global_dof_index> indices_org;
 
     /**
-     * An auxiliary local
-     * BlockIndices object created
-     * if #block_info is not set.
-     * It contains just a single
-     * block of the size of
-     * degrees of freedom per cell.
+     * An auxiliary local BlockIndices object created if #block_info is not
+     * set. It contains just a single block of the size of degrees of freedom
+     * per cell.
      */
     BlockIndices aux_local_indices;
 
@@ -212,30 +194,28 @@ namespace MeshWorker
 
 
   /**
-  * A class bundling the MeshWorker::DoFInfo objects used on a cell.
-  *
-  * @todo Currently, we are storing an object for the cells and two for
-  * each face. We could gather all face data pertaining to the cell
-  * itself in one object, saving a bit of memory and a few operations,
-  * but sacrificing some cleanliness.
-  *
-  * @ingroup MeshWorker
-  * @author Guido Kanschat, 2010
-  */
+   * A class bundling the MeshWorker::DoFInfo objects used on a cell.
+   *
+   * @todo Currently, we are storing an object for the cells and two for each
+   * face. We could gather all face data pertaining to the cell itself in one
+   * object, saving a bit of memory and a few operations, but sacrificing some
+   * cleanliness.
+   *
+   * @ingroup MeshWorker
+   * @author Guido Kanschat, 2010
+   */
   template <int dim, class DOFINFO>
   class DoFInfoBox
   {
   public:
     /**
-     * Constructor copying the seed
-     * into all other objects.
+     * Constructor copying the seed into all other objects.
      */
     DoFInfoBox(const DOFINFO &seed);
 
     /**
-     * Copy constructor, taking
-     * #cell and using it as a seed
-     * in the other constructor.
+     * Copy constructor, taking #cell and using it as a seed in the other
+     * constructor.
      */
     DoFInfoBox(const DoFInfoBox<dim, DOFINFO> &);
 
@@ -245,13 +225,9 @@ namespace MeshWorker
     void reset();
 
     /**
-     * After all info objects have
-     * been filled appropriately,
-     * use the ASSEMBLER object
-     * to assemble them into the
-     * global data. See
-     * MeshWorker::Assembler for
-     * available classes.
+     * After all info objects have been filled appropriately, use the
+     * ASSEMBLER object to assemble them into the global data. See
+     * MeshWorker::Assembler for available classes.
      */
     template <class ASSEMBLER>
     void assemble(ASSEMBLER &ass) const;
@@ -276,22 +252,19 @@ namespace MeshWorker
     DOFINFO exterior[GeometryInfo<dim>::faces_per_cell];
 
     /**
-     * A set of flags, indicating
-     * whether data on an interior
-     * face is available.
+     * A set of flags, indicating whether data on an interior face is
+     * available.
      */
     bool interior_face_available[GeometryInfo<dim>::faces_per_cell];
 
     /**
-     * A set of flags, indicating
-     * whether data on an exterior
-     * face is available.
+     * A set of flags, indicating whether data on an exterior face is
+     * available.
      */
     bool exterior_face_available[GeometryInfo<dim>::faces_per_cell];
 
     /**
-     * A flag to specify if the current object has been set to a valid
-     * cell.
+     * A flag to specify if the current object has been set to a valid cell.
      */
     bool cell_valid;
   };
index b68236f4314f63fb64dcf78eb72ea080c0c5330c..6bb519c10af577cedfd12476ee13d2e82a3d8a35 100644 (file)
@@ -33,8 +33,8 @@ namespace MeshWorker
   namespace Assembler
   {
     /**
-     * The class assembling local contributions to a functional into
-     * global functionals.
+     * The class assembling local contributions to a functional into global
+     * functionals.
      *
      *
      *
@@ -46,51 +46,40 @@ namespace MeshWorker
     {
     public:
       /**
-       * Initialize local data to
-       * store functionals. The
-       * number <tt>n</tt> is the
-       * number of functionals to
-       * be computed.
+       * Initialize local data to store functionals. The number <tt>n</tt> is
+       * the number of functionals to be computed.
        */
       void initialize(const unsigned int n);
       /**
-       * Initialize the local data
-       * in the DoFInfo object used
-       * later for assembling.
+       * Initialize the local data in the DoFInfo object used later for
+       * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face);
 
       /**
-       * Assemble the local values
-       * into the global vectors.
+       * Assemble the local values into the global vectors.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local values
-       * into the global vectors.
+       * Assemble both local values into the global vectors.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
                     const DOFINFO &info2);
 
       /**
-       * The value of the ith entry
-       * in #results.
+       * The value of the ith entry in #results.
        */
       number operator() (const unsigned int i) const;
     private:
       /**
-       * The values into which the
-       * results are added.
+       * The values into which the results are added.
        */
       std::vector<double> results;
     };
@@ -107,21 +96,21 @@ namespace MeshWorker
     {
     public:
       /**
-       * The initialization function, specifying the @p results
-       * vectors and whether face data should be collected separately.
+       * The initialization function, specifying the @p results vectors and
+       * whether face data should be collected separately.
        *
-       * @p results should contain two block vectors named "cells" and
-       * "faces" (the latter only if @p separate_faces is true). In
-       * each of the two, each block should have equal size and be
-       * large enough to accommodate all user indices set in the cells
-       * and faces covered by the loop it is used in. Typically, for
-       * estimators, this is Triangulation::n_active_cells() and
-       * Triangulation::n_faces(), respectively.
+       * @p results should contain two block vectors named "cells" and "faces"
+       * (the latter only if @p separate_faces is true). In each of the two,
+       * each block should have equal size and be large enough to accommodate
+       * all user indices set in the cells and faces covered by the loop it is
+       * used in. Typically, for estimators, this is
+       * Triangulation::n_active_cells() and Triangulation::n_faces(),
+       * respectively.
        *
-       * The use of BlockVector may seem cumbersome, but it allows us
-       * to assemble several functionals at the same time, one in each
-       * block. The typical situation for error estimate is just
-       * having a single block in each vector.
+       * The use of BlockVector may seem cumbersome, but it allows us to
+       * assemble several functionals at the same time, one in each block. The
+       * typical situation for error estimate is just having a single block in
+       * each vector.
        */
       void initialize(AnyData &results, bool separate_faces = true);
 
@@ -131,39 +120,30 @@ namespace MeshWorker
       void initialize(NamedData<BlockVector<number>*> &results,
                       bool separate_faces = true);
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
 
       /**
-       * Assemble the local values
-       * into the global vectors.
+       * Assemble the local values into the global vectors.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local values
-       * into the global vectors.
+       * Assemble both local values into the global vectors.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
                     const DOFINFO &info2);
 
       /**
-       * The value of the ith entry
-       * in @p results.
+       * The value of the ith entry in @p results.
        */
       number operator() (const unsigned int i) const;
     private:
index 2d5e2ea5f37decd0a443454ef0f7b31263b067e6..bb3a5bc68a4cfa02b1e21899451b9cc994398fab 100644 (file)
@@ -34,41 +34,37 @@ namespace MeshWorker
    * Class for objects handed to local integration functions.
    *
    * Objects of this class contain one or more objects of type FEValues,
-   * FEFaceValues or FESubfaceValues to be used in local
-   * integration. They are stored in an array of pointers to the base
-   * classes FEValuesBase. The template parameter VECTOR allows the
-   * use of different data types for the global system.
+   * FEFaceValues or FESubfaceValues to be used in local integration. They are
+   * stored in an array of pointers to the base classes FEValuesBase. The
+   * template parameter VECTOR allows the use of different data types for the
+   * global system.
    *
-   * Additionally, this function contains space to store the values of
-   * finite element functions stored in #global_data in the
-   * quadrature points. These vectors are initialized automatically on
-   * each cell or face. In order to avoid initializing unused vectors,
-   * you can use initialize_selector() to select the vectors by name
-   * that you actually want to use.
+   * Additionally, this function contains space to store the values of finite
+   * element functions stored in #global_data in the quadrature points. These
+   * vectors are initialized automatically on each cell or face. In order to
+   * avoid initializing unused vectors, you can use initialize_selector() to
+   * select the vectors by name that you actually want to use.
    *
    * <h3>Integration models</h3>
    *
-   * This class supports two local integration models, corresponding to
-   * the data models in the documentation of the Assembler namespace.
-   * One is the
-   * standard model suggested by the use of FESystem. Namely, there is
-   * one FEValuseBase object in this class, containing all shape
-   * functions of the whole system, and having as many components as the
-   * system. Using this model involves loops over all system shape
-   * functions. It requires to identify the system components
-   * for each shape function and to select the correct bilinear form,
-   * usually in an @p if or @p switch statement.
+   * This class supports two local integration models, corresponding to the
+   * data models in the documentation of the Assembler namespace. One is the
+   * standard model suggested by the use of FESystem. Namely, there is one
+   * FEValuseBase object in this class, containing all shape functions of the
+   * whole system, and having as many components as the system. Using this
+   * model involves loops over all system shape functions. It requires to
+   * identify the system components for each shape function and to select the
+   * correct bilinear form, usually in an @p if or @p switch statement.
    *
-   * The second integration model builds one FEValuesBase object per
-   * base element of the system. The degrees of freedom on each cell are
-   * renumbered by block, such that they represent the same block
-   * structure as the global system. Objects performing the integration
-   * can then process each block separately, which improves reusability
-   * of code considerably.
+   * The second integration model builds one FEValuesBase object per base
+   * element of the system. The degrees of freedom on each cell are renumbered
+   * by block, such that they represent the same block structure as the global
+   * system. Objects performing the integration can then process each block
+   * separately, which improves reusability of code considerably.
    *
    * @note As described in DoFInfo, the use of the local block model is
-   * triggered by calling BlockInfo::initialize_local() before
-   * using initialize() in this class.
+   * triggered by calling BlockInfo::initialize_local() before using
+   * initialize() in this class.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -89,30 +85,27 @@ namespace MeshWorker
     IntegrationInfo();
 
     /**
-     * Copy constructor, creating a clone to be used by
-     * WorksTream::run().
+     * Copy constructor, creating a clone to be used by WorksTream::run().
      */
     IntegrationInfo(const IntegrationInfo<dim, spacedim> &other);
 
     /**
-     * Build all internal structures, in particular the FEValuesBase
-     * objects and allocate space for data vectors.
+     * Build all internal structures, in particular the FEValuesBase objects
+     * and allocate space for data vectors.
      *
      * @param el is the finite element of the DoFHandler.
      *
-     * @param mapping is the Mapping object used to map the mesh
-     * cells.
+     * @param mapping is the Mapping object used to map the mesh cells.
      *
-     * @param quadrature is a Quadrature formula used in the
-     * constructor of the FEVALUES objects.
+     * @param quadrature is a Quadrature formula used in the constructor of
+     * the FEVALUES objects.
      *
      * @param flags are the UpdateFlags used in the constructor of the
      * FEVALUES objects.
      *
-     * @param local_block_info is an optional parameter for systems of
-     * PDE. If it is provided with reasonable data, then the degrees
-     * of freedom on the cells will be re-ordered to reflect the block
-     * structure of the system.
+     * @param local_block_info is an optional parameter for systems of PDE. If
+     * it is provided with reasonable data, then the degrees of freedom on the
+     * cells will be re-ordered to reflect the block structure of the system.
      */
     template <class FEVALUES>
     void initialize(const FiniteElement<dim,spacedim> &el,
@@ -132,8 +125,8 @@ namespace MeshWorker
     void clear();
 
     /**
-     * Return a reference to the FiniteElement that was used to
-     * initialize this object.
+     * Return a reference to the FiniteElement that was used to initialize
+     * this object.
      */
     const FiniteElement<dim, spacedim> &finite_element() const;
 
@@ -141,36 +134,36 @@ namespace MeshWorker
     bool multigrid;
     /// Access to finite element
     /**
-     * This is the access function being used, if initialize() for a
-     * single element was used (without the BlockInfo argument). It
-     * throws an exception, if applied to a vector of elements.
+     * This is the access function being used, if initialize() for a single
+     * element was used (without the BlockInfo argument). It throws an
+     * exception, if applied to a vector of elements.
      */
     const FEValuesBase<dim, spacedim> &fe_values () const;
 
     /// Access to finite elements
     /**
-     * This access function must be used if the initalize() for a
-     * group of elements was used (with a valid BlockInfo object).
+     * This access function must be used if the initalize() for a group of
+     * elements was used (with a valid BlockInfo object).
      */
     const FEValuesBase<dim, spacedim> &fe_values (const unsigned int i) const;
 
     /**
-     * The vector containing the values of finite element functions in
-     * the quadrature points.
+     * The vector containing the values of finite element functions in the
+     * quadrature points.
      *
-     * There is one vector per selected finite element function,
-     * containing one vector for each component, containing vectors
-     * with values for each quadrature point.
+     * There is one vector per selected finite element function, containing
+     * one vector for each component, containing vectors with values for each
+     * quadrature point.
      */
     std::vector<std::vector<std::vector<double> > > values;
 
     /**
-     * The vector containing the derivatives of finite element
-     * functions in the quadrature points.
+     * The vector containing the derivatives of finite element functions in
+     * the quadrature points.
      *
-     * There is one vector per selected finite element function,
-     * containing one vector for each component, containing vectors
-     * with values for each quadrature point.
+     * There is one vector per selected finite element function, containing
+     * one vector for each component, containing vectors with values for each
+     * quadrature point.
      */
     std::vector<std::vector<std::vector<Tensor<1,dim> > > > gradients;
 
@@ -178,9 +171,9 @@ namespace MeshWorker
      * The vector containing the second derivatives of finite element
      * functions in the quadrature points.
      *
-     * There is one vector per selected finite element function,
-     * containing one vector for each component, containing vectors
-     * with values for each quadrature point.
+     * There is one vector per selected finite element function, containing
+     * one vector for each component, containing vectors with values for each
+     * quadrature point.
      */
     std::vector<std::vector<std::vector<Tensor<2,dim> > > > hessians;
 
@@ -191,15 +184,15 @@ namespace MeshWorker
     void reinit(const DoFInfo<dim, spacedim, number> &i);
 
     /**
-     * Use the finite element functions in #global_data and fill the
-     * vectors #values, #gradients and #hessians.
+     * Use the finite element functions in #global_data and fill the vectors
+     * #values, #gradients and #hessians.
      */
     template<typename number>
     void fill_local_data(const DoFInfo<dim, spacedim, number> &info, bool split_fevalues);
 
     /**
-     * The global data vector used to compute function values in
-     * quadrature points.
+     * The global data vector used to compute function values in quadrature
+     * points.
      */
     std_cxx11::shared_ptr<VectorDataBase<dim, spacedim> > global_data;
 
@@ -215,9 +208,9 @@ namespace MeshWorker
     SmartPointer<const FiniteElement<dim, spacedim>, IntegrationInfo<dim, spacedim> > fe_pointer;
 
     /**
-     * Use the finite element functions in #global_data and fill the
-     * vectors #values, #gradients and #hessians with values according
-     * to the selector.
+     * Use the finite element functions in #global_data and fill the vectors
+     * #values, #gradients and #hessians with values according to the
+     * selector.
      */
     template <typename TYPE>
     void fill_local_data(
@@ -231,57 +224,55 @@ namespace MeshWorker
   };
 
   /**
-   * The object holding the scratch data for integrating over cells and
-   * faces. IntegrationInfoBox serves three main purposes:
+   * The object holding the scratch data for integrating over cells and faces.
+   * IntegrationInfoBox serves three main purposes:
    *
    * <ol>
-   * <li> It provides the interface needed by MeshWorker::loop(), namely
-   * the two functions post_cell() and post_faces(), as well as
-   * the data members #cell, #boundary, #face,
-   * #subface, and #neighbor.
+   * <li> It provides the interface needed by MeshWorker::loop(), namely the
+   * two functions post_cell() and post_faces(), as well as the data members
+   * #cell, #boundary, #face, #subface, and #neighbor.
    *
-   * <li> It contains all information needed to initialize the FEValues
-   * and FEFaceValues objects in the IntegrationInfo data members.
+   * <li> It contains all information needed to initialize the FEValues and
+   * FEFaceValues objects in the IntegrationInfo data members.
    *
-   * <li> It stores information on finite element vectors and whether
-   * their data should be used to compute values or derivatives of
-   * functions at quadrature points.
+   * <li> It stores information on finite element vectors and whether their
+   * data should be used to compute values or derivatives of functions at
+   * quadrature points.
    *
-   * <li> It makes educated guesses on quadrature rules and update
-   * flags, so that minimal code has to be written when default
-   * parameters are sufficient.
+   * <li> It makes educated guesses on quadrature rules and update flags, so
+   * that minimal code has to be written when default parameters are
+   * sufficient.
    * </ol>
    *
    * In order to allow for sufficient generality, a few steps have to be
    * undertaken to use this class.
    *
    * First, you should consider if you need values from any vectors in a
-   * AnyData object. If so, fill the VectorSelector objects
-   * #cell_selector, #boundary_selector and #face_selector with their names
-   * and the data type (value, gradient, Hessian) to be extracted.
+   * AnyData object. If so, fill the VectorSelector objects #cell_selector,
+   * #boundary_selector and #face_selector with their names and the data type
+   * (value, gradient, Hessian) to be extracted.
    *
-   * Afterwards, you will need to consider UpdateFlags for FEValues
-   * objects. A good start is initialize_update_flags(), which looks at
-   * the selectors filled before and adds all the flags needed to get
-   * the selection. Additional flags can be set with add_update_flags().
+   * Afterwards, you will need to consider UpdateFlags for FEValues objects. A
+   * good start is initialize_update_flags(), which looks at the selectors
+   * filled before and adds all the flags needed to get the selection.
+   * Additional flags can be set with add_update_flags().
    *
-   * Finally, we need to choose quadrature formulas. In the simplest
-   * case, you might be happy with the default settings, which are
-   * <i>n</i>-point Gauss formulas. If only derivatives of the shape
-   * functions are used (#update_values is not set) <i>n</i> equals the
-   * highest polynomial degree in the FiniteElement, if #update_values
-   * is set, <i>n</i> is one higher than this degree.  If you choose to
-   * use Gauss formulas of other size, use initialize_gauss_quadrature()
-   * with appropriate values. Otherwise, you can fill the variables
-   * #cell_quadrature, #boundary_quadrature and #face_quadrature
-   * directly.
+   * Finally, we need to choose quadrature formulas. In the simplest case, you
+   * might be happy with the default settings, which are <i>n</i>-point Gauss
+   * formulas. If only derivatives of the shape functions are used
+   * (#update_values is not set) <i>n</i> equals the highest polynomial degree
+   * in the FiniteElement, if #update_values is set, <i>n</i> is one higher
+   * than this degree.  If you choose to use Gauss formulas of other size, use
+   * initialize_gauss_quadrature() with appropriate values. Otherwise, you can
+   * fill the variables #cell_quadrature, #boundary_quadrature and
+   * #face_quadrature directly.
    *
-   * In order to save time, you can set the variables boundary_fluxes
-   * and interior_fluxes of the base class to false, thus telling the
+   * In order to save time, you can set the variables boundary_fluxes and
+   * interior_fluxes of the base class to false, thus telling the
    * Meshworker::loop() not to loop over those faces.
    *
-   * All the information in here is used to set up IntegrationInfo
-   * objects correctly, typically in an IntegrationInfoBox.
+   * All the information in here is used to set up IntegrationInfo objects
+   * correctly, typically in an IntegrationInfoBox.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -292,8 +283,7 @@ namespace MeshWorker
   public:
 
     /**
-     * The type of the info object
-     * for cells.
+     * The type of the info object for cells.
      */
     typedef IntegrationInfo<dim, spacedim> CellInfo;
 
@@ -305,9 +295,9 @@ namespace MeshWorker
     /**
      * Initialize the IntegrationInfo objects contained.
      *
-     * Before doing so, add update flags necessary to produce the data
-     * needed and also set uninitialized quadrature rules to Gauss
-     * formulas, which integrate polynomial bilinear forms exactly.
+     * Before doing so, add update flags necessary to produce the data needed
+     * and also set uninitialized quadrature rules to Gauss formulas, which
+     * integrate polynomial bilinear forms exactly.
      */
     void initialize(const FiniteElement<dim, spacedim> &el,
                     const Mapping<dim, spacedim> &mapping,
@@ -316,9 +306,9 @@ namespace MeshWorker
     /**
      * Initialize the IntegrationInfo objects contained.
      *
-     * Before doing so, add update flags necessary to produce the data
-     * needed and also set uninitialized quadrature rules to Gauss
-     * formulas, which integrate polynomial bilinear forms exactly.
+     * Before doing so, add update flags necessary to produce the data needed
+     * and also set uninitialized quadrature rules to Gauss formulas, which
+     * integrate polynomial bilinear forms exactly.
      */
     template <typename VECTOR>
     void initialize(const FiniteElement<dim, spacedim> &el,
@@ -349,15 +339,15 @@ namespace MeshWorker
     /* @{ */
 
     /**
-    * Call this function before initialize() in order to guess the
-    * update flags needed, based on the data selected.
-    *
-    * When computing face fluxes, we normally can use the geometry
-    * (integration weights and normal vectors) from the original cell
-    * and thus can avoid updating these values on the neighboring
-    * cell. Set <tt>neighbor_geometry</tt> to true in order to
-    * initialize these values as well.
-    */
+     * Call this function before initialize() in order to guess the update
+     * flags needed, based on the data selected.
+     *
+     * When computing face fluxes, we normally can use the geometry
+     * (integration weights and normal vectors) from the original cell and
+     * thus can avoid updating these values on the neighboring cell. Set
+     * <tt>neighbor_geometry</tt> to true in order to initialize these values
+     * as well.
+     */
     void initialize_update_flags(bool neighbor_geometry = false);
 
     /**
@@ -382,10 +372,10 @@ namespace MeshWorker
     void add_update_flags_face(const UpdateFlags flags);
 
     /**
-     * Add additional update flags to the ones already set in this
-     * program. The four boolean flags indicate whether the additional
-     * flags should be set for cell, boundary, interelement face for
-     * the cell itself or neighbor cell, or any combination thereof.
+     * Add additional update flags to the ones already set in this program.
+     * The four boolean flags indicate whether the additional flags should be
+     * set for cell, boundary, interelement face for the cell itself or
+     * neighbor cell, or any combination thereof.
      */
     void add_update_flags(const UpdateFlags flags,
                           const bool cell = true,
@@ -394,13 +384,13 @@ namespace MeshWorker
                           const bool neighbor = true);
 
     /**
-     * Assign n-point Gauss quadratures to each of the quadrature
-     * rules. Here, a size of zero points means that no loop over
-     * these grid entities should be performed.
+     * Assign n-point Gauss quadratures to each of the quadrature rules. Here,
+     * a size of zero points means that no loop over these grid entities
+     * should be performed.
      *
-     * If the parameter <tt>force</tt> is true, then all quadrature
-     * sets are filled with new quadrature rules. If it is false, then
-     * only empty rules are changed.
+     * If the parameter <tt>force</tt> is true, then all quadrature sets are
+     * filled with new quadrature rules. If it is false, then only empty rules
+     * are changed.
      */
     void initialize_gauss_quadrature(unsigned int n_cell_points,
                                      unsigned int n_boundary_points,
@@ -435,8 +425,8 @@ namespace MeshWorker
     /**
      * The set of update flags for interior face integration.
      *
-     * Defaults to #update_default, since quadrature weights are taken
-     * from the other cell.
+     * Defaults to #update_default, since quadrature weights are taken from
+     * the other cell.
      */
     UpdateFlags neighbor_flags;
 
@@ -463,29 +453,28 @@ namespace MeshWorker
 
     /**
      * Initialize the VectorSelector objects #cell_selector,
-     * #boundary_selector and #face_selector in order to save
-     * computational effort. If no selectors are used, then values for
-     * all named vectors in DoFInfo::global_data will be computed in
-     * all quadrature points.
+     * #boundary_selector and #face_selector in order to save computational
+     * effort. If no selectors are used, then values for all named vectors in
+     * DoFInfo::global_data will be computed in all quadrature points.
      *
-     * This function will also add UpdateFlags to the flags stored in
-     * this class.
+     * This function will also add UpdateFlags to the flags stored in this
+     * class.
      */
     /**
-     * Select the vectors from DoFInfo::global_data that should be
-     * computed in the quadrature points on cells.
+     * Select the vectors from DoFInfo::global_data that should be computed in
+     * the quadrature points on cells.
      */
     MeshWorker::VectorSelector cell_selector;
 
     /**
-     * Select the vectors from DoFInfo::global_data that should be
-     * computed in the quadrature points on boundary faces.
+     * Select the vectors from DoFInfo::global_data that should be computed in
+     * the quadrature points on boundary faces.
      */
     MeshWorker::VectorSelector boundary_selector;
 
     /**
-     * Select the vectors from DoFInfo::global_data that should be
-     * computed in the quadrature points on interior faces.
+     * Select the vectors from DoFInfo::global_data that should be computed in
+     * the quadrature points on interior faces.
      */
     MeshWorker::VectorSelector face_selector;
 
@@ -499,42 +488,40 @@ namespace MeshWorker
      */
     /* @{ */
     /**
-     * A callback function which is called in the loop over all cells,
-     * after the action on a cell has been performed and before the
-     * faces are dealt with.
+     * A callback function which is called in the loop over all cells, after
+     * the action on a cell has been performed and before the faces are dealt
+     * with.
      *
-     * In order for this function to have this effect, at least either
-     * of the arguments <tt>boundary_worker</tt> or
-     * <tt>face_worker</tt> arguments of loop() should be
-     * nonzero. Additionally, <tt>cells_first</tt> should be true. If
-     * <tt>cells_first</tt> is false, this function is called before
+     * In order for this function to have this effect, at least either of the
+     * arguments <tt>boundary_worker</tt> or <tt>face_worker</tt> arguments of
+     * loop() should be nonzero. Additionally, <tt>cells_first</tt> should be
+     * true. If <tt>cells_first</tt> is false, this function is called before
      * any action on a cell is taken.
      *
-     * And empty function in this class, but can be replaced in other
-     * classes given to loop() instead.
+     * And empty function in this class, but can be replaced in other classes
+     * given to loop() instead.
      *
-     * See loop() and cell_action() for more details of how this
-     * function can be used.
+     * See loop() and cell_action() for more details of how this function can
+     * be used.
      */
     template <class DOFINFO>
     void post_cell(const DoFInfoBox<dim, DOFINFO> &);
 
     /**
-     * A callback function which is called in the loop over all cells,
-     * after the action on the faces of a cell has been performed and
-     * before the cell itself is dealt with (assumes
-     * <tt>cells_first</tt> is false).
+     * A callback function which is called in the loop over all cells, after
+     * the action on the faces of a cell has been performed and before the
+     * cell itself is dealt with (assumes <tt>cells_first</tt> is false).
      *
-     * In order for this function to have a reasonable effect, at
-     * least either of the arguments <tt>boundary_worker</tt> or
-     * <tt>face_worker</tt> arguments of loop() should be
-     * nonzero. Additionally, <tt>cells_first</tt> should be false.
+     * In order for this function to have a reasonable effect, at least either
+     * of the arguments <tt>boundary_worker</tt> or <tt>face_worker</tt>
+     * arguments of loop() should be nonzero. Additionally,
+     * <tt>cells_first</tt> should be false.
      *
-     * And empty function in this class, but can be replaced in other
-     * classes given to loop() instead.
+     * And empty function in this class, but can be replaced in other classes
+     * given to loop() instead.
      *
-     * See loop() and cell_action() for more details of how this
-     * function can be used.
+     * See loop() and cell_action() for more details of how this function can
+     * be used.
      */
     template <class DOFINFO>
     void post_faces(const DoFInfoBox<dim, DOFINFO> &);
@@ -548,13 +535,12 @@ namespace MeshWorker
      */
     CellInfo boundary;
     /**
-     * The info object for a regular interior face, seen from the
-     * first cell.
+     * The info object for a regular interior face, seen from the first cell.
      */
     CellInfo face;
     /**
-     * The info object for the refined side of an interior face seen
-     * from the first cell.
+     * The info object for the refined side of an interior face seen from the
+     * first cell.
      */
     CellInfo subface;
     /**
index 2ec2e11c055695e0689a7ee956130518fc8b2778..a1fd6fccac3c345b529bea6d97533f34a52463d3 100644 (file)
@@ -32,19 +32,17 @@ namespace MeshWorker
   template <int dim, int spacedim> class IntegrationInfo;
 
   /**
-   * A local integrator object, which can be used to simplify the call
-   * of loop(). Instead of providing the three local integration
-   * functions separately, we bundle them as virtual functions in this
-   * class.
+   * A local integrator object, which can be used to simplify the call of
+   * loop(). Instead of providing the three local integration functions
+   * separately, we bundle them as virtual functions in this class.
    *
-   * Additionally, since we cannot have a virtual null function, we
-   * provide flags, which allow us to indicate, whether we want to
-   * integrate on boundary and interior faces. Thes flags are true by
-   * default, but can be modified by applications to speed up the loop.
+   * Additionally, since we cannot have a virtual null function, we provide
+   * flags, which allow us to indicate, whether we want to integrate on
+   * boundary and interior faces. Thes flags are true by default, but can be
+   * modified by applications to speed up the loop.
    *
-   * If a function is not overloaded in a derived class, but its usage
-   * flag is true, the function will cause an exception
-   * ExcPureFunction.
+   * If a function is not overloaded in a derived class, but its usage flag is
+   * true, the function will cause an exception ExcPureFunction.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat
@@ -55,84 +53,85 @@ namespace MeshWorker
   {
   public:
     /**
-    * The constructor setting default values, namely all integration flags to true.
-    */
+     * The constructor setting default values, namely all integration flags to
+     * true.
+     */
     LocalIntegrator();
 
     /**
-    * The constructor setting integration flags to specified values.
-    */
+     * The constructor setting integration flags to specified values.
+     */
     LocalIntegrator(bool use_cell, bool use_boundary, bool use_face);
 
     /**
-    * The empty virtual destructor.
-    */
+     * The empty virtual destructor.
+     */
     ~LocalIntegrator();
 
     /**
-    * Virtual function for integrating on cells. Throws exception
-    * PureFunctionCalled if not overloaded by a derived class.
-    */
+     * Virtual function for integrating on cells. Throws exception
+     * PureFunctionCalled if not overloaded by a derived class.
+     */
     virtual void cell(DoFInfo<dim, spacedim, number> &dinfo,
                       IntegrationInfo<dim, spacedim> &info) const;
     /**
-    * Virtual function for integrating on boundary faces. Throws exception
-    * PureFunctionCalled if not overloaded by a derived class.
-    */
+     * Virtual function for integrating on boundary faces. Throws exception
+     * PureFunctionCalled if not overloaded by a derived class.
+     */
     virtual void boundary(DoFInfo<dim, spacedim, number> &dinfo,
                           IntegrationInfo<dim, spacedim> &info) const;
     /**
-    * Virtual function for integrating on interior faces. Throws exception
-    * PureFunctionCalled if not overloaded by a derived class.
-    */
+     * Virtual function for integrating on interior faces. Throws exception
+     * PureFunctionCalled if not overloaded by a derived class.
+     */
     virtual void face(DoFInfo<dim, spacedim, number> &dinfo1,
                       DoFInfo<dim, spacedim, number> &dinfo2,
                       IntegrationInfo<dim, spacedim> &info1,
                       IntegrationInfo<dim, spacedim> &info2) const;
 
     /**
-    * The flag indicating whether the cell integrator cell() is to be
-    * used in the loop. Defaults to <tt>true</tt>.
-    */
+     * The flag indicating whether the cell integrator cell() is to be used in
+     * the loop. Defaults to <tt>true</tt>.
+     */
     bool use_cell;
 
     /**
-    * The flag indicating whether the boundary integrator boundary()
-    * is to be used in the loop. Defaults to <tt>true</tt>.
-    */
+     * The flag indicating whether the boundary integrator boundary() is to be
+     * used in the loop. Defaults to <tt>true</tt>.
+     */
     bool use_boundary;
 
     /**
-    * The flag indicating whether the interior face integrator face()
-    * is to be used in the loop. Defaults to <tt>true</tt>.
-    */
+     * The flag indicating whether the interior face integrator face() is to
+     * be used in the loop. Defaults to <tt>true</tt>.
+     */
     bool use_face;
 
     /**
-     * The names of the input vectors. If this vector is nonempty, it
-     * can be used by application programs to automatically select
-     * and verify the input vectors used for integration.
+     * The names of the input vectors. If this vector is nonempty, it can be
+     * used by application programs to automatically select and verify the
+     * input vectors used for integration.
      *
-     * @note This variable is currently not used by the library, but
-     * it is provided to help develop application programs.
+     * @note This variable is currently not used by the library, but it is
+     * provided to help develop application programs.
      */
     std::vector<std::string> input_vector_names;
 
     /**
-     * The names of the results produced. If this vector is nonempty,
-     * it can be used by application programs to automatically assign
-     * names to output values and/or verify the names of vectors.
+     * The names of the results produced. If this vector is nonempty, it can
+     * be used by application programs to automatically assign names to output
+     * values and/or verify the names of vectors.
      *
-     * @note This variable is currently not used by the library, but
-     * it is provided to help develop application programs.
+     * @note This variable is currently not used by the library, but it is
+     * provided to help develop application programs.
      */
     std::vector<std::string> output_names;
 
     /**
      * This error is thrown if one of the virtual functions cell(),
-     * boundary(), or face() is called without being overloaded in a
-     * derived class. Consider setting #use_cell, #use_boundary, and
-     * #use_face to false, respectively.
+     * boundary(), or face() is called without being overloaded in a derived
+     * class. Consider setting #use_cell, #use_boundary, and #use_face to
+     * false, respectively.
      *
      * @ingroup Exceptions
      */
index 0cb5e0e54e37d718af211d0e913ea05a2284ab70..94538f915c8424ea59de5b40507928f8f2be65e6 100644 (file)
@@ -31,34 +31,32 @@ template<int,int> class DoFHandler;
 template<int,int> class MGDoFHandler;
 
 /**
- * A collection of functions and classes for the mesh loops that are
- * an ubiquitous part of each finite element program.
+ * A collection of functions and classes for the mesh loops that are an
+ * ubiquitous part of each finite element program.
  *
  * The workhorse of this namespace is the loop() function, which implements a
- * completely generic loop over all mesh cells. Since the calls to
- * loop() are error-prone due to its generality, for many applications
- * it is advisable to derive a class from MeshWorker::LocalIntegrator
- * and use the less general integration_loop() instead.
+ * completely generic loop over all mesh cells. Since the calls to loop() are
+ * error-prone due to its generality, for many applications it is advisable to
+ * derive a class from MeshWorker::LocalIntegrator and use the less general
+ * integration_loop() instead.
  *
- * The loop() depends on certain objects handed to it as
- * arguments. These objects are of two types, info objects like
- * DoFInfo and IntegrationInfo and worker objects like LocalWorker and
- * IntegrationWorker.
+ * The loop() depends on certain objects handed to it as arguments. These
+ * objects are of two types, info objects like DoFInfo and IntegrationInfo and
+ * worker objects like LocalWorker and IntegrationWorker.
  *
- * Worker objects usually do two different jobs: first, they compute
- * the local contribution of a cell or face to the global
- * operation. Second, they assemble this local contribution into the
- * global result, whether a functional, a form or a bilinear
- * form. While the first job is particular to the problem being
- * solved, the second is generic and only depends on the data
- * structures. Therefore, base classes for workers assembling into
- * global data are provided in the namespace Assembler.
+ * Worker objects usually do two different jobs: first, they compute the local
+ * contribution of a cell or face to the global operation. Second, they
+ * assemble this local contribution into the global result, whether a
+ * functional, a form or a bilinear form. While the first job is particular to
+ * the problem being solved, the second is generic and only depends on the
+ * data structures. Therefore, base classes for workers assembling into global
+ * data are provided in the namespace Assembler.
  *
  * <h3>Template argument types</h3>
  *
- * The functions loop() and cell_action() take some arguments which
- * are template parameters. Let us list the minimum requirements for
- * these classes here and describe their properties.
+ * The functions loop() and cell_action() take some arguments which are
+ * template parameters. Let us list the minimum requirements for these classes
+ * here and describe their properties.
  *
  * <h4>ITERATOR</h4>
  *
@@ -67,9 +65,9 @@ template<int,int> class MGDoFHandler;
  *
  * <h4>DOFINFO</h4>
  *
- * For an example implementation, refer to the class template DoFInfo.
- * In order to work with cell_action() and loop(), DOFINFO needs to
- * follow the following interface.
+ * For an example implementation, refer to the class template DoFInfo. In
+ * order to work with cell_action() and loop(), DOFINFO needs to follow the
+ * following interface.
  * @code
  * class DOFINFO
  * {
@@ -93,25 +91,24 @@ template<int,int> class MGDoFHandler;
  * };
  * @endcode
  *
- * The three private functions are called by DoFInfoBox and should not
- * be needed elsewhere. Obviously, they can be made public and then
- * the friend declaration at the end may be missing.
+ * The three private functions are called by DoFInfoBox and should not be
+ * needed elsewhere. Obviously, they can be made public and then the friend
+ * declaration at the end may be missing.
  *
  * Additionally, you will need at least one public constructor. Furthermore
- * DOFINFO is pretty useless yet: functions to interface with
- * INTEGRATIONINFO and ASSEMBLER are needed.
+ * DOFINFO is pretty useless yet: functions to interface with INTEGRATIONINFO
+ * and ASSEMBLER are needed.
  *
- * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we
- * store the results of local operations on each cell and its
- * faces. Once all this information has been gathered, an ASSEMBLER is
- * used to assemble it into golbal data.
+ * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we store
+ * the results of local operations on each cell and its faces. Once all this
+ * information has been gathered, an ASSEMBLER is used to assemble it into
+ * golbal data.
  *
  * <h4>INFOBOX</h4>
  *
- * This type is exemplified in IntegrationInfoBox. It collects the
- * input data for actions on cells and faces in INFO objects (see
- * below). It provides the following interface to loop() and
- * cell_action():
+ * This type is exemplified in IntegrationInfoBox. It collects the input data
+ * for actions on cells and faces in INFO objects (see below). It provides the
+ * following interface to loop() and cell_action():
  *
  * @code
  * class INFOBOX
@@ -131,20 +128,20 @@ template<int,int> class MGDoFHandler;
  * };
  * @endcode
  *
- * The main purpose of this class is gathering the five INFO objects,
- * which contain the temporary data used on each cell or face. The
- * requirements on these objects are listed below. Here, we only note
- * that there need to be these 5 objects with the names listed above.
+ * The main purpose of this class is gathering the five INFO objects, which
+ * contain the temporary data used on each cell or face. The requirements on
+ * these objects are listed below. Here, we only note that there need to be
+ * these 5 objects with the names listed above.
  *
- * The two function templates are call back functions called in
- * cell_action(). The first is called before the faces are worked on,
- * the second after the faces.
+ * The two function templates are call back functions called in cell_action().
+ * The first is called before the faces are worked on, the second after the
+ * faces.
  *
  * <h4>INFO</h4>
  *
- * See IntegrationInfo for an example of these objects. They contain
- * the temporary data needed on each cell or face to compute the
- * result. The MeshWorker only uses the interface
+ * See IntegrationInfo for an example of these objects. They contain the
+ * temporary data needed on each cell or face to compute the result. The
+ * MeshWorker only uses the interface
  *
  * @code
  * class INFO
@@ -156,22 +153,20 @@ template<int,int> class MGDoFHandler;
  *
  * <h3>Simplified interfaces</h3>
  *
- * Since the loop() is fairly general, a specialization
- * integration_loop() is available, which is a wrapper around loop()
- * with a simplified interface.
+ * Since the loop() is fairly general, a specialization integration_loop() is
+ * available, which is a wrapper around loop() with a simplified interface.
  *
- * The integration_loop() function loop takes most of the information
- * that it needs to pass to loop() from an IntegrationInfoBox
- * object. Its use is explained in step-12, but in
- * short it requires functions that do the local integration on a
- * cell, interior or boundary face, and it needs an object (called
- * "assembler") that copies these local contributions into the global
+ * The integration_loop() function loop takes most of the information that it
+ * needs to pass to loop() from an IntegrationInfoBox object. Its use is
+ * explained in step-12, but in short it requires functions that do the local
+ * integration on a cell, interior or boundary face, and it needs an object
+ * (called "assembler") that copies these local contributions into the global
  * matrix and right hand side objects.
  *
- * Before we can run the integration loop, we have to initialize
- * several data structures in our IntegrationWorker and assembler
- * objects. For instance, we have to decide on the quadrature rule or
- * we may need more than the default update flags.
+ * Before we can run the integration loop, we have to initialize several data
+ * structures in our IntegrationWorker and assembler objects. For instance, we
+ * have to decide on the quadrature rule or we may need more than the default
+ * update flags.
  *
  * @ingroup MeshWorker
  * @ingroup Integrators
@@ -182,32 +177,30 @@ namespace MeshWorker
 {
   /**
    * The class providing the scrapbook to fill with results of local
-   * integration. Depending on the task the mesh worker loop is
-   * performing, local results can be of different types. They have
-   * in common that they are the result of local integration over a cell
-   * or face. Their actual type is determined by the Assember using
-   * them. It is also the assembler setting the arrays of local results
-   * to the sizes needed. Here is a list of the provided data types and
-   * the assembers using them:
+   * integration. Depending on the task the mesh worker loop is performing,
+   * local results can be of different types. They have in common that they
+   * are the result of local integration over a cell or face. Their actual
+   * type is determined by the Assember using them. It is also the assembler
+   * setting the arrays of local results to the sizes needed. Here is a list
+   * of the provided data types and the assembers using them:
    *
    * <ol>
-   * <li> n_values() numbers accessed with value(), and stored in the
-   * data member #J.
+   * <li> n_values() numbers accessed with value(), and stored in the data
+   * member #J.
    *
-   * <li> n_vectors() vectors of the length of dofs on this cell,
-   * accessed by vector(), and stored in #R.
-   * <li> n_matrices() matrices of dimension dofs per cell in each
-   * direction, accessed by matrix() with second argument
-   * <tt>false</tt>. These are stored in #M1, and they are the matrices
-   * coupling degrees of freedom in the same cell. For fluxes across
-   * faces, there is an additional set #M2 of matrices of the same size, but
-   * the dimension of the matrices being according to the degrees of
-   * freedom on both cells. These are accessed with matrix(), using the
-   * second argument <tt>true</tt>.
+   * <li> n_vectors() vectors of the length of dofs on this cell, accessed by
+   * vector(), and stored in #R.
+   * <li> n_matrices() matrices of dimension dofs per cell in each direction,
+   * accessed by matrix() with second argument <tt>false</tt>. These are
+   * stored in #M1, and they are the matrices coupling degrees of freedom in
+   * the same cell. For fluxes across faces, there is an additional set #M2 of
+   * matrices of the same size, but the dimension of the matrices being
+   * according to the degrees of freedom on both cells. These are accessed
+   * with matrix(), using the second argument <tt>true</tt>.
    * </ol>
    *
-   * The local matrices initialized by reinit() of the info object and
-   * then assembled into the global system by Assembler classes.
+   * The local matrices initialized by reinit() of the info object and then
+   * assembled into the global system by Assembler classes.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -219,8 +212,7 @@ namespace MeshWorker
     /**
      * The number of scalar values.
      *
-     * This number is set to a
-     * nonzero value by Assember::CellsAndFaces
+     * This number is set to a nonzero value by Assember::CellsAndFaces
      *
      */
     unsigned int n_values () const;
@@ -228,9 +220,7 @@ namespace MeshWorker
     /**
      * The number of vectors.
      *
-     * This number is set to a
-     * nonzero value by
-     * Assember::ResidualSimple and
+     * This number is set to a nonzero value by Assember::ResidualSimple and
      * Assember::ResidualLocalBlocksToGlobalBlocks.
      */
     unsigned int n_vectors () const;
@@ -241,27 +231,22 @@ namespace MeshWorker
     unsigned int n_matrices () const;
 
     /**
-     * The number of quadrature
-     * points in quadrature_values().
+     * The number of quadrature points in quadrature_values().
      */
     unsigned int n_quadrature_points() const;
 
     /**
-     * The number of values in each
-     * quadrature point in
-     * quadrature_values().
+     * The number of values in each quadrature point in quadrature_values().
      */
     unsigned int n_quadrature_values() const;
 
     /**
-     * Access scalar value at index
-     * @p i.
+     * Access scalar value at index @p i.
      */
     number &value(unsigned int i);
 
     /**
-     * Read scalar value at index
-     * @p i.
+     * Read scalar value at index @p i.
      */
     number value(unsigned int i) const;
 
@@ -276,35 +261,23 @@ namespace MeshWorker
     const BlockVector<number> &vector(unsigned int i) const;
 
     /**
-     * Access matrix at index @p
-     * i. For results on internal
-     * faces, a true value for @p
-     * external refers to the flux
-     * between cells, while false
-     * refers to entries coupling
-     * inside the cell.
+     * Access matrix at index @p i. For results on internal faces, a true
+     * value for @p external refers to the flux between cells, while false
+     * refers to entries coupling inside the cell.
      */
     MatrixBlock<FullMatrix<number> > &matrix(unsigned int i, bool external = false);
 
     /**
-     * Read matrix at index @p
-     * i. For results on internal
-     * faces, a true value for @p
-     * external refers to the flux
-     * between cells, while false
-     * refers to entries coupling
-     * inside the cell.
+     * Read matrix at index @p i. For results on internal faces, a true value
+     * for @p external refers to the flux between cells, while false refers to
+     * entries coupling inside the cell.
      */
     const MatrixBlock<FullMatrix<number> > &matrix(unsigned int i, bool external = false) const;
 
     /**
-     * Access to the vector
-     * #quadrature_data of data
-     * in quadrature points,
-     * organized such that there is
-     * a vector for each point,
-     * containing one entry for
-     * each component.
+     * Access to the vector #quadrature_data of data in quadrature points,
+     * organized such that there is a vector for each point, containing one
+     * entry for each component.
      */
     Table<2, number> &quadrature_values();
 
@@ -333,18 +306,18 @@ namespace MeshWorker
     void initialize_vectors(const unsigned int n);
 
     /**
-     * Allocate @p n local matrices. Additionally, set their block row
-     * and column coordinates to zero. The matrices themselves are
-     * resized by reinit().
+     * Allocate @p n local matrices. Additionally, set their block row and
+     * column coordinates to zero. The matrices themselves are resized by
+     * reinit().
      *
      * @note This function is usually only called by the assembler.
      */
     void initialize_matrices(unsigned int n, bool both);
 
     /**
-     * Allocate a local matrix for each of the global ones in @p
-     * matrices. Additionally, set their block row and column
-     * coordinates. The matrices themselves are resized by reinit().
+     * Allocate a local matrix for each of the global ones in @p matrices.
+     * Additionally, set their block row and column coordinates. The matrices
+     * themselves are resized by reinit().
      *
      * @note This function is usually only called by the assembler.
      */
@@ -353,34 +326,26 @@ namespace MeshWorker
                              bool both);
 
     /**
-     * Allocate a local matrix
-     * for each of the global
-     * level objects in @p
-     * matrices. Additionally,
-     * set their block row and
-     * column coordinates. The
-     * matrices themselves are
-     * resized by reinit().
+     * Allocate a local matrix for each of the global level objects in @p
+     * matrices. Additionally, set their block row and column coordinates. The
+     * matrices themselves are resized by reinit().
      *
-     * @note This function is
-     * usually only called by the
-     * assembler.
+     * @note This function is usually only called by the assembler.
      */
     template <class MATRIX>
     void initialize_matrices(const MGMatrixBlockVector<MATRIX> &matrices,
                              bool both);
 
     /**
-     * Initialize quadrature values to <tt>nv</tt> values in
-     * <tt>np</tt> quadrature points.
+     * Initialize quadrature values to <tt>nv</tt> values in <tt>np</tt>
+     * quadrature points.
      */
     void initialize_quadrature(unsigned int np, unsigned int nv);
 
     /**
-     * Reinitialize matrices for new cell. Does not resize any of the
-     * data vectors stored in this object, but resizes the vectors in
-     * #R and the matrices in #M1 and #M2 for hp and sets them to
-     * zero.
+     * Reinitialize matrices for new cell. Does not resize any of the data
+     * vectors stored in this object, but resizes the vectors in #R and the
+     * matrices in #M1 and #M2 for hp and sets them to zero.
      */
     void reinit(const BlockIndices &local_sizes);
 
@@ -407,20 +372,20 @@ namespace MeshWorker
     std::vector<number> J;
 
     /**
-     * The local vectors. This field is public, so that local
-     * integrators can write to it.
+     * The local vectors. This field is public, so that local integrators can
+     * write to it.
      */
     std::vector<BlockVector<number> > R;
 
     /**
-     * The local matrices coupling degrees of freedom in the cell
-     * itself or within the first cell on a face.
+     * The local matrices coupling degrees of freedom in the cell itself or
+     * within the first cell on a face.
      */
     std::vector<MatrixBlock<FullMatrix<number> > > M1;
 
     /**
-     * The local matrices coupling test functions on the cell with
-     * trial functions on the other cell.
+     * The local matrices coupling test functions on the cell with trial
+     * functions on the other cell.
      *
      * Only used on interior faces.
      */
index 66d35d95dd8228a75b92f4baef655d2328374480..878c2baaf3641ac33978e543d7153e7d1c71f888 100644 (file)
@@ -90,7 +90,8 @@ namespace MeshWorker
      */
     bool own_cells;
     /**
-     * Loop over cells not owned by this process. Defaults to <code>false</code>.
+     * Loop over cells not owned by this process. Defaults to
+     * <code>false</code>.
      */
     bool ghost_cells;
 
@@ -102,23 +103,20 @@ namespace MeshWorker
     };
 
     /**
-     * Loop over faces between a locally owned cell and a ghost cell:
-     * - never: do not assembly these faces
-     * - one: only one of the processes will assemble these faces (
-     * from the finer side or the process with the lower mpi rank)
-     * - both: both processes will assemble these faces
-     * Note that these faces are never assembled from both sides on a single
-     * process.
-     * Default is one.
+     * Loop over faces between a locally owned cell and a ghost cell: - never:
+     * do not assembly these faces - one: only one of the processes will
+     * assemble these faces ( from the finer side or the process with the
+     * lower mpi rank) - both: both processes will assemble these faces Note
+     * that these faces are never assembled from both sides on a single
+     * process. Default is one.
      */
     FaceOption faces_to_ghost;
 
     /**
-     * Loop over faces between two locally owned cells:
-     * - never: do not assemble face terms
-     * - one: assemble once (always coming from the finer side)
-     * - both: assemble each face twice (not implemented for hanging nodes!)
-     * Default is one.
+     * Loop over faces between two locally owned cells: - never: do not
+     * assemble face terms - one: assemble once (always coming from the finer
+     * side) - both: assemble each face twice (not implemented for hanging
+     * nodes!) Default is one.
      */
     FaceOption own_faces;
 
@@ -133,29 +131,27 @@ namespace MeshWorker
 
 
   /**
-   * The function called by loop() to perform the required actions on a
-   * cell and its faces. The three functions <tt>cell_worker</tt>,
+   * The function called by loop() to perform the required actions on a cell
+   * and its faces. The three functions <tt>cell_worker</tt>,
    * <tt>boundary_worker</tt> and <tt>face_worker</tt> are the same ones
-   * handed to loop(). While there we only run the loop over all cells,
-   * here, we do a single cell and, if necessary, its faces, interior
-   * and boundary.
+   * handed to loop(). While there we only run the loop over all cells, here,
+   * we do a single cell and, if necessary, its faces, interior and boundary.
    *
-   * Upon return, the DoFInfo objects in the DoFInfoBox are filled with
-   * the data computed on the cell and each of the faces. Thus, after
-   * the execution of this function, we are ready to call
-   * DoFInfoBox::assemble() to distribute the local data into global
-   * data.
+   * Upon return, the DoFInfo objects in the DoFInfoBox are filled with the
+   * data computed on the cell and each of the faces. Thus, after the
+   * execution of this function, we are ready to call DoFInfoBox::assemble()
+   * to distribute the local data into global data.
    *
    * @param cell is the cell we work on
-   * @param dof_info is the object into which local results are
-   * entered. It is expected to have been set up for the right types of
-   * data.
-   * @param info is the object containing additional data only needed
-   * for internal processing.
+   * @param dof_info is the object into which local results are entered. It is
+   * expected to have been set up for the right types of data.
+   * @param info is the object containing additional data only needed for
+   * internal processing.
    * @param cell_worker defines the local action on each cell.
    * @param boundary_worker defines the local action on boundary faces
    * @param face_worker defines the local action on interior faces.
-   * @param loop_control control structure to specify what actions should be performed.
+   * @param loop_control control structure to specify what actions should be
+   * performed.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat
@@ -356,16 +352,15 @@ namespace MeshWorker
 
 
   /**
-   * The main work function of this namespace. It is a loop over all
-   * cells in an iterator range, in which cell_action() is called for
-   * each cell. Unilaterally refined interior faces are handled
-   * automatically by the loop.
-   * Most of the work in this loop is done in cell_action(), which also
-   * receives most of the parameters of this function. See the
-   * documentation there for more details.
+   * The main work function of this namespace. It is a loop over all cells in
+   * an iterator range, in which cell_action() is called for each cell.
+   * Unilaterally refined interior faces are handled automatically by the
+   * loop. Most of the work in this loop is done in cell_action(), which also
+   * receives most of the parameters of this function. See the documentation
+   * there for more details.
    *
-   * If you don't want anything to be done on cells, interior or boundary faces
-   * to happen, simply pass the Null pointer to one of the function
+   * If you don't want anything to be done on cells, interior or boundary
+   * faces to happen, simply pass the Null pointer to one of the function
    * arguments.
    *
    * @ingroup MeshWorker
@@ -451,8 +446,8 @@ namespace MeshWorker
   }
 
   /**
-   * @deprecated The simplification in this loop is
-   * insignificant. Therefore, it is recommended to use loop() instead.
+   * @deprecated The simplification in this loop is insignificant. Therefore,
+   * it is recommended to use loop() instead.
    *
    * Simplified interface for loop() if specialized for integration.
    *
@@ -502,8 +497,8 @@ namespace MeshWorker
 
 
   /**
-   * Simplified interface for loop() if specialized for integration,
-   * using the virtual functions in LocalIntegrator.
+   * Simplified interface for loop() if specialized for integration, using the
+   * virtual functions in LocalIntegrator.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
index c5657b9558b0907347288cb30aee445a1e388799..65b04a54fc67f4b8861eb80ec32b69e38bc0cb94 100644 (file)
@@ -33,22 +33,22 @@ namespace MeshWorker
   {
 
     /**
-     * A class that, instead of assembling into a matrix or vector,
-     * outputs the results on a cell to a gnuplot patch.
+     * A class that, instead of assembling into a matrix or vector, outputs
+     * the results on a cell to a gnuplot patch.
      *
-     * This assembler expects that LocalResults contains quadrature values
-     * set with LocalResults::quadrature_value(). When it is initialized
-     * with the number of quadrature points in a single (!) space
-     * direction and the number of data fields to be displayed, it
-     * initializes LocalResults automatically. The number of data fields
-     * in local results will be increased by dim in order to accommodate
-     * for the coordinates of the data points.
+     * This assembler expects that LocalResults contains quadrature values set
+     * with LocalResults::quadrature_value(). When it is initialized with the
+     * number of quadrature points in a single (!) space direction and the
+     * number of data fields to be displayed, it initializes LocalResults
+     * automatically. The number of data fields in local results will be
+     * increased by dim in order to accommodate for the coordinates of the
+     * data points.
      *
-     * While data slots for the space coordinates are allocated
-     * automatically, these coordinates are not entered. It is up to the
-     * user to enter the coordinates in the first dim data entries at
-     * every point. This adds the flexibility to output transformed
-     * coordinates or even something completely different.
+     * While data slots for the space coordinates are allocated automatically,
+     * these coordinates are not entered. It is up to the user to enter the
+     * coordinates in the first dim data entries at every point. This adds the
+     * flexibility to output transformed coordinates or even something
+     * completely different.
      *
      * @note In the current implementation, only cell data can be written.
      *
@@ -64,56 +64,35 @@ namespace MeshWorker
       GnuplotPatch();
 
       /**
-       * Initialize for writing
-       * <i>n</i> data vectors. The
-       * number of points is the
-       * number of quadrature
-       * points in a single
-       * direction in a tensor
-       * product formula. It must
-       * match the number in the
-       * actual Quadrature used to
-       * create the patches. The
-       * total number of data
-       * vectors produced is <tt>n+dim</tt>
-       * and the first dim should be
-       * the space coordinates of
-       * the points. Nevertheless,
-       * it is up to the user to
-       * set these values to
-       * whatever is desired.
+       * Initialize for writing <i>n</i> data vectors. The number of points is
+       * the number of quadrature points in a single direction in a tensor
+       * product formula. It must match the number in the actual Quadrature
+       * used to create the patches. The total number of data vectors produced
+       * is <tt>n+dim</tt> and the first dim should be the space coordinates
+       * of the points. Nevertheless, it is up to the user to set these values
+       * to whatever is desired.
        */
       void initialize (const unsigned int n_points,
                        const unsigned int n_vectors);
 
       /**
-       * Set the stream #os to
-       * which data is written. If
-       * no stream is selected with
-       * this function, data goes
-       * to @p deallog.
+       * Set the stream #os to which data is written. If no stream is selected
+       * with this function, data goes to @p deallog.
        */
       void initialize_stream (std::ostream &stream);
 
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <int dim>
       void initialize_info(DoFInfo<dim> &info, bool face);
 
       /**
-       * Write the patch to the
-       * output stream.
+       * Write the patch to the output stream.
        */
       template<int dim>
       void assemble(const DoFInfo<dim> &info);
@@ -127,32 +106,25 @@ namespace MeshWorker
 
     private:
       /**
-       * Write the object T either
-       * to the stream #os, if initialize_stream()
-       * has been called, or to
-       * @p deallog if no pointer has
-       * been set.
+       * Write the object T either to the stream #os, if initialize_stream()
+       * has been called, or to @p deallog if no pointer has been set.
        */
       template<typename T>
       void write(const T &t) const;
 
       /**
-       * Write an end-of-line marker either
-       * to the stream #os, if initialize_stream
-       * has been called, or to
-       * @p deallog if no pointer has
+       * Write an end-of-line marker either to the stream #os, if
+       * initialize_stream has been called, or to @p deallog if no pointer has
        * been set.
        */
       void write_endl () const;
 
       /**
-       * The number of output
-       * components in each point.
+       * The number of output components in each point.
        */
       unsigned int n_vectors;
       /**
-       * The number of points in
-       * one direction.
+       * The number of points in one direction.
        */
       unsigned int n_points;
 
index ed299cef9c4071de87da42af44ee4f5477d682f4..ee39e96b4cb1072aa38a285b9ba58c1e5e799f8b 100644 (file)
 #include <deal.II/multigrid/mg_constrained_dofs.h>
 
 /**
- * @file
- * @brief MeshWorker::Assember objects for systems without block structure
+ * @file @brief MeshWorker::Assember objects for systems without block
+ * structure
  *
- * The header containing the classes
- * MeshWorker::Assember::MatrixSimple,
- * MeshWorker::Assember::MGMatrixSimple,
- * MeshWorker::Assember::ResidualSimple, and
- * MeshWorker::Assember::SystemSimple.
+ * The header containing the classes MeshWorker::Assember::MatrixSimple,
+ * MeshWorker::Assember::MGMatrixSimple, MeshWorker::Assember::ResidualSimple,
+ * and MeshWorker::Assember::SystemSimple.
  */
 
 DEAL_II_NAMESPACE_OPEN
@@ -46,12 +44,12 @@ namespace MeshWorker
     /**
      * Assemble residuals without block structure.
      *
-     * The data structure for this Assembler class is a simple vector on
-     * each cell with entries from zero to
-     * FiniteElementData::dofs_per_cell and a simple global vector with
-     * entries numbered from zero to DoFHandler::n_dofs(). No BlockInfo is
-     * required and the global vector may be any type of vector having
-     * element access through <tt>operator() (unsigned int)</tt>
+     * The data structure for this Assembler class is a simple vector on each
+     * cell with entries from zero to FiniteElementData::dofs_per_cell and a
+     * simple global vector with entries numbered from zero to
+     * DoFHandler::n_dofs(). No BlockInfo is required and the global vector
+     * may be any type of vector having element access through <tt>operator()
+     * (unsigned int)</tt>
      *
      * @ingroup MeshWorker
      * @author Guido Kanschat, 2009
@@ -61,10 +59,10 @@ namespace MeshWorker
     {
     public:
       /**
-       * Initialize with an AnyData object holding the result of
-       * assembling.
+       * Initialize with an AnyData object holding the result of assembling.
        *
-       * Assembling currently writes into the first vector of <tt>results</tt>.
+       * Assembling currently writes into the first vector of
+       * <tt>results</tt>.
        */
       void initialize(AnyData &results);
 
@@ -81,25 +79,23 @@ namespace MeshWorker
        * @deprecated This function is of no effect. Only the block info
        * structure in DoFInfo is being used.
        *
-       * Store information on the local block structure. If the
-       * assembler is inititialized with this function,
-       * initialize_info() will generate one local matrix for each
-       * block row and column, which will be numbered
+       * Store information on the local block structure. If the assembler is
+       * inititialized with this function, initialize_info() will generate one
+       * local matrix for each block row and column, which will be numbered
        * lexicographically, row by row.
        *
-       * In spite of using local block structure, all blocks will be
-       * enteres into the same global matrix, disregarding any global
-       * block structure.
+       * In spite of using local block structure, all blocks will be enteres
+       * into the same global matrix, disregarding any global block structure.
        */
 
       void initialize_local_blocks(const BlockIndices &);
 
       /**
-       * Initialize the local data in the DoFInfo object used later
-       * for assembling.
+       * Initialize the local data in the DoFInfo object used later for
+       * assembling.
        *
-       * The info object refers to a cell if <code>!face</code>, or
-       * else to an interior or boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
@@ -107,9 +103,8 @@ namespace MeshWorker
       /**
        * Assemble the local residuals into the global residuals.
        *
-       * Values are added to the previous contents. If constraints are
-       * active, ConstraintMatrix::distribute_local_to_global() is
-       * used.
+       * Values are added to the previous contents. If constraints are active,
+       * ConstraintMatrix::distribute_local_to_global() is used.
        */
       template <class DOFINFO>
       void assemble(const DOFINFO &info);
@@ -134,26 +129,24 @@ namespace MeshWorker
 
     /**
      * Assemble local matrices into a single global matrix. If this global
-     * matrix has a block structure, this structure is not used, but
-     * rather the global numbering of degrees of freedom.
+     * matrix has a block structure, this structure is not used, but rather
+     * the global numbering of degrees of freedom.
      *
-     * After being initialized with a SparseMatrix object (or another
-     * matrix offering the same functionality as SparseMatrix::add()),
-     * this class can be used in a MeshWorker::loop() to assemble the cell
-     * and face matrices into the global matrix.
+     * After being initialized with a SparseMatrix object (or another matrix
+     * offering the same functionality as SparseMatrix::add()), this class can
+     * be used in a MeshWorker::loop() to assemble the cell and face matrices
+     * into the global matrix.
      *
      * If a ConstraintMatrix has been provided during initialization, this
-     * matrix will be used
-     * (ConstraintMatrix::distribute_local_to_global(), to be precise) to
-     * enter the local matrix into the global sparse matrix.
+     * matrix will be used (ConstraintMatrix::distribute_local_to_global(), to
+     * be precise) to enter the local matrix into the global sparse matrix.
      *
-     * The assembler can handle two different types of local data. First,
-     * by default, the obvious choice of taking a single local matrix with
-     * dimensions equal to the number of degrees of freedom of the
-     * cell. Alternatively, a local block structure can be initialized
-     * in DoFInfo. After this, the local data will be
-     * arranged as an array of n by n FullMatrix blocks, which are
-     * ordered lexicographically in DoFInfo.
+     * The assembler can handle two different types of local data. First, by
+     * default, the obvious choice of taking a single local matrix with
+     * dimensions equal to the number of degrees of freedom of the cell.
+     * Alternatively, a local block structure can be initialized in DoFInfo.
+     * After this, the local data will be arranged as an array of n by n
+     * FullMatrix blocks, which are ordered lexicographically in DoFInfo.
      *
      * @ingroup MeshWorker
      * @author Guido Kanschat, 2009
@@ -163,8 +156,8 @@ namespace MeshWorker
     {
     public:
       /**
-       * Constructor, initializing the #threshold, which limits how
-       * small numbers may be to be entered into the matrix.
+       * Constructor, initializing the #threshold, which limits how small
+       * numbers may be to be entered into the matrix.
        */
       MatrixSimple(double threshold = 1.e-12);
 
@@ -173,11 +166,11 @@ namespace MeshWorker
        */
       void initialize(MATRIX &m);
       /**
-       * Initialize the constraints. After this function has been
-       * called with a valid ConstraintMatrix, the function
-       * ConstraintMatrix::distribute_local_to_global() will be used
-       * by assemble() to distribute the cell and face matrices into a
-       * global sparse matrix.
+       * Initialize the constraints. After this function has been called with
+       * a valid ConstraintMatrix, the function
+       * ConstraintMatrix::distribute_local_to_global() will be used by
+       * assemble() to distribute the cell and face matrices into a global
+       * sparse matrix.
        */
       void initialize(const ConstraintMatrix &constraints);
 
@@ -185,25 +178,23 @@ namespace MeshWorker
        * @deprecated This function is of no effect. Only the block info
        * structure in DoFInfo is being used.
        *
-       * Store information on the local block structure. If the
-       * assembler is inititialized with this function,
-       * initialize_info() will generate one local matrix for each
-       * block row and column, which will be numbered
+       * Store information on the local block structure. If the assembler is
+       * inititialized with this function, initialize_info() will generate one
+       * local matrix for each block row and column, which will be numbered
        * lexicographically, row by row.
        *
-       * In spite of using local block structure, all blocks will be
-       * enteres into the same global matrix, disregarding any global
-       * block structure.
+       * In spite of using local block structure, all blocks will be enteres
+       * into the same global matrix, disregarding any global block structure.
        */
 
       void initialize_local_blocks(const BlockIndices &);
 
       /**
-       * Initialize the local data in the DoFInfo object used later
-       * for assembling.
+       * Initialize the local data in the DoFInfo object used later for
+       * assembling.
        *
-       * The info object refers to a cell if <code>!face</code>, or
-       * else to an interior or boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
@@ -215,36 +206,33 @@ namespace MeshWorker
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local matrices in the info objects into the
-       * global matrix.
+       * Assemble both local matrices in the info objects into the global
+       * matrix.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
                     const DOFINFO &info2);
     private:
       /**
-       * Assemble a single matrix
-       * into #matrix.
+       * Assemble a single matrix into #matrix.
        */
       void assemble(const FullMatrix<double> &M,
                     const std::vector<types::global_dof_index> &i1,
                     const std::vector<types::global_dof_index> &i2);
 
       /**
-       * The global matrix being
-       * assembled.
+       * The global matrix being assembled.
        */
       SmartPointer<MATRIX,MatrixSimple<MATRIX> > matrix;
       /**
-       * A pointer to the object
-       * containing constraints.
+       * A pointer to the object containing constraints.
        */
       SmartPointer<const ConstraintMatrix,MatrixSimple<MATRIX> > constraints;
 
       /**
-       * The smallest positive number that will be entered into the
-       * global matrix. All smaller absolute values will be treated as
-       * zero and will not be assembled.
+       * The smallest positive number that will be entered into the global
+       * matrix. All smaller absolute values will be treated as zero and will
+       * not be assembled.
        */
       const double threshold;
 
@@ -252,11 +240,11 @@ namespace MeshWorker
 
 
     /**
-     * Assemble local matrices into level matrices without using
-     * block structure.
+     * Assemble local matrices into level matrices without using block
+     * structure.
      *
-     * @todo The matrix structures needed for assembling level matrices
-     * with local refinement and continuous elements are missing.
+     * @todo The matrix structures needed for assembling level matrices with
+     * local refinement and continuous elements are missing.
      *
      * @ingroup MeshWorker
      * @author Guido Kanschat, 2009
@@ -266,8 +254,8 @@ namespace MeshWorker
     {
     public:
       /**
-       * Constructor, initializing the #threshold, which limits how
-       * small numbers may be to be entered into the matrix.
+       * Constructor, initializing the #threshold, which limits how small
+       * numbers may be to be entered into the matrix.
        */
       MGMatrixSimple(double threshold = 1.e-12);
 
@@ -282,41 +270,39 @@ namespace MeshWorker
       void initialize(const MGConstrainedDoFs &mg_constrained_dofs);
 
       /**
-       * @deprecated This function is of no effect. Only the block
-       * info structure in DoFInfo is being used.
+       * @deprecated This function is of no effect. Only the block info
+       * structure in DoFInfo is being used.
        *
-       * Store information on the local block structure. If the
-       * assembler is inititialized with this function,
-       * initialize_info() will generate one local matrix for each
-       * block row and column, which will be numbered
+       * Store information on the local block structure. If the assembler is
+       * inititialized with this function, initialize_info() will generate one
+       * local matrix for each block row and column, which will be numbered
        * lexicographically, row by row.
        *
-       * In spite of using local block structure, all blocks will be
-       * enteres into the same global matrix, disregarding any global
-       * block structure.
+       * In spite of using local block structure, all blocks will be enteres
+       * into the same global matrix, disregarding any global block structure.
        */
       void initialize_local_blocks(const BlockIndices &);
 
       /**
-       * Initialize the matrices #flux_up and #flux_down used for
-       * local refinement with discontinuous Galerkin methods.
+       * Initialize the matrices #flux_up and #flux_down used for local
+       * refinement with discontinuous Galerkin methods.
        */
       void initialize_fluxes(MGLevelObject<MATRIX> &flux_up,
                              MGLevelObject<MATRIX> &flux_down);
 
       /**
-       * Initialize the matrices #interface_in and #interface_out used
-       * for local refinement with continuous Galerkin methods.
+       * Initialize the matrices #interface_in and #interface_out used for
+       * local refinement with continuous Galerkin methods.
        */
 
       void initialize_interfaces(MGLevelObject<MATRIX> &interface_in,
                                  MGLevelObject<MATRIX> &interface_out);
       /**
-       * Initialize the local data in the DoFInfo object used later
-       * for assembling.
+       * Initialize the local data in the DoFInfo object used later for
+       * assembling.
        *
-       * The info object refers to a cell if <code>!face</code>, or
-       * else to an interior or boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
@@ -328,8 +314,8 @@ namespace MeshWorker
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local matrices in the info objects into the
-       * global matrices.
+       * Assemble both local matrices in the info objects into the global
+       * matrices.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info1,
@@ -397,26 +383,26 @@ namespace MeshWorker
       SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > matrix;
 
       /**
-       * The matrix used for face flux terms across the refinement
-       * edge, coupling coarse to fine.
+       * The matrix used for face flux terms across the refinement edge,
+       * coupling coarse to fine.
        */
       SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > flux_up;
 
       /**
-       * The matrix used for face flux terms across the refinement
-       * edge, coupling fine to coarse.
+       * The matrix used for face flux terms across the refinement edge,
+       * coupling fine to coarse.
        */
       SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > flux_down;
 
       /**
-       * The matrix used for face contributions for continuous
-       * elements across the refinement edge, coupling coarse to fine.
+       * The matrix used for face contributions for continuous elements across
+       * the refinement edge, coupling coarse to fine.
        */
       SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > interface_in;
 
       /**
-       * The matrix used for face contributions for continuous
-       * elements across the refinement edge, coupling fine to coarse.
+       * The matrix used for face contributions for continuous elements across
+       * the refinement edge, coupling fine to coarse.
        */
       SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > interface_out;
       /**
@@ -425,9 +411,9 @@ namespace MeshWorker
       SmartPointer<const MGConstrainedDoFs,MGMatrixSimple<MATRIX> > mg_constrained_dofs;
 
       /**
-       * The smallest positive number that will be entered into the
-       * global matrix. All smaller absolute values will be treated as
-       * zero and will not be assembled.
+       * The smallest positive number that will be entered into the global
+       * matrix. All smaller absolute values will be treated as zero and will
+       * not be assembled.
        */
       const double threshold;
 
@@ -435,11 +421,11 @@ namespace MeshWorker
 
 
     /**
-     * Assemble a simple matrix and a simple right hand side at once. We
-     * use a combination of MatrixSimple and ResidualSimple to achieve
-     * this. Cell and face operators should fill the matrix and vector
-     * objects in LocalResults and this class will assemble
-     * them into matrix and vector objects.
+     * Assemble a simple matrix and a simple right hand side at once. We use a
+     * combination of MatrixSimple and ResidualSimple to achieve this. Cell
+     * and face operators should fill the matrix and vector objects in
+     * LocalResults and this class will assemble them into matrix and vector
+     * objects.
      *
      * @ingroup MeshWorker
      * @author Guido Kanschat, 2009
@@ -451,55 +437,42 @@ namespace MeshWorker
     {
     public:
       /**
-       * Constructor setting the
-       * threshold value in
-       * MatrixSimple.
+       * Constructor setting the threshold value in MatrixSimple.
        */
       SystemSimple(double threshold = 1.e-12);
 
       /**
-       * Store the two objects data
-       * is assembled into.
+       * Store the two objects data is assembled into.
        */
       void initialize(MATRIX &m, VECTOR &rhs);
 
       /**
-       * Initialize the constraints. After this function has been
-       * called with a valid ConstraintMatrix, the function
-       * ConstraintMatrix::distribute_local_to_global() will be used
-       * by assemble() to distribute the cell and face matrices into a
-       * global sparse matrix.
+       * Initialize the constraints. After this function has been called with
+       * a valid ConstraintMatrix, the function
+       * ConstraintMatrix::distribute_local_to_global() will be used by
+       * assemble() to distribute the cell and face matrices into a global
+       * sparse matrix.
        */
       void initialize(const ConstraintMatrix &constraints);
 
       /**
-       * Initialize the local data
-       * in the
-       * DoFInfo
-       * object used later for
+       * Initialize the local data in the DoFInfo object used later for
        * assembling.
        *
-       * The info object refers to
-       * a cell if
-       * <code>!face</code>, or
-       * else to an interior or
-       * boundary face.
+       * The info object refers to a cell if <code>!face</code>, or else to an
+       * interior or boundary face.
        */
       template <class DOFINFO>
       void initialize_info(DOFINFO &info, bool face) const;
 
       /**
-       * Assemble the matrix
-       * DoFInfo::M1[0]
-       * into the global matrix.
+       * Assemble the matrix DoFInfo::M1[0] into the global matrix.
        */
       template<class DOFINFO>
       void assemble(const DOFINFO &info);
 
       /**
-       * Assemble both local
-       * matrices in the info
-       * objects into the global
+       * Assemble both local matrices in the info objects into the global
        * matrix.
        */
       template<class DOFINFO>
index 240a1828f4e7e3bd1133d1991004e9bd5fba4740..89fd0a0f4710cf8a1e22cec781f836b87e0f5635 100644 (file)
@@ -33,13 +33,12 @@ namespace MeshWorker
    * A class that selects vectors from a list of named vectors.
    *
    * Since the number of vectors in an AnyData object may grow with every
-   * nesting of applications or loops, it is important to be able to
-   * select those, which are actually used in computing residuals etc.
-   * This class organizes the selection.
+   * nesting of applications or loops, it is important to be able to select
+   * those, which are actually used in computing residuals etc. This class
+   * organizes the selection.
    *
-   * It is used for instance in IntegrationWorker to
-   * determine which values, derivatives or second derivatives are
-   * actually computed.
+   * It is used for instance in IntegrationWorker to determine which values,
+   * derivatives or second derivatives are actually computed.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat 2009
@@ -50,12 +49,11 @@ namespace MeshWorker
   public:
     /**
      * Add a vector to the selection of finite element functions. The
-     * arguments are the name of the vector and indicators, which
-     * information is to be extracted from the vector. The name refers
-     * to an entry in a AnyData object, which will be identified by
-     * initialize().  The three bool parameters indicate, whether
-     * values, greadients and Hessians of the finite element function
-     * are to be computed on each cell or face.
+     * arguments are the name of the vector and indicators, which information
+     * is to be extracted from the vector. The name refers to an entry in a
+     * AnyData object, which will be identified by initialize().  The three
+     * bool parameters indicate, whether values, greadients and Hessians of
+     * the finite element function are to be computed on each cell or face.
      */
     void add(const std::string &name,
              const bool values = true,
@@ -63,8 +61,8 @@ namespace MeshWorker
              const bool hessians = false);
 
     /**
-     * Does the same as the function above but it is possible to
-     * select a block of the global vector.
+     * Does the same as the function above but it is possible to select a
+     * block of the global vector.
      */
 //      void add(const std::string& name,
 //               const unsigned int selected_block,
@@ -73,14 +71,13 @@ namespace MeshWorker
 //             bool hessians = false);
 
     /**
-     * Initialize the selection field with a data vector. While add()
-     * only enters the names of vectors, which will be used in the
-     * integration loop over cells and faces, this function links the
-     * names to actual vectos in a AnyData object.
+     * Initialize the selection field with a data vector. While add() only
+     * enters the names of vectors, which will be used in the integration loop
+     * over cells and faces, this function links the names to actual vectos in
+     * a AnyData object.
      *
-     * @note This function caches the index associated with a
-     * name. Therefore, it must be called every time after the AnyData
-     * object has changed.
+     * @note This function caches the index associated with a name. Therefore,
+     * it must be called every time after the AnyData object has changed.
      */
     void initialize(const AnyData &);
 
@@ -141,8 +138,7 @@ namespace MeshWorker
     unsigned int hessian_index (const unsigned int i) const;
 
     /**
-     * Print the contents of the
-     * selection to the stream.
+     * Print the contents of the selection to the stream.
      */
     template <class STREAM, typename DATA>
     void print (STREAM &s, const AnyData &v) const;
@@ -166,8 +162,7 @@ namespace MeshWorker
 
   protected:
     /**
-     * Selection of the vectors
-     * used to compute values.
+     * Selection of the vectors used to compute values.
      */
     NamedSelection value_selection;
 
@@ -183,8 +178,8 @@ namespace MeshWorker
   };
 
   /**
-   * Based on VectorSelector, this is the class used by IntegrationInfo
-   * to compute values of source vectors in quadrature points.
+   * Based on VectorSelector, this is the class used by IntegrationInfo to
+   * compute values of source vectors in quadrature points.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -218,44 +213,42 @@ namespace MeshWorker
      */
     virtual ~VectorDataBase();
     /**
-     * The only function added to VectorSelector is an abstract
-     * virtual function implemented in the derived class template and
-     * called by IntegrationInfo.
+     * The only function added to VectorSelector is an abstract virtual
+     * function implemented in the derived class template and called by
+     * IntegrationInfo.
      *
-     * Depending on the selections made in our base class, this fills
-     * the first three arguments with the local data of the finite
-     * element functions. It is usually called either for the whole
-     * FESystem, or for each base element separately.
+     * Depending on the selections made in our base class, this fills the
+     * first three arguments with the local data of the finite element
+     * functions. It is usually called either for the whole FESystem, or for
+     * each base element separately.
      *
-     * @param values is the vector filled with the values of the
-     * finite element function in the quadrature points.
+     * @param values is the vector filled with the values of the finite
+     * element function in the quadrature points.
      *
-     * @param gradients is the vector filled with the derivatives of
-     * the finite element function in the quadrature points.
+     * @param gradients is the vector filled with the derivatives of the
+     * finite element function in the quadrature points.
      *
-     * @param hessians is the vector filled with the second
-     * derivatives of the finite element function in the quadrature
-     * points.
+     * @param hessians is the vector filled with the second derivatives of the
+     * finite element function in the quadrature points.
      *
-     * @param fe is the FEValuesBase object which is used to compute
-     * the function values. Its UpdateFlags must have been set
-     * appropriately.
+     * @param fe is the FEValuesBase object which is used to compute the
+     * function values. Its UpdateFlags must have been set appropriately.
      *
      * @param index is the local index vector. If @p fe refers to base
-     * elements of the system, this vector should be sorted by block
-     * and the arguments @p start and @p size below specify the subset
-     * of @p indices used.
+     * elements of the system, this vector should be sorted by block and the
+     * arguments @p start and @p size below specify the subset of @p indices
+     * used.
      *
-     * @param component is the first index in @p values, @p gradients
-     * and @p hessians entered in this function.
+     * @param component is the first index in @p values, @p gradients and @p
+     * hessians entered in this function.
      *
      * @param n_comp is the number of components to be filled.
      *
-     * @param start is the first index of this block in @p indices, or
-     * zero if no base elements are used.
+     * @param start is the first index of this block in @p indices, or zero if
+     * no base elements are used.
      *
-     * @param size is the number of dofs per cell of the current
-     * element or base element.
+     * @param size is the number of dofs per cell of the current element or
+     * base element.
      */
     virtual void fill(
       std::vector<std::vector<std::vector<double> > > &values,
@@ -269,10 +262,10 @@ namespace MeshWorker
       const unsigned int size) const;
 
     /**
-     * Fill the local data vector from level vectors. Performs exactly
-     * what the other fill() does, but uses the cell level to access a
-     * single level out of a hierarchy of level vectors, instead of a
-     * global data vector on the active cells.
+     * Fill the local data vector from level vectors. Performs exactly what
+     * the other fill() does, but uses the cell level to access a single level
+     * out of a hierarchy of level vectors, instead of a global data vector on
+     * the active cells.
      */
     virtual void mg_fill(
       std::vector<std::vector<std::vector<double> > > &values,
@@ -296,9 +289,9 @@ namespace MeshWorker
 
 
   /**
-   * Based on VectorSelector, this is the class that implements the
-   * function VectorDataBase::fill() for a certain type of vector, using
-   * AnyData to identify vectors by name.
+   * Based on VectorSelector, this is the class that implements the function
+   * VectorDataBase::fill() for a certain type of vector, using AnyData to
+   * identify vectors by name.
    *
    * @ingroup MeshWorker
    * @author Guido Kanschat, 2009
@@ -313,8 +306,7 @@ namespace MeshWorker
      */
     VectorData();
     /**
-     * Constructor using a
-     * prefilled VectorSelector
+     * Constructor using a prefilled VectorSelector
      */
     VectorData(const VectorSelector &);
 
@@ -356,15 +348,15 @@ namespace MeshWorker
       const unsigned int size) const;
 
     /**
-    * The memory used by this object.
-    */
+     * The memory used by this object.
+     */
     std::size_t memory_consumption () const;
   };
 
 
   /**
-   * Based on VectorSelector, this is the class that implements the
-   * function VectorDataBase::fill() for a certain type of multilevel vectors, using
+   * Based on VectorSelector, this is the class that implements the function
+   * VectorDataBase::fill() for a certain type of multilevel vectors, using
    * AnyData to identify vectors by name.
    *
    * @ingroup MeshWorker
index 6b5ec4d2550a42e4b2ffee3860dba6fd007223d0..838cf27386fb62da41f2a628ff3e2c42d09a6708 100644 (file)
@@ -37,11 +37,11 @@ template <typename> class MGLevelObject;
 
 /**
  * Multilevel matrix base. This class sets up the interface needed by
- * multilevel algorithms. It has no relation to the actual matrix type
- * and takes the vector class as only template argument.
+ * multilevel algorithms. It has no relation to the actual matrix type and
+ * takes the vector class as only template argument.
  *
- * Usually, the derived class MGMatrix, operating on an
- * MGLevelObject of matrices will be sufficient for applications.
+ * Usually, the derived class MGMatrix, operating on an MGLevelObject of
+ * matrices will be sufficient for applications.
  *
  * @author Guido Kanschat, 2002
  */
@@ -55,34 +55,28 @@ public:
   virtual ~MGMatrixBase();
 
   /**
-   * Matrix-vector-multiplication on
-   * a certain level.
+   * Matrix-vector-multiplication on a certain level.
    */
   virtual void vmult (const unsigned int level,
                       VECTOR &dst,
                       const VECTOR &src) const = 0;
 
   /**
-   * Adding matrix-vector-multiplication on
-   * a certain level.
+   * Adding matrix-vector-multiplication on a certain level.
    */
   virtual void vmult_add (const unsigned int level,
                           VECTOR &dst,
                           const VECTOR &src) const = 0;
 
   /**
-   * Transpose
-   * matrix-vector-multiplication on
-   * a certain level.
+   * Transpose matrix-vector-multiplication on a certain level.
    */
   virtual void Tvmult (const unsigned int level,
                        VECTOR &dst,
                        const VECTOR &src) const = 0;
 
   /**
-   * Adding transpose
-   * matrix-vector-multiplication on
-   * a certain level.
+   * Adding transpose matrix-vector-multiplication on a certain level.
    */
   virtual void Tvmult_add (const unsigned int level,
                            VECTOR &dst,
@@ -91,9 +85,9 @@ public:
 
 
 /**
- * Base class for coarse grid solvers.  This defines the virtual
- * parenthesis operator, being the interface used by multigrid
- * methods. Any implementation will be done by derived classes.
+ * Base class for coarse grid solvers.  This defines the virtual parenthesis
+ * operator, being the interface used by multigrid methods. Any implementation
+ * will be done by derived classes.
  *
  * @author Guido Kanschat, 2002
  */
@@ -118,47 +112,44 @@ public:
 /**
  * Base class used to declare the operations needed by a concrete class
  * implementing prolongation and restriction of vectors in the multigrid
- * context. This class is abstract and has no implementation of
- * these operations.
+ * context. This class is abstract and has no implementation of these
+ * operations.
  *
- * There are several derived classes, reflecting the fact that vector
- * types and numbering of the fine-grid discretization and of the
- * multi-level implementation are independent.
+ * There are several derived classes, reflecting the fact that vector types
+ * and numbering of the fine-grid discretization and of the multi-level
+ * implementation are independent.
  *
- * If you use multigrid for a single PDF or for your complete system
- * of equations, you
- * will use MGTransferPrebuilt together with Multigrid. The vector
- * types used on the fine grid as well as for the multilevel
- * operations may be Vector or BlockVector. In both cases,
- * MGTransferPrebuilt will operate on all components of the solution.
+ * If you use multigrid for a single PDF or for your complete system of
+ * equations, you will use MGTransferPrebuilt together with Multigrid. The
+ * vector types used on the fine grid as well as for the multilevel operations
+ * may be Vector or BlockVector. In both cases, MGTransferPrebuilt will
+ * operate on all components of the solution.
  *
- * @note For the following, it is important to realize the difference
- * between a solution @ref GlossComponent "component" and a solution
- * @ref GlossBlock "block". The distinction only applies if vector valued
- * elements are used, but is quite important then. This is reflected
- * in the fact that it is not possible right now to use transfer
- * classes based on MGTransferComponentBase for genuine vector valued
- * elements, but descendants of MGTransferBlockBase would have to be
- * applied. In the following text, we will use the term
+ * @note For the following, it is important to realize the difference between
+ * a solution @ref GlossComponent "component" and a solution @ref GlossBlock
+ * "block". The distinction only applies if vector valued elements are used,
+ * but is quite important then. This is reflected in the fact that it is not
+ * possible right now to use transfer classes based on MGTransferComponentBase
+ * for genuine vector valued elements, but descendants of MGTransferBlockBase
+ * would have to be applied. In the following text, we will use the term
  * <em>block</em>, but remark that it might refer to components as well.
  *
- * @todo update the following documentation, since it does not reflect
- * the latest changes in structure.
+ * @todo update the following documentation, since it does not reflect the
+ * latest changes in structure.
  *
- * For mixed systems, it may be required to do multigrid only for a
- * single component or for some components. The classes
- * MGTransferSelect and MGTransferBlock handle these cases.
+ * For mixed systems, it may be required to do multigrid only for a single
+ * component or for some components. The classes MGTransferSelect and
+ * MGTransferBlock handle these cases.
  *
- * MGTransferSelect is used if you use mutligrid (on Vector objects)
- * for a single component, possibly grouped using
- * <tt>mg_target_component</tt>.
+ * MGTransferSelect is used if you use mutligrid (on Vector objects) for a
+ * single component, possibly grouped using <tt>mg_target_component</tt>.
  *
- * The class MGTransferBlock handles the case where your multigrid
- * method operates on BlockVector objects. These can contain all or a
- * consecutive set of the blocks of the complete system. Since most
- * smoothers cannot operate on block structures, it is not clear
- * whether this case is really useful. Therefore, a tested
- * implementation of this case will be supplied when needed.
+ * The class MGTransferBlock handles the case where your multigrid method
+ * operates on BlockVector objects. These can contain all or a consecutive set
+ * of the blocks of the complete system. Since most smoothers cannot operate
+ * on block structures, it is not clear whether this case is really useful.
+ * Therefore, a tested implementation of this case will be supplied when
+ * needed.
  *
  * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2007
  */
@@ -167,56 +158,37 @@ class MGTransferBase : public Subscriptor
 {
 public:
   /**
-   * Destructor. Does nothing here, but
-   * needs to be declared virtual anyway.
+   * Destructor. Does nothing here, but needs to be declared virtual anyway.
    */
   virtual ~MGTransferBase();
 
   /**
-   * Prolongate a vector from level
-   * <tt>to_level-1</tt> to level
-   * <tt>to_level</tt>. The previous
-   * content of <tt>dst</tt> is
-   * overwritten.
+   * Prolongate a vector from level <tt>to_level-1</tt> to level
+   * <tt>to_level</tt>. The previous content of <tt>dst</tt> is overwritten.
    *
-   * @arg src is a vector with as
-   * many elements as there are
-   * degrees of freedom on the
-   * coarser level involved.
+   * @arg src is a vector with as many elements as there are degrees of
+   * freedom on the coarser level involved.
    *
-   * @arg dst has as many elements
-   * as there are degrees of
-   * freedom on the finer level.
+   * @arg dst has as many elements as there are degrees of freedom on the
+   * finer level.
    */
   virtual void prolongate (const unsigned int to_level,
                            VECTOR            &dst,
                            const VECTOR      &src) const = 0;
 
   /**
-   * Restrict a vector from level
-   * <tt>from_level</tt> to level
-   * <tt>from_level-1</tt> and add
-   * this restriction to
-   * <tt>dst</tt>. If the region
-   * covered by cells on level
-   * <tt>from_level</tt> is smaller
-   * than that of level
-   * <tt>from_level-1</tt> (local
-   * refinement), then some degrees
-   * of freedom in <tt>dst</tt> are
-   * active and will not be
-   * altered. For the other degress
-   * of freedom, the result of the
-   * restriction is added.
+   * Restrict a vector from level <tt>from_level</tt> to level
+   * <tt>from_level-1</tt> and add this restriction to <tt>dst</tt>. If the
+   * region covered by cells on level <tt>from_level</tt> is smaller than that
+   * of level <tt>from_level-1</tt> (local refinement), then some degrees of
+   * freedom in <tt>dst</tt> are active and will not be altered. For the other
+   * degress of freedom, the result of the restriction is added.
    *
-   * @arg src is a vector with as
-   * many elements as there are
-   * degrees of freedom on the
-   * finer level
+   * @arg src is a vector with as many elements as there are degrees of
+   * freedom on the finer level
    *
-   * @arg dst has as many elements as there
-   * are degrees of freedom on the coarser
-   * level.
+   * @arg dst has as many elements as there are degrees of freedom on the
+   * coarser level.
    *
    */
   virtual void restrict_and_add (const unsigned int from_level,
@@ -227,8 +199,8 @@ public:
 
 
 /**
- * Base class for multigrid smoothers. Does nothing but defining the
- * interface used by multigrid methods.
+ * Base class for multigrid smoothers. Does nothing but defining the interface
+ * used by multigrid methods.
  *
  * @author Guido Kanschat, 2002
  */
@@ -246,9 +218,7 @@ public:
   virtual void clear() = 0;
 
   /**
-   * Smoothing function. This is the
-   * function used in multigrid
-   * methods.
+   * Smoothing function. This is the function used in multigrid methods.
    */
   virtual void smooth (const unsigned int level,
                        VECTOR            &u,
index 95e75a30af9869e673324f20386867f8e90c838c..5a333df816ac16f569d6c50ac7cacde63ab83a49 100644 (file)
@@ -36,10 +36,10 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * General smoother class for block vectors. This class gives complete
- * freedom to the choice of a block smoother by being initialized with
- * a matrix and a smoother object. Therefore, the smoother object for
- * each level must be constructed by hand.
+ * General smoother class for block vectors. This class gives complete freedom
+ * to the choice of a block smoother by being initialized with a matrix and a
+ * smoother object. Therefore, the smoother object for each level must be
+ * constructed by hand.
  *
  * @author Guido Kanschat, 2005
  */
@@ -49,8 +49,7 @@ class MGSmootherBlock
 {
 public:
   /**
-   * Constructor. Sets memory and
-   * smoothing parameters.
+   * Constructor. Sets memory and smoothing parameters.
    */
   MGSmootherBlock(VectorMemory<BlockVector<number> > &mem,
                   const unsigned int steps = 1,
@@ -60,26 +59,17 @@ public:
                   const bool reverse = false);
 
   /**
-   * Initialize for matrices. The
-   * parameter <tt>matrices</tt> can be
-   * any object having functions
-   * <tt>get_minlevel()</tt> and
-   * <tt>get_maxlevel()</tt> as well as
-   * an <tt>operator[]</tt> returning a
+   * Initialize for matrices. The parameter <tt>matrices</tt> can be any
+   * object having functions <tt>get_minlevel()</tt> and
+   * <tt>get_maxlevel()</tt> as well as an <tt>operator[]</tt> returning a
    * reference to @p MATRIX.
    *
-   * The same convention is used
-   * for the parameter
-   * <tt>smoothers</tt>, such that
-   * <tt>operator[]</tt> returns
-   * the object doing the
-   * block-smoothing on a single
-   * level.
+   * The same convention is used for the parameter <tt>smoothers</tt>, such
+   * that <tt>operator[]</tt> returns the object doing the block-smoothing on
+   * a single level.
    *
-   * This function stores pointers
-   * to the level matrices and
-   * smoothing operator for each
-   * level.
+   * This function stores pointers to the level matrices and smoothing
+   * operator for each level.
    */
   template <class MGMATRIX, class MGRELAX>
   void initialize (const MGMATRIX &matrices,
@@ -91,46 +81,34 @@ public:
   void clear ();
 
   /**
-   * Modify the number of smoothing
-   * steps on finest level.
+   * Modify the number of smoothing steps on finest level.
    */
   void set_steps (const unsigned int);
 
   /**
-   * Switch on/off variable
-   * smoothing.
+   * Switch on/off variable smoothing.
    */
   void set_variable (const bool);
 
   /**
-   * Switch on/off symmetric
-   * smoothing.
+   * Switch on/off symmetric smoothing.
    */
   void set_symmetric (const bool);
 
   /**
-   * Switch on/off transposed. This
-   * is mutually exclusive with
-   * reverse().
+   * Switch on/off transposed. This is mutually exclusive with reverse().
    */
   void set_transpose (const bool);
 
   /**
-   * Switch on/off reversed. This
-   * is mutually exclusive with
-   * transpose().
+   * Switch on/off reversed. This is mutually exclusive with transpose().
    */
   void set_reverse (const bool);
 
   /**
-   * Implementation of the
-   * interface for @p Multigrid.
-   * This function does nothing,
-   * which by comparison with the
-   * definition of this function
-   * means that the the smoothing
-   * operator equals the null
-   * operator.
+   * Implementation of the interface for @p Multigrid. This function does
+   * nothing, which by comparison with the definition of this function means
+   * that the the smoothing operator equals the null operator.
    */
   virtual void smooth (const unsigned int         level,
                        BlockVector<number>       &u,
index 5cb229412aa5e213ff43ba8793a5ebbbb3b93783..5955bf44c596e670bf1e77e6acc46d084993d5c5 100644 (file)
@@ -28,13 +28,12 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * Coarse grid solver using LAC iterative methods.
- * This is a little wrapper, transforming a triplet of iterative
- * solver, matrix and preconditioner into a coarse grid solver.
+ * Coarse grid solver using LAC iterative methods. This is a little wrapper,
+ * transforming a triplet of iterative solver, matrix and preconditioner into
+ * a coarse grid solver.
  *
- * The type of the matrix (i.e. the template parameter @p MATRIX)
- * should be derived from @p Subscriptor to allow for the use of a
- * smart pointer to it.
+ * The type of the matrix (i.e. the template parameter @p MATRIX) should be
+ * derived from @p Subscriptor to allow for the use of a smart pointer to it.
  *
  * @author Guido Kanschat, 1999, Ralf Hartmann, 2002.
  */
@@ -48,9 +47,7 @@ public:
   MGCoarseGridLACIteration ();
 
   /**
-   * Constructor.
-   * Store solver, matrix and
-   * preconditioning method for later
+   * Constructor. Store solver, matrix and preconditioning method for later
    * use.
    */
   template<class MATRIX, class PRECOND>
@@ -77,21 +74,16 @@ public:
   void clear ();
 
   /**
-   * Implementation of the abstract
-   * function.
-   * Calls the solver method with
-   * matrix, vectors and
-   * preconditioner.
+   * Implementation of the abstract function. Calls the solver method with
+   * matrix, vectors and preconditioner.
    */
   void operator() (const unsigned int   level,
                    VECTOR       &dst,
                    const VECTOR &src) const;
 
   /**
-   * Sets the matrix. This gives
-   * the possibility to replace the
-   * matrix that was given to the
-   * constructor by a new matrix.
+   * Sets the matrix. This gives the possibility to replace the matrix that
+   * was given to the constructor by a new matrix.
    */
   template <class MATRIX>
   void set_matrix (const MATRIX &);
@@ -116,11 +108,12 @@ private:
 
 
 /**
- * Coarse grid solver by QR factorization implemented in the class Householder.
+ * Coarse grid solver by QR factorization implemented in the class
+ * Householder.
  *
- * Upon initialization, the QR decomposition of the matrix is
- * computed. then, the operator() uses Householder::least_squares() to
- * compute the action of the inverse.
+ * Upon initialization, the QR decomposition of the matrix is computed. then,
+ * the operator() uses Householder::least_squares() to compute the action of
+ * the inverse.
  *
  * @author Guido Kanschat, 2003, 2012
  */
@@ -129,8 +122,7 @@ class MGCoarseGridHouseholder : public MGCoarseGridBase<VECTOR>
 {
 public:
   /**
-   * Constructor, taking the coarse
-   * grid matrix.
+   * Constructor, taking the coarse grid matrix.
    */
   MGCoarseGridHouseholder (const FullMatrix<number> *A = 0);
 
@@ -163,15 +155,12 @@ class MGCoarseGridSVD : public MGCoarseGridBase<VECTOR>
 {
 public:
   /**
-   * Constructor leaving an
-   * uninitialized object.
+   * Constructor leaving an uninitialized object.
    */
   MGCoarseGridSVD ();
 
   /**
-   * Initialize for a new
-   * matrix. This resets the
-   * dimensions to the
+   * Initialize for a new matrix. This resets the dimensions to the
    */
   void initialize (const FullMatrix<number> &A, const double threshold = 0);
 
index 4d7b591c46af3eede1410149c5365474756193cc..b6986b4f7aad371aad9ca126ffd639034ae4075e 100644 (file)
@@ -31,8 +31,8 @@ template <int dim, typename Number> struct FunctionMap;
 
 
 /**
- * Collection of boundary constraints and refinement edge constraints
- * for level vectors.
+ * Collection of boundary constraints and refinement edge constraints for
+ * level vectors.
  *
  * @ingroup mg
  */
@@ -42,10 +42,9 @@ public:
 
   typedef std::vector<std::set<types::global_dof_index> >::size_type size_dof;
   /**
-   * Fill the internal data structures with hanging node constraints
-   * extracted from the dof handler object. Works with natural
-   * boundary conditions only. There exists a sister function setting
-   * up boundary constraints as well.
+   * Fill the internal data structures with hanging node constraints extracted
+   * from the dof handler object. Works with natural boundary conditions only.
+   * There exists a sister function setting up boundary constraints as well.
    *
    * This function ensures that on every level, degrees of freedom at interior
    * edges of a refinement level are treated corrected but leaves degrees of
@@ -74,8 +73,7 @@ public:
   void clear();
 
   /**
-   * Determine whether a dof index is subject to a boundary
-   * constraint.
+   * Determine whether a dof index is subject to a boundary constraint.
    */
   bool is_boundary_index (const unsigned int level,
                           const types::global_dof_index index) const;
@@ -94,19 +92,17 @@ public:
                            const types::global_dof_index index) const;
 
   /**
-   * @deprecated Use is_boundary_index() instead. The logic behind
-   * this function here is unclear and for practical purposes, the
-   * other is needed.
+   * @deprecated Use is_boundary_index() instead. The logic behind this
+   * function here is unclear and for practical purposes, the other is needed.
    *
-   * Determine whether a dof index is subject to a boundary
-   * constraint.
+   * Determine whether a dof index is subject to a boundary constraint.
    */
   bool at_refinement_edge_boundary (const unsigned int level,
                                     const types::global_dof_index index) const DEAL_II_DEPRECATED;
 
   /**
-   * Return the indices of dofs for each level that are subject to
-   * boundary constraints.
+   * Return the indices of dofs for each level that are subject to boundary
+   * constraints.
    */
   const std::vector<std::set<types::global_dof_index> > &
   get_boundary_indices () const;
@@ -115,34 +111,34 @@ public:
    * @deprecated Use at_refinement_edge() if possible, else
    * get_refinement_edge_indices(unsigned int).
    *
-   * Return the indices of dofs for each level that lie on the
-   * refinement edge (i.e. are on faces between cells of this level
-   * and cells on the level below).
+   * Return the indices of dofs for each level that lie on the refinement edge
+   * (i.e. are on faces between cells of this level and cells on the level
+   * below).
    */
   const std::vector<std::vector<bool> > &
   get_refinement_edge_indices () const DEAL_II_DEPRECATED;
 
   /**
-   * Return the indices of dofs on the given level that lie on an
-   * refinement edge (dofs on faces to neighbors that are coarser)
+   * Return the indices of dofs on the given level that lie on an refinement
+   * edge (dofs on faces to neighbors that are coarser)
    */
   const IndexSet &
   get_refinement_edge_indices (unsigned int level) const;
 
   /**
-   * @deprecated Use at_refinement_edge_boundary() if possible, else
-   * use get_refinement_edge_boundary_indices().
+   * @deprecated Use at_refinement_edge_boundary() if possible, else use
+   * get_refinement_edge_boundary_indices().
    *
-   * Return the indices of dofs for each level that are in the
-   * intersection of the sets returned by get_boundary_indices() and
+   * Return the indices of dofs for each level that are in the intersection of
+   * the sets returned by get_boundary_indices() and
    * get_refinement_edge_indices().
    */
   const std::vector<std::vector<bool> > &
   get_refinement_edge_boundary_indices () const DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated The function is_boundary_index() now returns false if
-   * no boundary values are set.
+   * @deprecated The function is_boundary_index() now returns false if no
+   * boundary values are set.
    *
    * Return if boundary_indices need to be set or not.
    */
@@ -156,8 +152,8 @@ private:
   std::vector<std::set<types::global_dof_index> > boundary_indices;
 
   /**
-   * The degrees of freedom on the refinement edge between a level and
-   * coarser cells.
+   * The degrees of freedom on the refinement edge between a level and coarser
+   * cells.
    */
   std::vector<IndexSet> refinement_edge_indices;
 
index ae089e95d78e9e2818220a17fcd1a88396afeb8f..b0970bc9099ec8a0e1c464fc8adb7fb203ed27fd 100644 (file)
@@ -40,21 +40,22 @@ namespace internal
 
 
 /**
- * @deprecated All functionality of this class has been moved to
- * DoFHandler. Thus, this class is only a wrapper left in the library
- * for compatibility reasons.
+ * @deprecated All functionality of this class has been moved to DoFHandler.
+ * Thus, this class is only a wrapper left in the library for compatibility
+ * reasons.
  *
- * This class manages degrees of freedom for a multilevel hierarchy of
- * grids. It does mostly the same as does the @p DoDHandler class,
- * but it uses a separate enumeration of the degrees of freedom on
- * each level. For example, a vertex has several DoF numbers, one for
- * each level of the triangulation on which it exists.
+ * This class manages degrees of freedom for a multilevel hierarchy of grids.
+ * It does mostly the same as does the @p DoDHandler class, but it uses a
+ * separate enumeration of the degrees of freedom on each level. For example,
+ * a vertex has several DoF numbers, one for each level of the triangulation
+ * on which it exists.
  *
- * @todo This class has not yet been implemented for the use in the codimension
- * one case (<tt>spacedim != dim </tt>).
+ * @todo This class has not yet been implemented for the use in the
+ * codimension one case (<tt>spacedim != dim </tt>).
  *
  * @ingroup dofs
- * @author Wolfgang Bangerth, 1998, 1999 Markus Bürg, Timo Heister, Guido Kanschat, 2012
+ * @author Wolfgang Bangerth, 1998, 1999 Markus Bürg, Timo Heister, Guido
+ * Kanschat, 2012
  */
 template <int dim, int spacedim=dim>
 class MGDoFHandler : public DoFHandler<dim,spacedim>
@@ -81,23 +82,21 @@ public:
   typedef typename IteratorSelector::active_face_iterator active_face_iterator;
 
   /**
-   * Make the dimension and the space_dimension available
-   * in function templates.
+   * Make the dimension and the space_dimension available in function
+   * templates.
    */
   static const unsigned int dimension = dim;
 
   static const unsigned int space_dimension = spacedim;
 
   /**
-   * Default constructor, which
-   * will require a call to
-   * initialize() later to set the Triangulation.
+   * Default constructor, which will require a call to initialize() later to
+   * set the Triangulation.
    */
   MGDoFHandler ();
 
   /**
-   * Constructor. Take @p tria as
-   * the triangulation to work on.
+   * Constructor. Take @p tria as the triangulation to work on.
    */
   MGDoFHandler (const Triangulation<dim, spacedim> &tria);
 
@@ -107,46 +106,33 @@ public:
   virtual ~MGDoFHandler ();
 
   /**
-   * Go through the triangulation
-   * and distribute the degrees of
-   * freedoms needed for the given
-   * finite element according to
-   * the given distribution
-   * method. We first call the
-   * DoFHandler's function
-   * and then distribute the
+   * Go through the triangulation and distribute the degrees of freedoms
+   * needed for the given finite element according to the given distribution
+   * method. We first call the DoFHandler's function and then distribute the
    * levelwise numbers.
    *
-   * A copy of the transferred
-   * finite element is stored.
+   * A copy of the transferred finite element is stored.
    */
   virtual void distribute_dofs (const FiniteElement<dim,spacedim> &);
 
   /**
-   *  @name Cell iterator functions
+   * @name Cell iterator functions
    */
   /*@{*/
   /**
-   * Iterator to the first used
-   * cell on level @p level.
+   * Iterator to the first used cell on level @p level.
    */
   cell_iterator        begin       (const unsigned int level = 0) const;
 
   /**
-   * Iterator past the end; this
-   * iterator serves for
-   * comparisons of iterators with
-   * past-the-end or
-   * before-the-beginning states.
+   * Iterator past the end; this iterator serves for comparisons of iterators
+   * with past-the-end or before-the-beginning states.
    */
   cell_iterator        end () const;
 
   /**
-   * Return an iterator which is
-   * the first iterator not on
-   * level. If @p level is the
-   * last level, then this returns
-   * <tt>end()</tt>.
+   * Return an iterator which is the first iterator not on level. If @p level
+   * is the last level, then this returns <tt>end()</tt>.
    */
   cell_iterator        end (const unsigned int level) const;
 
index d959a3e82757db0b78985248e750523dd750997f..56e4b05f0ead7f534a5b7d1617e4d24979978493 100644 (file)
@@ -40,8 +40,8 @@ namespace internal
 
 
     /**
-     * Iterators for MGDofHandler in one dimension. See the @ref Iterators module
-     * for more information.
+     * Iterators for MGDofHandler in one dimension. See the @ref Iterators
+     * module for more information.
      */
     template <int spacedim>
     class Iterators<1,spacedim>
@@ -74,8 +74,8 @@ namespace internal
 
 
     /**
-     * Iterators for MGDofHandler in two dimensions. See the @ref Iterators module
-     * for more information.
+     * Iterators for MGDofHandler in two dimensions. See the @ref Iterators
+     * module for more information.
      */
     template <int spacedim>
     class Iterators<2,spacedim>
@@ -108,8 +108,8 @@ namespace internal
 
 
     /**
-     * Iterators for MGDofHandler in three dimensions. See the @ref Iterators module
-     * for more information.
+     * Iterators for MGDofHandler in three dimensions. See the @ref Iterators
+     * module for more information.
      */
     template <int spacedim>
     class Iterators<3,spacedim>
index f70bf5b6c35836602a6cbadc70ae96b0a0ab66a8..ed2d3589bf71eb1dccc50de3189895e858d2bf79 100644 (file)
@@ -44,23 +44,19 @@ namespace mg
   {
   public:
     /**
-     * Default constructor for an
-     * empty object.
+     * Default constructor for an empty object.
      */
     Matrix();
 
     /**
-     * Constructor setting up
-     * pointers to the matrices in
-     * <tt>M</tt> by calling initialize().
+     * Constructor setting up pointers to the matrices in <tt>M</tt> by
+     * calling initialize().
      */
     template <class MATRIX>
     Matrix(const MGLevelObject<MATRIX> &M);
 
     /**
-     * Initialize the object such
-     * that the level
-     * multiplication uses the
+     * Initialize the object such that the level multiplication uses the
      * matrices in <tt>M</tt>
      */
     template <class MATRIX>
@@ -117,13 +113,12 @@ private:
 
 
 /**
- * Multilevel matrix selecting from block matrices. This class
- * implements the interface defined by MGMatrixBase.  The
- * template parameter @p MATRIX should be a block matrix class like
- * BlockSparseMatrix or @p BlockSparseMatrixEZ. Then, this
- * class stores a pointer to a MGLevelObject of this matrix
- * class. In each @p vmult, the block selected on initialization will
- * be multiplied with the vector provided.
+ * Multilevel matrix selecting from block matrices. This class implements the
+ * interface defined by MGMatrixBase.  The template parameter @p MATRIX should
+ * be a block matrix class like BlockSparseMatrix or @p BlockSparseMatrixEZ.
+ * Then, this class stores a pointer to a MGLevelObject of this matrix class.
+ * In each @p vmult, the block selected on initialization will be multiplied
+ * with the vector provided.
  *
  * @author Guido Kanschat, 2002
  */
@@ -132,61 +127,48 @@ class MGMatrixSelect : public MGMatrixBase<Vector<number> >
 {
 public:
   /**
-   * Constructor. @p row and
-   * @p col are the coordinate of
-   * the selected block. The other
-   * argument is handed over to the
-   * @p SmartPointer constructor.
+   * Constructor. @p row and @p col are the coordinate of the selected block.
+   * The other argument is handed over to the @p SmartPointer constructor.
    */
   MGMatrixSelect (const unsigned int row = 0,
                   const unsigned int col = 0,
                   MGLevelObject<MATRIX> *matrix = 0);
 
   /**
-   * Set the matrix object to be
-   * used. The matrix object must
-   * exist longer as the
-   * @p MGMatrix object, since
-   * only a pointer is stored.
+   * Set the matrix object to be used. The matrix object must exist longer as
+   * the @p MGMatrix object, since only a pointer is stored.
    */
   void set_matrix (MGLevelObject<MATRIX> *M);
 
   /**
-   * Select the block for
-   * multiplication.
+   * Select the block for multiplication.
    */
   void select_block (const unsigned int row,
                      const unsigned int col);
 
   /**
-   * Matrix-vector-multiplication on
-   * a certain level.
+   * Matrix-vector-multiplication on a certain level.
    */
   virtual void vmult (const unsigned int level,
                       Vector<number> &dst,
                       const Vector<number> &src) const;
 
   /**
-   * Adding matrix-vector-multiplication on
-   * a certain level.
+   * Adding matrix-vector-multiplication on a certain level.
    */
   virtual void vmult_add (const unsigned int level,
                           Vector<number> &dst,
                           const Vector<number> &src) const;
 
   /**
-   * Transpose
-   * matrix-vector-multiplication on
-   * a certain level.
+   * Transpose matrix-vector-multiplication on a certain level.
    */
   virtual void Tvmult (const unsigned int level,
                        Vector<number> &dst,
                        const Vector<number> &src) const;
 
   /**
-   * Adding transpose
-   * matrix-vector-multiplication on
-   * a certain level.
+   * Adding transpose matrix-vector-multiplication on a certain level.
    */
   virtual void Tvmult_add (const unsigned int level,
                            Vector<number> &dst,
index d2f0c377f27633734d607ec2efc22d38cc96bbd9..1622faa3b788fd6db10ea08af195329cff1f3990 100644 (file)
@@ -35,10 +35,10 @@ DEAL_II_NAMESPACE_OPEN
 /*@{*/
 
 /**
- * A base class for smoother handling information on smoothing.
- * While not adding to the abstract interface in MGSmootherBase, this
- * class stores information on the number and type of smoothing steps,
- * which in turn can be used by a derived class.
+ * A base class for smoother handling information on smoothing. While not
+ * adding to the abstract interface in MGSmootherBase, this class stores
+ * information on the number and type of smoothing steps, which in turn can be
+ * used by a derived class.
  *
  * @author Guido Kanschat 2009
  */
@@ -47,10 +47,8 @@ class MGSmoother : public MGSmootherBase<VECTOR>
 {
 public:
   /**
-   * Constructor. Sets smoothing
-   * parameters and creates a
-   * private GrowingVectorMemory
-   * object to be used to retrieve vectors.
+   * Constructor. Sets smoothing parameters and creates a private
+   * GrowingVectorMemory object to be used to retrieve vectors.
    */
   MGSmoother(const unsigned int steps = 1,
              const bool variable = false,
@@ -58,15 +56,10 @@ public:
              const bool transpose = false);
 
   /**
-   * @deprecated Since
-   * GrowingVectorMemory now uses a
-   * joint memory pool, it is
-   * recommended to use the
-   * constructor without the memory
-   * object.
+   * @deprecated Since GrowingVectorMemory now uses a joint memory pool, it is
+   * recommended to use the constructor without the memory object.
    *
-   * Constructor. Sets memory and
-   * smoothing parameters.
+   * Constructor. Sets memory and smoothing parameters.
    */
   MGSmoother(VectorMemory<VECTOR> &mem,
              const unsigned int steps = 1,
@@ -75,85 +68,65 @@ public:
              const bool transpose = false) DEAL_II_DEPRECATED;
 
   /**
-   * Modify the number of smoothing
-   * steps on finest level.
+   * Modify the number of smoothing steps on finest level.
    */
   void set_steps (const unsigned int);
 
   /**
-   * Switch on/off variable
-   * smoothing.
+   * Switch on/off variable smoothing.
    */
   void set_variable (const bool);
 
   /**
-   * Switch on/off symmetric
-   * smoothing.
+   * Switch on/off symmetric smoothing.
    */
   void set_symmetric (const bool);
 
   /**
-   * Switch on/off transposed
-   * smoothing. The effect is
-   * overriden by set_symmetric().
+   * Switch on/off transposed smoothing. The effect is overriden by
+   * set_symmetric().
    */
   void set_transpose (const bool);
 
   /**
-   * Set @p debug to a nonzero value
-   * to get debug information
-   * logged to @p deallog. Increase
-   * to get more information
+   * Set @p debug to a nonzero value to get debug information logged to @p
+   * deallog. Increase to get more information
    */
   void set_debug (const unsigned int level);
 
 private:
   /**
-   * The memory object to be used
-   * if none is given to the
-   * constructor.
+   * The memory object to be used if none is given to the constructor.
    */
   GrowingVectorMemory<VECTOR> my_memory;
 
 protected:
   /**
-   * Number of smoothing steps on
-   * the finest level. If no
-   * #variable smoothing is chosen,
-   * this is the number of steps on
-   * all levels.
+   * Number of smoothing steps on the finest level. If no #variable smoothing
+   * is chosen, this is the number of steps on all levels.
    */
   unsigned int steps;
 
   /**
-   * Variable smoothing: double the
-   * number of smoothing steps
-   * whenever going to the next
-   * coarser level
+   * Variable smoothing: double the number of smoothing steps whenever going
+   * to the next coarser level
    */
   bool variable;
 
   /**
-   * Symmetric smoothing: in the
-   * smoothing iteration, alternate
-   * between the relaxation method
-   * and its transpose.
+   * Symmetric smoothing: in the smoothing iteration, alternate between the
+   * relaxation method and its transpose.
    */
   bool symmetric;
 
   /**
-   * Use the transpose of the
-   * relaxation method instead of
-   * the method itself. This has no
-   * effect if #symmetric smoothing
-   * is chosen.
+   * Use the transpose of the relaxation method instead of the method itself.
+   * This has no effect if #symmetric smoothing is chosen.
    */
   bool transpose;
 
   /**
-   * Output debugging information
-   * to @p deallog if this is
-   * nonzero.
+   * Output debugging information to @p deallog if this is nonzero.
    */
   unsigned int debug;
 
@@ -165,9 +138,9 @@ protected:
 
 
 /**
- * Smoother doing nothing. This class is not useful for many applications other
- * than for testing some multigrid procedures. Also some applications might
- * get convergence without smoothing and then this class brings you the
+ * Smoother doing nothing. This class is not useful for many applications
+ * other than for testing some multigrid procedures. Also some applications
+ * might get convergence without smoothing and then this class brings you the
  * cheapest possible multigrid.
  *
  * @author Guido Kanschat, 1999, 2002
@@ -177,14 +150,9 @@ class MGSmootherIdentity : public MGSmootherBase<VECTOR>
 {
 public:
   /**
-   * Implementation of the
-   * interface for @p Multigrid.
-   * This function does nothing,
-   * which by comparison with the
-   * definition of this function
-   * means that the the smoothing
-   * operator equals the null
-   * operator.
+   * Implementation of the interface for @p Multigrid. This function does
+   * nothing, which by comparison with the definition of this function means
+   * that the the smoothing operator equals the null operator.
    */
   virtual void smooth (const unsigned int level,
                        VECTOR            &u,
@@ -206,25 +174,24 @@ namespace mg
    * performing one step of the smoothing scheme.
    *
    * This class performs smoothing on each level. The operation can be
-   * controlled by several parameters. First, the relaxation parameter
-   * @p omega is used in the underlying relaxation method. @p steps is
-   * the number of relaxation steps on the finest level (on all levels
-   * if @p variable is off). If @p variable is @p true, the number of
-   * smoothing steps is doubled on each coarser level. This results in a
-   * method having the complexity of the W-cycle, but saving grid
-   * transfers. This is the method proposed by Bramble at al.
+   * controlled by several parameters. First, the relaxation parameter @p
+   * omega is used in the underlying relaxation method. @p steps is the number
+   * of relaxation steps on the finest level (on all levels if @p variable is
+   * off). If @p variable is @p true, the number of smoothing steps is doubled
+   * on each coarser level. This results in a method having the complexity of
+   * the W-cycle, but saving grid transfers. This is the method proposed by
+   * Bramble at al.
    *
-   * The option @p symmetric switches on alternating between the
-   * smoother and its transpose in each step as proposed by Bramble.
+   * The option @p symmetric switches on alternating between the smoother and
+   * its transpose in each step as proposed by Bramble.
    *
-   * @p transpose uses the transposed smoothing operation using
-   * <tt>Tstep</tt> instead of the regular <tt>step</tt> of the
-   * relaxation scheme.
+   * @p transpose uses the transposed smoothing operation using <tt>Tstep</tt>
+   * instead of the regular <tt>step</tt> of the relaxation scheme.
    *
-   * If you are using block matrices, the second @p initialize function
-   * offers the possibility to extract a single block for smoothing. In
-   * this case, the multigrid method must be used only with the vector
-   * associated to that single block.
+   * If you are using block matrices, the second @p initialize function offers
+   * the possibility to extract a single block for smoothing. In this case,
+   * the multigrid method must be used only with the vector associated to that
+   * single block.
    *
    * @author Guido Kanschat,
    * @date 2003, 2009, 2010
@@ -234,8 +201,7 @@ namespace mg
   {
   public:
     /**
-     * Constructor. Sets memory and
-     * smoothing parameters.
+     * Constructor. Sets memory and smoothing parameters.
      */
     SmootherRelaxation(const unsigned int steps = 1,
                        const bool variable = false,
@@ -243,51 +209,32 @@ namespace mg
                        const bool transpose = false);
 
     /**
-     * Initialize for matrices. This
-     * function initializes the
-     * smoothing operator with the
-     * same smoother for each level.
+     * Initialize for matrices. This function initializes the smoothing
+     * operator with the same smoother for each level.
      *
-     * @p additional_data is an
-     * object of type
-     * @p RELAX::AdditionalData and
-     * is handed to the
-     * initialization function of the
-     * relaxation method.
+     * @p additional_data is an object of type @p RELAX::AdditionalData and is
+     * handed to the initialization function of the relaxation method.
      */
     template <class MATRIX2>
     void initialize (const MGLevelObject<MATRIX2> &matrices,
                      const typename RELAX::AdditionalData &additional_data = typename RELAX::AdditionalData());
 
     /**
-     * Initialize matrices and
-     * additional data for each
-     * level.
+     * Initialize matrices and additional data for each level.
      *
-     * If minimal or maximal level of
-     * the two objects differ, the
-     * greatest common range is
-     * utilized. This way, smoothing
-     * can be restricted to certain
-     * levels even if the matrix was
-     * generated for all levels.
+     * If minimal or maximal level of the two objects differ, the greatest
+     * common range is utilized. This way, smoothing can be restricted to
+     * certain levels even if the matrix was generated for all levels.
      */
     template <class MATRIX2, class DATA>
     void initialize (const MGLevelObject<MATRIX2> &matrices,
                      const MGLevelObject<DATA> &additional_data);
     /**
-     * Initialize for matrix
-     * blocks. This function
-     * initializes the smoothing
-     * operator with the same
-     * smoother for each level.
+     * Initialize for matrix blocks. This function initializes the smoothing
+     * operator with the same smoother for each level.
      *
-     * @p additional_data is an
-     * object of type
-     * @p RELAX::AdditionalData and
-     * is handed to the
-     * initialization function of the
-     * relaxation method.
+     * @p additional_data is an object of type @p RELAX::AdditionalData and is
+     * handed to the initialization function of the relaxation method.
      */
 //     template <class MATRIX2>
 //     void initialize (const MGLevelObject<MatrixBlock<MATRIX2> >& matrices,
@@ -323,33 +270,32 @@ namespace mg
  * performing one step of the smoothing scheme.
  *
  * This class performs smoothing on each level. The operation can be
- * controlled by several parameters. First, the relaxation parameter
- * @p omega is used in the underlying relaxation method. @p steps is
- * the number of relaxation steps on the finest level (on all levels
- * if @p variable is off). If @p variable is @p true, the number of
- * smoothing steps is doubled on each coarser level. This results in a
- * method having the complexity of the W-cycle, but saving grid
- * transfers. This is the method proposed by Bramble at al.
+ * controlled by several parameters. First, the relaxation parameter @p omega
+ * is used in the underlying relaxation method. @p steps is the number of
+ * relaxation steps on the finest level (on all levels if @p variable is off).
+ * If @p variable is @p true, the number of smoothing steps is doubled on each
+ * coarser level. This results in a method having the complexity of the
+ * W-cycle, but saving grid transfers. This is the method proposed by Bramble
+ * at al.
  *
- * The option @p symmetric switches on alternating between the
- * smoother and its transpose in each step as proposed by Bramble.
+ * The option @p symmetric switches on alternating between the smoother and
+ * its transpose in each step as proposed by Bramble.
  *
- * @p transpose uses the transposed smoothing operation using
- * <tt>Tstep</tt> instead of the regular <tt>step</tt> of the
- * relaxation scheme.
+ * @p transpose uses the transposed smoothing operation using <tt>Tstep</tt>
+ * instead of the regular <tt>step</tt> of the relaxation scheme.
  *
- * If you are using block matrices, the second @p initialize function
- * offers the possibility to extract a single block for smoothing. In
- * this case, the multigrid method must be used only with the vector
- * associated to that single block.
+ * If you are using block matrices, the second @p initialize function offers
+ * the possibility to extract a single block for smoothing. In this case, the
+ * multigrid method must be used only with the vector associated to that
+ * single block.
  *
  * The library contains instantiation for <tt>SparseMatrix<.></tt> and
- * <tt>Vector<.></tt>, where the template arguments are all combinations of
- * @p float and @p double. Additional instantiations may be created
- * by including the file mg_smoother.templates.h.
+ * <tt>Vector<.></tt>, where the template arguments are all combinations of @p
+ * float and @p double. Additional instantiations may be created by including
+ * the file mg_smoother.templates.h.
  *
- * @note If '--enable-mgcompatibility' was used on configuring
- * deal.II, this class behaves like MGSmootherPrecondition.
+ * @note If '--enable-mgcompatibility' was used on configuring deal.II, this
+ * class behaves like MGSmootherPrecondition.
  *
  * @author Guido Kanschat, 2003
  */
@@ -366,11 +312,9 @@ public:
                        const bool transpose = false);
 
   /**
-   * Constructor. Sets memory and
-   * smoothing parameters.
+   * Constructor. Sets memory and smoothing parameters.
    *
-   * @deprecated Use the constructor without the vector memory
-   * object
+   * @deprecated Use the constructor without the vector memory object
    */
   MGSmootherRelaxation(VectorMemory<VECTOR> &mem,
                        const unsigned int steps = 1,
@@ -379,62 +323,37 @@ public:
                        const bool transpose = false) DEAL_II_DEPRECATED;
 
   /**
-   * Initialize for matrices. This
-   * function stores pointers to
-   * the level matrices and
-   * initializes the smoothing
-   * operator with the same smoother
+   * Initialize for matrices. This function stores pointers to the level
+   * matrices and initializes the smoothing operator with the same smoother
    * for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p RELAX::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p RELAX::AdditionalData and is
+   * handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
                    const typename RELAX::AdditionalData &additional_data = typename RELAX::AdditionalData());
 
   /**
-   * Initialize for matrices. This
-   * function stores pointers to
-   * the level matrices and
-   * initializes the smoothing
-   * operator with the according
+   * Initialize for matrices. This function stores pointers to the level
+   * matrices and initializes the smoothing operator with the according
    * smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p RELAX::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p RELAX::AdditionalData and is
+   * handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
                    const MGLevelObject<DATA> &additional_data);
 
   /**
-   * Initialize for single blocks
-   * of matrices. Of this block
-   * matrix, the block indicated by
-   * @p block_row and
-   * @p block_col is selected on
-   * each level.  This function
-   * stores pointers to the level
-   * matrices and initializes the
-   * smoothing operator with the
-   * same smoother for each
-   * level.
+   * Initialize for single blocks of matrices. Of this block matrix, the block
+   * indicated by @p block_row and @p block_col is selected on each level.
+   * This function stores pointers to the level matrices and initializes the
+   * smoothing operator with the same smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p RELAX::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p RELAX::AdditionalData and is
+   * handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
@@ -443,24 +362,13 @@ public:
                    const unsigned int block_col);
 
   /**
-   * Initialize for single blocks
-   * of matrices. Of this block
-   * matrix, the block indicated by
-   * @p block_row and
-   * @p block_col is selected on
-   * each level.  This function
-   * stores pointers to the level
-   * matrices and initializes the
-   * smoothing operator with the
-   * according smoother for each
-   * level.
+   * Initialize for single blocks of matrices. Of this block matrix, the block
+   * indicated by @p block_row and @p block_col is selected on each level.
+   * This function stores pointers to the level matrices and initializes the
+   * smoothing operator with the according smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p RELAX::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p RELAX::AdditionalData and is
+   * handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
@@ -481,8 +389,7 @@ public:
                        const VECTOR      &rhs) const;
 
   /**
-   * Object containing relaxation
-   * methods.
+   * Object containing relaxation methods.
    */
   MGLevelObject<RELAX> smoothers;
 
@@ -506,30 +413,29 @@ private:
  * Smoother using preconditioner classes.
  *
  * This class performs smoothing on each level. The operation can be
- * controlled by several parameters. First, the relaxation parameter
- * @p omega is used in the underlying relaxation method. @p steps is
- * the number of relaxation steps on the finest level (on all levels
- * if @p variable is off). If @p variable is @p true, the number of
- * smoothing steps is doubled on each coarser level. This results in a
- * method having the complexity of the W-cycle, but saving grid
- * transfers. This is the method proposed by Bramble at al.
+ * controlled by several parameters. First, the relaxation parameter @p omega
+ * is used in the underlying relaxation method. @p steps is the number of
+ * relaxation steps on the finest level (on all levels if @p variable is off).
+ * If @p variable is @p true, the number of smoothing steps is doubled on each
+ * coarser level. This results in a method having the complexity of the
+ * W-cycle, but saving grid transfers. This is the method proposed by Bramble
+ * at al.
  *
- * The option @p symmetric switches on alternating between the
- * smoother and its transpose in each step as proposed by Bramble.
+ * The option @p symmetric switches on alternating between the smoother and
+ * its transpose in each step as proposed by Bramble.
  *
- * @p transpose uses the transposed smoothing operation using
- * <tt>Tvmult</tt> instead of the regular <tt>vmult</tt> of the
- * relaxation scheme.
+ * @p transpose uses the transposed smoothing operation using <tt>Tvmult</tt>
+ * instead of the regular <tt>vmult</tt> of the relaxation scheme.
  *
- * If you are using block matrices, the second @p initialize function
- * offers the possibility to extract a single block for smoothing. In
- * this case, the multigrid method must be used only with the vector
- * associated to that single block.
+ * If you are using block matrices, the second @p initialize function offers
+ * the possibility to extract a single block for smoothing. In this case, the
+ * multigrid method must be used only with the vector associated to that
+ * single block.
  *
  * The library contains instantiation for <tt>SparseMatrix<.></tt> and
- * <tt>Vector<.></tt>, where the template arguments are all combinations of
- * @p float and @p double. Additional instantiations may be created
- * by including the file mg_smoother.templates.h.
+ * <tt>Vector<.></tt>, where the template arguments are all combinations of @p
+ * float and @p double. Additional instantiations may be created by including
+ * the file mg_smoother.templates.h.
  *
  * @author Guido Kanschat, 2009
  */
@@ -546,11 +452,9 @@ public:
                          const bool transpose = false);
 
   /**
-   * Constructor. Sets memory and
-   * smoothing parameters.
+   * Constructor. Sets memory and smoothing parameters.
    *
-   * @deprecated Use the constructor without the vector memory
-   * object
+   * @deprecated Use the constructor without the vector memory object
    */
   MGSmootherPrecondition(VectorMemory<VECTOR> &mem,
                          const unsigned int steps = 1,
@@ -559,62 +463,37 @@ public:
                          const bool transpose = false) DEAL_II_DEPRECATED;
 
   /**
-   * Initialize for matrices. This
-   * function stores pointers to
-   * the level matrices and
-   * initializes the smoothing
-   * operator with the same smoother
+   * Initialize for matrices. This function stores pointers to the level
+   * matrices and initializes the smoothing operator with the same smoother
    * for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p PRECONDITIONER::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+   * and is handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
                    const typename PRECONDITIONER::AdditionalData &additional_data = typename PRECONDITIONER::AdditionalData());
 
   /**
-   * Initialize for matrices. This
-   * function stores pointers to
-   * the level matrices and
-   * initializes the smoothing
-   * operator with the according
+   * Initialize for matrices. This function stores pointers to the level
+   * matrices and initializes the smoothing operator with the according
    * smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p PRECONDITIONER::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+   * and is handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
                    const MGLevelObject<DATA> &additional_data);
 
   /**
-   * Initialize for single blocks
-   * of matrices. Of this block
-   * matrix, the block indicated by
-   * @p block_row and
-   * @p block_col is selected on
-   * each level.  This function
-   * stores pointers to the level
-   * matrices and initializes the
-   * smoothing operator with the
-   * same smoother for each
-   * level.
+   * Initialize for single blocks of matrices. Of this block matrix, the block
+   * indicated by @p block_row and @p block_col is selected on each level.
+   * This function stores pointers to the level matrices and initializes the
+   * smoothing operator with the same smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p PRECONDITIONER::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+   * and is handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
@@ -623,24 +502,13 @@ public:
                    const unsigned int block_col);
 
   /**
-   * Initialize for single blocks
-   * of matrices. Of this block
-   * matrix, the block indicated by
-   * @p block_row and
-   * @p block_col is selected on
-   * each level.  This function
-   * stores pointers to the level
-   * matrices and initializes the
-   * smoothing operator with the
-   * according smoother for each
-   * level.
+   * Initialize for single blocks of matrices. Of this block matrix, the block
+   * indicated by @p block_row and @p block_col is selected on each level.
+   * This function stores pointers to the level matrices and initializes the
+   * smoothing operator with the according smoother for each level.
    *
-   * @p additional_data is an
-   * object of type
-   * @p PRECONDITIONER::AdditionalData and
-   * is handed to the
-   * initialization function of the
-   * relaxation method.
+   * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+   * and is handed to the initialization function of the relaxation method.
    */
   template <class MATRIX2, class DATA>
   void initialize (const MGLevelObject<MATRIX2> &matrices,
@@ -661,8 +529,7 @@ public:
                        const VECTOR      &rhs) const;
 
   /**
-   * Object containing relaxation
-   * methods.
+   * Object containing relaxation methods.
    */
   MGLevelObject<PRECONDITIONER> smoothers;
 
index acf7f0b3ab4b0b240799f8cae513a18721b546c9..097af48ce236f3a0ddde2b6aeb8900ea04958860 100644 (file)
@@ -40,11 +40,10 @@ template <typename number> class BlockSparseMatrix;
 /* @{ */
 
 /**
- * This is a collection of functions operating on, and manipulating
- * the numbers of degrees of freedom in a multilevel triangulation. It
- * is similar in purpose and function to the @p DoFTools class, but
- * operates on levels of DoFHandler
- * objects. See there and the documentation of the member functions
+ * This is a collection of functions operating on, and manipulating the
+ * numbers of degrees of freedom in a multilevel triangulation. It is similar
+ * in purpose and function to the @p DoFTools class, but operates on levels of
+ * DoFHandler objects. See there and the documentation of the member functions
  * for more information.
  *
  * @author Wolfgang Bangerth, Guido Kanschat, 1999 - 2005, 2012
@@ -52,8 +51,7 @@ template <typename number> class BlockSparseMatrix;
 namespace MGTools
 {
   /**
-   * Compute row length vector for
-   * multilevel methods.
+   * Compute row length vector for multilevel methods.
    */
   template <int dim, int spacedim>
   void
@@ -63,10 +61,8 @@ namespace MGTools
                             const DoFTools::Coupling flux_couplings = DoFTools::none);
 
   /**
-   * Compute row length vector for
-   * multilevel methods with
-   * optimization for block
-   * couplings.
+   * Compute row length vector for multilevel methods with optimization for
+   * block couplings.
    */
   template <int dim, int spacedim>
   void
@@ -77,18 +73,13 @@ namespace MGTools
                             const Table<2,DoFTools::Coupling> &flux_couplings);
 
   /**
-   * Write the sparsity structure
-   * of the matrix belonging to the
-   * specified @p level. The sparsity pattern
-   * is not compressed, so before
-   * creating the actual matrix
-   * you have to compress the
-   * matrix yourself, using
+   * Write the sparsity structure of the matrix belonging to the specified @p
+   * level. The sparsity pattern is not compressed, so before creating the
+   * actual matrix you have to compress the matrix yourself, using
    * <tt>SparseMatrixStruct::compress()</tt>.
    *
-   * There is no need to consider
-   * hanging nodes here, since only
-   * one level is considered.
+   * There is no need to consider hanging nodes here, since only one level is
+   * considered.
    */
   template <class DH, class SparsityPattern>
   void
@@ -97,10 +88,8 @@ namespace MGTools
                          const unsigned int       level);
 
   /**
-   * Make a sparsity pattern including fluxes
-   * of discontinuous Galerkin methods.
-   * @ref make_sparsity_pattern
-   * @ref DoFTools
+   * Make a sparsity pattern including fluxes of discontinuous Galerkin
+   * methods. @ref make_sparsity_pattern @ref DoFTools
    */
   template <int dim, class SparsityPattern, int spacedim>
   void
@@ -109,12 +98,8 @@ namespace MGTools
                               const unsigned int       level);
 
   /**
-   * Create sparsity pattern for
-   * the fluxes at refinement
-   * edges. The matrix maps a
-   * function of the fine level
-   * space @p level to the coarser
-   * space.
+   * Create sparsity pattern for the fluxes at refinement edges. The matrix
+   * maps a function of the fine level space @p level to the coarser space.
    *
    * make_flux_sparsity_pattern()
    */
@@ -124,21 +109,13 @@ namespace MGTools
                                    SparsityPattern         &sparsity,
                                    const unsigned int       level);
   /**
-   * This function does the same as
-   * the other with the same name,
-   * but it gets two additional
-   * coefficient matrices. A matrix
-   * entry will only be generated
-   * for two basis functions, if
-   * there is a non-zero entry
-   * linking their associated
-   * components in the coefficient
-   * matrix.
+   * This function does the same as the other with the same name, but it gets
+   * two additional coefficient matrices. A matrix entry will only be
+   * generated for two basis functions, if there is a non-zero entry linking
+   * their associated components in the coefficient matrix.
    *
-   * There is one matrix for
-   * couplings in a cell and one
-   * for the couplings occurring in
-   * fluxes.
+   * There is one matrix for couplings in a cell and one for the couplings
+   * occurring in fluxes.
    */
   template <int dim, class SparsityPattern, int spacedim>
   void
@@ -149,14 +126,10 @@ namespace MGTools
                               const Table<2,DoFTools::Coupling> &flux_mask);
 
   /**
-   * Create sparsity pattern for
-   * the fluxes at refinement
-   * edges. The matrix maps a
-   * function of the fine level
-   * space @p level to the coarser
-   * space. This is the version
-   * restricting the pattern to the
-   * elements actually needed.
+   * Create sparsity pattern for the fluxes at refinement edges. The matrix
+   * maps a function of the fine level space @p level to the coarser space.
+   * This is the version restricting the pattern to the elements actually
+   * needed.
    *
    * make_flux_sparsity_pattern()
    */
@@ -168,14 +141,10 @@ namespace MGTools
                                    const Table<2,DoFTools::Coupling> &flux_mask);
 
   /**
-   * Count the dofs block-wise
-   * on each level.
+   * Count the dofs block-wise on each level.
    *
-   * Result is a vector containing
-   * for each level a vector
-   * containing the number of dofs
-   * for each block (access is
-   * <tt>result[level][block]</tt>).
+   * Result is a vector containing for each level a vector containing the
+   * number of dofs for each block (access is <tt>result[level][block]</tt>).
    */
   template <class DH>
   void
@@ -184,13 +153,10 @@ namespace MGTools
                         std::vector<unsigned int>  target_block = std::vector<unsigned int>());
 
   /**
-   * Count the dofs component-wise
-   * on each level.
+   * Count the dofs component-wise on each level.
    *
-   * Result is a vector containing
-   * for each level a vector
-   * containing the number of dofs
-   * for each component (access is
+   * Result is a vector containing for each level a vector containing the
+   * number of dofs for each component (access is
    * <tt>result[level][component]</tt>).
    */
   template <int dim, int spacedim>
@@ -201,9 +167,8 @@ namespace MGTools
                             std::vector<unsigned int> target_component = std::vector<unsigned int>());
 
   /**
-   * @deprecated Wrapper for the
-   * other function with same name,
-   * introduced for compatibility.
+   * @deprecated Wrapper for the other function with same name, introduced for
+   * compatibility.
    */
   template <int dim, int spacedim>
   void
@@ -235,8 +200,7 @@ namespace MGTools
                       const ComponentMask                   &component_mask = ComponentMask());
 
   /**
-   * The same function as above, but return
-   * an IndexSet rather than a
+   * The same function as above, but return an IndexSet rather than a
    * std::set<unsigned int> on each level.
    */
   template <int dim, int spacedim>
@@ -266,10 +230,9 @@ namespace MGTools
                          const bool preserve_symmetry) DEAL_II_DEPRECATED;
 
   /**
-   * For each level in a multigrid hierarchy, produce an IndexSet
-   * that indicates which of the degrees of freedom are along
-   * interfaces of this level to cells that only exist on coarser
-   * levels.
+   * For each level in a multigrid hierarchy, produce an IndexSet that
+   * indicates which of the degrees of freedom are along interfaces of this
+   * level to cells that only exist on coarser levels.
    */
   template <int dim, int spacedim>
   void
@@ -277,7 +240,8 @@ namespace MGTools
                                 std::vector<IndexSet>  &interface_dofs);
 
   /**
-   * As above but with a deprecated data structure. This makes one additional copy.
+   * As above but with a deprecated data structure. This makes one additional
+   * copy.
    */
   template <int dim, int spacedim>
   void
index 0d62a7b00223324d385daa82fdf8aa8d72dabe1c..599174f9e062a6c9aa1c765440f3e2461aca282f 100644 (file)
@@ -98,11 +98,11 @@ namespace internal
  * Implementation of the MGTransferBase interface for which the transfer
  * operations are prebuilt upon construction of the object of this class as
  * matrices. This is the fast way, since it only needs to build the operation
- * once by looping over all cells and storing the result in a matrix for
- * each level, but requires additional memory.
+ * once by looping over all cells and storing the result in a matrix for each
+ * level, but requires additional memory.
  *
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
  *
  * @author Wolfgang Bangerth, Guido Kanschat
  * @date 1999, 2000, 2001, 2002, 2003, 2004, 2012
@@ -112,16 +112,13 @@ class MGTransferPrebuilt : public MGTransferBase<VECTOR>
 {
 public:
   /**
-   * Constructor without constraint
-   * matrices. Use this constructor
-   * only with discontinuous finite
-   * elements or with no local
-   * refinement.
+   * Constructor without constraint matrices. Use this constructor only with
+   * discontinuous finite elements or with no local refinement.
    */
   MGTransferPrebuilt ();
   /**
-   * Constructor with constraints. Equivalent to the default
-   * constructor followed by initialize_constraints().
+   * Constructor with constraints. Equivalent to the default constructor
+   * followed by initialize_constraints().
    */
   MGTransferPrebuilt (const ConstraintMatrix &constraints,
                       const MGConstrainedDoFs &mg_constrained_dofs);
@@ -142,8 +139,7 @@ public:
   void clear ();
 
   /**
-   * Actually build the prolongation
-   * matrices for each level.
+   * Actually build the prolongation matrices for each level.
    */
   template <int dim, int spacedim>
   void build_matrices (const DoFHandler<dim,spacedim> &mg_dof);
@@ -157,10 +153,8 @@ public:
                                  const VECTOR &src) const;
 
   /**
-   * Transfer from a vector on the
-   * global grid to vectors defined
-   * on each of the levels
-   * separately, i.a. an @p MGVector.
+   * Transfer from a vector on the global grid to vectors defined on each of
+   * the levels separately, i.a. an @p MGVector.
    */
   template <int dim, class InVector, int spacedim>
   void
@@ -169,16 +163,11 @@ public:
               const InVector &src) const;
 
   /**
-   * Transfer from multi-level vector to
-   * normal vector.
+   * Transfer from multi-level vector to normal vector.
    *
-   * Copies data from active
-   * portions of an MGVector into
-   * the respective positions of a
-   * <tt>Vector<number></tt>. In order to
-   * keep the result consistent,
-   * constrained degrees of freedom
-   * are set to zero.
+   * Copies data from active portions of an MGVector into the respective
+   * positions of a <tt>Vector<number></tt>. In order to keep the result
+   * consistent, constrained degrees of freedom are set to zero.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -187,12 +176,9 @@ public:
                 const MGLevelObject<VECTOR> &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -201,33 +187,18 @@ public:
                     const MGLevelObject<VECTOR> &src) const;
 
   /**
-   * If this object operates on
-   * BlockVector objects, we need
-   * to describe how the individual
-   * vector components are mapped
-   * to the blocks of a vector. For
-   * example, for a Stokes system,
-   * we have dim+1 vector
-   * components for velocity and
-   * pressure, but we may want to
-   * use block vectors with only
-   * two blocks for all velocities
-   * in one block, and the pressure
-   * variables in the other.
+   * If this object operates on BlockVector objects, we need to describe how
+   * the individual vector components are mapped to the blocks of a vector.
+   * For example, for a Stokes system, we have dim+1 vector components for
+   * velocity and pressure, but we may want to use block vectors with only two
+   * blocks for all velocities in one block, and the pressure variables in the
+   * other.
    *
-   * By default, if this function
-   * is not called, block vectors
-   * have as many blocks as the
-   * finite element has vector
-   * components. However, this can
-   * be changed by calling this
-   * function with an array that
-   * describes how vector
-   * components are to be grouped
-   * into blocks. The meaning of
-   * the argument is the same as
-   * the one given to the
-   * DoFTools::count_dofs_per_component
+   * By default, if this function is not called, block vectors have as many
+   * blocks as the finite element has vector components. However, this can be
+   * changed by calling this function with an array that describes how vector
+   * components are to be grouped into blocks. The meaning of the argument is
+   * the same as the one given to the DoFTools::count_dofs_per_component
    * function.
    */
   void
@@ -271,9 +242,9 @@ private:
   std::vector<std_cxx11::shared_ptr<typename internal::MatrixSelector<VECTOR>::Sparsity> >   prolongation_sparsities;
 
   /**
-   * The actual prolongation matrix.  column indices belong to the dof
-   * indices of the mother cell, i.e. the coarse level.  while row
-   * indices belong to the child cell, i.e. the fine level.
+   * The actual prolongation matrix.  column indices belong to the dof indices
+   * of the mother cell, i.e. the coarse level.  while row indices belong to
+   * the child cell, i.e. the fine level.
    */
   std::vector<std_cxx11::shared_ptr<typename internal::MatrixSelector<VECTOR>::Matrix> > prolongation_matrices;
 
@@ -281,17 +252,16 @@ private:
    * Mapping for the copy_to_mg() and copy_from_mg() functions. Here only
    * index pairs locally owned
    *
-   * The data is organized as follows: one vector per level. Each
-   * element of these vectors contains first the global index, then
-   * the level index.
+   * The data is organized as follows: one vector per level. Each element of
+   * these vectors contains first the global index, then the level index.
    */
   std::vector<std::vector<std::pair<types::global_dof_index, unsigned int> > >
   copy_indices;
 
   /**
-   * Additional degrees of freedom for the copy_to_mg()
-   * function. These are the ones where the global degree of freedom
-   * is locally owned and the level degree of freedom is not.
+   * Additional degrees of freedom for the copy_to_mg() function. These are
+   * the ones where the global degree of freedom is locally owned and the
+   * level degree of freedom is not.
    *
    * Organization of the data is like for #copy_indices_mine.
    */
@@ -299,9 +269,9 @@ private:
   copy_indices_to_me;
 
   /**
-   * Additional degrees of freedom for the copy_from_mg()
-   * function. These are the ones where the level degree of freedom
-   * is locally owned and the global degree of freedom is not.
+   * Additional degrees of freedom for the copy_from_mg() function. These are
+   * the ones where the level degree of freedom is locally owned and the
+   * global degree of freedom is not.
    *
    * Organization of the data is like for #copy_indices_mine.
    */
@@ -310,27 +280,22 @@ private:
 
 
   /**
-   * The vector that stores what
-   * has been given to the
-   * set_component_to_block_map()
-   * function.
+   * The vector that stores what has been given to the
+   * set_component_to_block_map() function.
    */
   std::vector<unsigned int> component_to_block_map;
 
   /**
-   * Degrees of freedom on the
-   * refinement edge excluding
-   * those on the boundary.
+   * Degrees of freedom on the refinement edge excluding those on the
+   * boundary.
    */
   std::vector<std::vector<bool> > interface_dofs;
   /**
-   * The constraints of the global
-   * system.
+   * The constraints of the global system.
    */
   SmartPointer<const ConstraintMatrix, MGTransferPrebuilt<VECTOR> > constraints;
   /**
-   * The mg_constrained_dofs of the level
-   * systems.
+   * The mg_constrained_dofs of the level systems.
    */
 
   SmartPointer<const MGConstrainedDoFs, MGTransferPrebuilt<VECTOR> > mg_constrained_dofs;
index a50ce746262b904bb40cfc47f0e62c3b72c62992..aa9ef7a4dd4df594ef95ed70b1f4abe88d620363 100644 (file)
@@ -34,16 +34,10 @@ DEAL_II_NAMESPACE_OPEN
 namespace
 {
   /**
-   * Adjust vectors on all levels to
-   * correct size.  Here, we just
-   * count the numbers of degrees
-   * of freedom on each level and
-   * @p reinit each level vector
-   * to this length.
-   * For compatibility reasons with
-   * the next function
-   * the target_component is added
-   * here but is not used.
+   * Adjust vectors on all levels to correct size.  Here, we just count the
+   * numbers of degrees of freedom on each level and @p reinit each level
+   * vector to this length. For compatibility reasons with the next function
+   * the target_component is added here but is not used.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -61,14 +55,10 @@ namespace
   }
 
   /**
-   * Adjust vectors on all levels to
-   * correct size.  Here, we just
-   * count the numbers of degrees
-   * of freedom on each level and
-   * @p reinit each level vector
-   * to this length. The target_component
-   * is handed to MGTools::count_dofs_per_block.
-   * See for documentation there.
+   * Adjust vectors on all levels to correct size.  Here, we just count the
+   * numbers of degrees of freedom on each level and @p reinit each level
+   * vector to this length. The target_component is handed to
+   * MGTools::count_dofs_per_block. See for documentation there.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -107,12 +97,9 @@ namespace
 
 #ifdef DEAL_II_WITH_TRILINOS
   /**
-   * Adjust vectors on all levels to
-   * correct size.  Here, we just
-   * count the numbers of degrees
-   * of freedom on each level and
-   * @p reinit each level vector
-   * to this length.
+   * Adjust vectors on all levels to correct size.  Here, we just count the
+   * numbers of degrees of freedom on each level and @p reinit each level
+   * vector to this length.
    */
   template <int dim, int spacedim>
   void
index a7b4f9fb151c607f42fbc9fa25fcd9b4df5143bf..034e2cb176418f1ec542dd58531e8185962e8d18 100644 (file)
@@ -50,10 +50,9 @@ template <int dim, int spacedim> class DoFHandler;
 /**
  * Implementation of matrix generation for MGTransferBlock.
  *
- * This is the base class for MGTransfer objects for systems of
- * equations where multigrid is applied only to one ore some blocks,
- * where a @ref GlossBlock comprises all degrees of freedom generated
- * by one base element.
+ * This is the base class for MGTransfer objects for systems of equations
+ * where multigrid is applied only to one ore some blocks, where a @ref
+ * GlossBlock comprises all degrees of freedom generated by one base element.
  *
  * @author Guido Kanschat, 2001-2003
  */
@@ -61,11 +60,8 @@ class MGTransferBlockBase
 {
 public:
   /**
-   * Constructor without constraint
-   * matrices. Use this constructor
-   * only with discontinuous finite
-   * elements or with no local
-   * refinement.
+   * Constructor without constraint matrices. Use this constructor only with
+   * discontinuous finite elements or with no local refinement.
    */
   MGTransferBlockBase ();
   /**
@@ -80,14 +76,10 @@ public:
 
 protected:
   /**
-   * Actually build the prolongation
-   * matrices for each level.
+   * Actually build the prolongation matrices for each level.
    *
-   * This function is only called
-   * by derived classes. These can
-   * also set the member variables
-   * #selected and others to
-   * restrict the transfer matrices
+   * This function is only called by derived classes. These can also set the
+   * member variables #selected and others to restrict the transfer matrices
    * to certain blocks.
    */
   template <int dim, int spacedim>
@@ -97,29 +89,22 @@ protected:
   /**
    * Flag of selected blocks.
    *
-   * The transfer operators only act
-   * on the blocks having a
-   * <tt>true</tt> entry here.
+   * The transfer operators only act on the blocks having a <tt>true</tt>
+   * entry here.
    */
 //TODO: rename this to block_mask, in the same way as has already been done in MGTransferComponent, and give it type BlockMask
   std::vector<bool> selected;
 
   /**
-   * Number of blocks of multigrid
-   * vector.
+   * Number of blocks of multigrid vector.
    */
   unsigned int n_mg_blocks;
 
   /**
-   * For each block of the whole
-   * block vector, list to what
-   * block of the multigrid vector
-   * it is mapped. Since depending
-   * on #selected, there may be
-   * fewer mutlilevel blocks than
-   * original blocks, some of the
-   * entries may be illegal
-   * unsigned integers.
+   * For each block of the whole block vector, list to what block of the
+   * multigrid vector it is mapped. Since depending on #selected, there may be
+   * fewer mutlilevel blocks than original blocks, some of the entries may be
+   * illegal unsigned integers.
    */
 //TODO: rename this to mg_block_mask, in the same way as has already been done in MGTransferComponent, and give it type BlockMask
   std::vector<unsigned int> mg_block;
@@ -135,14 +120,12 @@ protected:
   std::vector<types::global_dof_index> block_start;
 
   /**
-   * Start index of each block on
-   * all levels.
+   * Start index of each block on all levels.
    */
   std::vector<std::vector<types::global_dof_index> > mg_block_start;
 
   /**
-   * Call build_matrices()
-   * function first.
+   * Call build_matrices() function first.
    */
   DeclException0(ExcMatricesNotBuilt);
 
@@ -152,58 +135,47 @@ private:
 protected:
 
   /**
-   * The actual prolongation matrix.
-   * column indices belong to the
-   * dof indices of the mother cell,
-   * i.e. the coarse level.
-   * while row indices belong to the
-   * child cell, i.e. the fine level.
+   * The actual prolongation matrix. column indices belong to the dof indices
+   * of the mother cell, i.e. the coarse level. while row indices belong to
+   * the child cell, i.e. the fine level.
    */
   std::vector<std_cxx11::shared_ptr<BlockSparseMatrix<double> > > prolongation_matrices;
 
   /**
-   * Mapping for the
-   * <tt>copy_to/from_mg</tt>-functions.
-   * The indices into this vector
-   * are (in this order): global
-   * block number, level
-   * number. The data is first the
-   * global index inside the block,
-   * then the level index inside
+   * Mapping for the <tt>copy_to/from_mg</tt>-functions. The indices into this
+   * vector are (in this order): global block number, level number. The data
+   * is first the global index inside the block, then the level index inside
    * the block.
-  */
+   */
   std::vector<std::vector<std::vector<std::pair<unsigned int, unsigned int> > > >
   copy_indices;
   /**
-   * The constraints of the global
-   * system.
+   * The constraints of the global system.
    */
   SmartPointer<const ConstraintMatrix, MGTransferBlockBase> constraints;
   /**
-   * The mg_constrained_dofs of the level
-   * systems.
+   * The mg_constrained_dofs of the level systems.
    */
 
   SmartPointer<const MGConstrainedDoFs, MGTransferBlockBase> mg_constrained_dofs;
 };
 
 /**
- * Implementation of the MGTransferBase interface for block
- * matrices and block vectors.
+ * Implementation of the MGTransferBase interface for block matrices and block
+ * vectors.
  *
  * @warning This class is in an untested state. If you use it and you
  * encounter problems, please contact Guido Kanschat.
  *
- * In addition to the functionality of
- * MGTransferPrebuilt, the operation may be restricted to
- * certain blocks of the vector.
+ * In addition to the functionality of MGTransferPrebuilt, the operation may
+ * be restricted to certain blocks of the vector.
  *
- * If the restricted mode is chosen, block vectors used in the
- * transfer routines may only have as many blocks as there are
- * @p trues in the selected-field.
+ * If the restricted mode is chosen, block vectors used in the transfer
+ * routines may only have as many blocks as there are @p trues in the
+ * selected-field.
  *
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
  *
  * @author Guido Kanschat, 2001, 2002
  */
@@ -223,20 +195,16 @@ public:
   virtual ~MGTransferBlock ();
 
   /**
-   * Initialize additional #factors
-   * and #memory if the restriction
-   * of the blocks is to be
-   * weighted differently.
+   * Initialize additional #factors and #memory if the restriction of the
+   * blocks is to be weighted differently.
    */
   void initialize (const std::vector<number> &factors,
                    VectorMemory<Vector<number> > &memory);
 
   /**
-   * Build the prolongation
-   * matrices for each level.
+   * Build the prolongation matrices for each level.
    *
-   * This function is a front-end
-   * for the same function in
+   * This function is a front-end for the same function in
    * MGTransferBlockBase.
    */
   template<int dim, int spacedim>
@@ -253,19 +221,12 @@ public:
                                  const BlockVector<number> &src) const;
 
   /**
-   * Transfer from a vector on the
-   * global grid to a multilevel
-   * vector.
+   * Transfer from a vector on the global grid to a multilevel vector.
    *
-   * The action for discontinuous
-   * elements is as follows: on an
-   * active mesh cell, the global
-   * vector entries are simply
-   * copied to the corresponding
-   * entries of the level
-   * vector. Then, these values are
-   * restricted down to the
-   * coarsest level.
+   * The action for discontinuous elements is as follows: on an active mesh
+   * cell, the global vector entries are simply copied to the corresponding
+   * entries of the level vector. Then, these values are restricted down to
+   * the coarsest level.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -274,13 +235,10 @@ public:
               const BlockVector<number2> &src) const;
 
   /**
-   * Transfer from multi-level vector to
-   * normal vector.
+   * Transfer from multi-level vector to normal vector.
    *
-   * Copies data from active
-   * portions of a multilevel
-   * vector into the respective
-   * positions of a global vector.
+   * Copies data from active portions of a multilevel vector into the
+   * respective positions of a global vector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -289,12 +247,9 @@ public:
                 const MGLevelObject<BlockVector<number> > &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -306,17 +261,14 @@ public:
 
 private:
   /**
-   * Optional multiplication
-   * factors for each
-   * block. Requires
-   * initialization of #memory.
+   * Optional multiplication factors for each block. Requires initialization
+   * of #memory.
    */
   std::vector<number> factors;
 
   /**
-   * Memory pool required if
-   * additional multiplication
-   * using #factors is desired.
+   * Memory pool required if additional multiplication using #factors is
+   * desired.
    */
   SmartPointer<VectorMemory<Vector<number> >,MGTransferBlock<number> > memory;
 };
@@ -325,14 +277,14 @@ private:
 //TODO:[GK] Update documentation for copy_* functions
 
 /**
- * Implementation of the MGTransferBase interface for block matrices
- * and simple vectors. This class uses MGTransferBlockBase selecting a
- * single block. The intergrid transfer operators are implemented for
- * Vector objects, The copy functions between regular and multigrid
- * vectors for Vector and BlockVector.
+ * Implementation of the MGTransferBase interface for block matrices and
+ * simple vectors. This class uses MGTransferBlockBase selecting a single
+ * block. The intergrid transfer operators are implemented for Vector objects,
+ * The copy functions between regular and multigrid vectors for Vector and
+ * BlockVector.
  *
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
  *
  * @author Guido Kanschat, 2001, 2002, 2003
  */
@@ -342,11 +294,8 @@ class MGTransferBlockSelect : public MGTransferBase<Vector<number> >,
 {
 public:
   /**
-   * Constructor without constraint
-   * matrices. Use this constructor
-   * only with discontinuous finite
-   * elements or with no local
-   * refinement.
+   * Constructor without constraint matrices. Use this constructor only with
+   * discontinuous finite elements or with no local refinement.
    */
   MGTransferBlockSelect ();
   /**
@@ -360,22 +309,16 @@ public:
   virtual ~MGTransferBlockSelect ();
 
   /**
-   * Actually build the prolongation
-   * matrices for grouped blocks.
+   * Actually build the prolongation matrices for grouped blocks.
    *
-   * This function is a front-end
-   * for the same function in
+   * This function is a front-end for the same function in
    * MGTransferBlockBase.
    *
-   * @arg selected: Number of the
-   * block of the global vector
-   * to be copied from and to the
-   * multilevel vector.
+   * @arg selected: Number of the block of the global vector to be copied from
+   * and to the multilevel vector.
    *
-   * @arg mg_selected: Number
-   * of the component for which the
-   * transfer matrices should be
-   * built.
+   * @arg mg_selected: Number of the component for which the transfer matrices
+   * should be built.
    */
   template<int dim, int spacedim>
   void build_matrices (const DoFHandler<dim,spacedim> &dof,
@@ -383,8 +326,7 @@ public:
                        unsigned int selected);
 
   /**
-   * Change selected
-   * block. Handle with care!
+   * Change selected block. Handle with care!
    */
   void select (const unsigned int block);
 
@@ -397,9 +339,8 @@ public:
                                  const Vector<number> &src) const;
 
   /**
-   * Transfer a single block from a
-   * vector on the global grid to a
-   * multilevel vector.
+   * Transfer a single block from a vector on the global grid to a multilevel
+   * vector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -408,13 +349,10 @@ public:
               const Vector<number2>          &src) const;
 
   /**
-   * Transfer from multilevel vector to
-   * normal vector.
+   * Transfer from multilevel vector to normal vector.
    *
-   * Copies data from active
-   * portions of an multilevel
-   * vector into the respective
-   * positions of a Vector.
+   * Copies data from active portions of an multilevel vector into the
+   * respective positions of a Vector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -423,12 +361,9 @@ public:
                 const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -437,10 +372,8 @@ public:
                     const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Transfer a block from a vector
-   * on the global grid to
-   * multilevel vectors. Only the
-   * block selected is transfered.
+   * Transfer a block from a vector on the global grid to multilevel vectors.
+   * Only the block selected is transfered.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -449,14 +382,10 @@ public:
               const BlockVector<number2>     &src) const;
 
   /**
-   * Transfer from multilevel vector to
-   * normal vector.
+   * Transfer from multilevel vector to normal vector.
    *
-   * Copies data from active
-   * portions of a multilevel
-   * vector into the respective
-   * positions of a global
-   * BlockVector.
+   * Copies data from active portions of a multilevel vector into the
+   * respective positions of a global BlockVector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -465,12 +394,9 @@ public:
                 const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -485,8 +411,7 @@ public:
 
 private:
   /**
-   * Implementation of the public
-   * function.
+   * Implementation of the public function.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -496,8 +421,7 @@ private:
                    const unsigned int offset) const;
 
   /**
-   * Implementation of the public
-   * function.
+   * Implementation of the public function.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -507,8 +431,7 @@ private:
                        const unsigned int offset) const;
 
   /**
-   * Actual implementation of
-   * copy_to_mg().
+   * Actual implementation of copy_to_mg().
    */
   template <int dim, class InVector, int spacedim>
   void
index b381c9c3ee2cb2ed15f05156c39ab290058b839f..25901128286c5b5d80ea75106be052f6077c2b5c 100644 (file)
@@ -47,9 +47,9 @@ template <int dim, int spacedim> class DoFHandler;
 /**
  * Implementation of matrix generation for component wise multigrid transfer.
  *
- * @note MGTransferBlockBase is probably the more logical
- * class. Still eventually, a class should be developed allowing to
- * select multiple components.
+ * @note MGTransferBlockBase is probably the more logical class. Still
+ * eventually, a class should be developed allowing to select multiple
+ * components.
  *
  * @author Guido Kanschat, 2001-2003
  */
@@ -64,20 +64,14 @@ public:
 
 protected:
   /**
-   * Actually build the prolongation
-   * matrices for each level.
+   * Actually build the prolongation matrices for each level.
    *
-   * This function is only called
-   * by derived classes. These can
-   * also set the member variables
-   * <code>selected_component</code> and <code>mg_selected_component</code> member variables to
-   * restrict the transfer matrices
-   * to certain components.
-   * Furthermore, they use
-   * <code>target_component</code> and
-   * <code>mg_target_component</code> for
-   * re-ordering and grouping of
-   * components.
+   * This function is only called by derived classes. These can also set the
+   * member variables <code>selected_component</code> and
+   * <code>mg_selected_component</code> member variables to restrict the
+   * transfer matrices to certain components. Furthermore, they use
+   * <code>target_component</code> and <code>mg_target_component</code> for
+   * re-ordering and grouping of components.
    */
   template <int dim, int spacedim>
   void build_matrices (const DoFHandler<dim,spacedim> &dof,
@@ -86,40 +80,28 @@ protected:
   /**
    * Flag of selected components.
    *
-   * The transfer operators only act
-   * on the components having a
-   * <tt>true</tt> entry here. If
-   * renumbering by
-   * #target_component is used,
-   * this refers to the
-   * <b>renumbered</b> components.
+   * The transfer operators only act on the components having a <tt>true</tt>
+   * entry here. If renumbering by #target_component is used, this refers to
+   * the <b>renumbered</b> components.
    */
   ComponentMask component_mask;
 
   /**
    * Flag of selected components.
    *
-   * The transfer operators only act
-   * on the components having a
-   * <tt>true</tt> entry here. If
-   * renumbering by
-   * #mg_target_component is used,
-   * this refers to the
-   * <b>renumbered</b> components.
+   * The transfer operators only act on the components having a <tt>true</tt>
+   * entry here. If renumbering by #mg_target_component is used, this refers
+   * to the <b>renumbered</b> components.
    */
   ComponentMask mg_component_mask;
 
   /**
-   * Target component of the
-   * fine-level vector if
-   * renumbering is required.
+   * Target component of the fine-level vector if renumbering is required.
    */
   std::vector<unsigned int> target_component;
 
   /**
-   * Target component if
-   * renumbering of level vectors
-   * is required.
+   * Target component if renumbering of level vectors is required.
    */
   std::vector<unsigned int> mg_target_component;
 
@@ -134,14 +116,12 @@ protected:
   std::vector<types::global_dof_index> component_start;
 
   /**
-   * Start index of each component on
-   * all levels.
+   * Start index of each component on all levels.
    */
   std::vector<std::vector<types::global_dof_index> > mg_component_start;
 
   /**
-   * Call build_matrices()
-   * function first.
+   * Call build_matrices() function first.
    */
   DeclException0(ExcMatricesNotBuilt);
 
@@ -151,29 +131,22 @@ private:
 protected:
 
   /**
-   * The actual prolongation matrix.
-   * column indices belong to the
-   * dof indices of the mother cell,
-   * i.e. the coarse level.
-   * while row indices belong to the
-   * child cell, i.e. the fine level.
+   * The actual prolongation matrix. column indices belong to the dof indices
+   * of the mother cell, i.e. the coarse level. while row indices belong to
+   * the child cell, i.e. the fine level.
    */
   std::vector<std_cxx11::shared_ptr<BlockSparseMatrix<double> > > prolongation_matrices;
 
   /**
-   * Holds the mapping for the
-   * <tt>copy_to/from_mg</tt>-functions.
-   * The data is first the global
-   * index, then the level index.
+   * Holds the mapping for the <tt>copy_to/from_mg</tt>-functions. The data is
+   * first the global index, then the level index.
    */
   std::vector<std::vector<std::pair<types::global_dof_index, unsigned int> > >
   copy_to_and_from_indices;
 
   /**
-   * Store the boundary_indices.
-   * These are needed for the
-   * boundary values in the
-   * restriction matrix.
+   * Store the boundary_indices. These are needed for the boundary values in
+   * the restriction matrix.
    */
   std::vector<std::set<types::global_dof_index> > boundary_indices;
 };
@@ -183,14 +156,13 @@ protected:
 //TODO: Use same kind of template argument as MGTransferSelect
 
 /**
- * Implementation of the MGTransferBase interface for block
- * matrices and simple vectors. This class uses MGTransferComponentBase
- * selecting a single component or grouping several components into a
- * single block. The transfer operators themselves are implemented for
- * Vector and BlockVector objects.
+ * Implementation of the MGTransferBase interface for block matrices and
+ * simple vectors. This class uses MGTransferComponentBase selecting a single
+ * component or grouping several components into a single block. The transfer
+ * operators themselves are implemented for Vector and BlockVector objects.
  *
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
  *
  * @author Guido Kanschat, 2001, 2002, 2003
  */
@@ -200,11 +172,8 @@ class MGTransferSelect : public MGTransferBase<Vector<number> >,
 {
 public:
   /**
-   * Constructor without constraint
-   * matrices. Use this constructor
-   * only with discontinuous finite
-   * elements or with no local
-   * refinement.
+   * Constructor without constraint matrices. Use this constructor only with
+   * discontinuous finite elements or with no local refinement.
    */
   MGTransferSelect ();
 
@@ -220,45 +189,29 @@ public:
 
 //TODO: rewrite docs; make sure defaulted args are actually allowed
   /**
-   * Actually build the prolongation
-   * matrices for grouped components.
+   * Actually build the prolongation matrices for grouped components.
    *
-   * This function is a front-end
-   * for the same function in
+   * This function is a front-end for the same function in
    * MGTransferComponentBase.
    *
-   * @arg selected: Number of the
-   * block of the global vector
-   * to be copied from and to the
-   * multilevel vector. This number
-   * refers to the renumbering by
+   * @arg selected: Number of the block of the global vector to be copied from
+   * and to the multilevel vector. This number refers to the renumbering by
    * <tt>target_component</tt>.
    *
-   * @arg mg_selected: Number
-   * of the block for which the
-   * transfer matrices should be
-   * built.
+   * @arg mg_selected: Number of the block for which the transfer matrices
+   * should be built.
    *
-   * If <tt>mg_target_component</tt> is
-   * present, this refers to the
-   * renumbered components.
+   * If <tt>mg_target_component</tt> is present, this refers to the renumbered
+   * components.
    *
-   * @arg target_component: this
-   * argument allows grouping and
-   * renumbering of components in
-   * the fine-level vector (see
-   * DoFRenumbering::component_wise).
+   * @arg target_component: this argument allows grouping and renumbering of
+   * components in the fine-level vector (see DoFRenumbering::component_wise).
    *
-   * @arg mg_target_component: this
-   * argument allows grouping and
-   * renumbering of components in
-   * the level vectors (see
-   * DoFRenumbering::component_wise). It
-   * also affects the behavior of
-   * the <tt>selected</tt> argument
+   * @arg mg_target_component: this argument allows grouping and renumbering
+   * of components in the level vectors (see DoFRenumbering::component_wise).
+   * It also affects the behavior of the <tt>selected</tt> argument
    *
-   * @arg boundary_indices: holds the
-   * boundary indices on each level.
+   * @arg boundary_indices: holds the boundary indices on each level.
    */
   template <int dim, int spacedim>
   void build_matrices (const DoFHandler<dim,spacedim> &dof,
@@ -274,8 +227,7 @@ public:
                       );
 
   /**
-   * Change selected
-   * component. Handle with care!
+   * Change selected component. Handle with care!
    */
   void select (const unsigned int component,
                const unsigned int mg_component = numbers::invalid_unsigned_int);
@@ -289,8 +241,7 @@ public:
                                  const Vector<number> &src) const;
 
   /**
-   * Transfer from a vector on the
-   * global grid to a multilevel vector.
+   * Transfer from a vector on the global grid to a multilevel vector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -299,13 +250,10 @@ public:
               const Vector<number2>          &src) const;
 
   /**
-   * Transfer from multilevel vector to
-   * normal vector.
+   * Transfer from multilevel vector to normal vector.
    *
-   * Copies data from active
-   * portions of an multilevel
-   * vector into the respective
-   * positions of a Vector.
+   * Copies data from active portions of an multilevel vector into the
+   * respective positions of a Vector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -314,12 +262,9 @@ public:
                 const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -328,8 +273,7 @@ public:
                     const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Transfer from a vector on the
-   * global grid to multilevel vectors.
+   * Transfer from a vector on the global grid to multilevel vectors.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -338,14 +282,10 @@ public:
               const BlockVector<number2>     &src) const;
 
   /**
-   * Transfer from multilevel vector to
-   * normal vector.
+   * Transfer from multilevel vector to normal vector.
    *
-   * Copies data from active
-   * portions of a multilevel
-   * vector into the respective
-   * positions of a global
-   * BlockVector.
+   * Copies data from active portions of a multilevel vector into the
+   * respective positions of a global BlockVector.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -354,12 +294,9 @@ public:
                 const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Add a multi-level vector to a
-   * normal vector.
+   * Add a multi-level vector to a normal vector.
    *
-   * Works as the previous
-   * function, but probably not for
-   * continuous elements.
+   * Works as the previous function, but probably not for continuous elements.
    */
   template <int dim, typename number2, int spacedim>
   void
@@ -374,8 +311,7 @@ public:
 
 private:
   /**
-   * Implementation of the public
-   * function.
+   * Implementation of the public function.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -384,8 +320,7 @@ private:
                    const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Implementation of the public
-   * function.
+   * Implementation of the public function.
    */
   template <int dim, class OutVector, int spacedim>
   void
@@ -394,8 +329,7 @@ private:
                        const MGLevelObject<Vector<number> > &src) const;
 
   /**
-   * Actual implementation of
-   * copy_to_mg().
+   * Actual implementation of copy_to_mg().
    */
   template <int dim, class InVector, int spacedim>
   void
@@ -412,20 +346,15 @@ private:
   unsigned int mg_selected_component;
 
   /**
-   * The degrees of freedom on the
-   * the refinement edges. For each
-   * level (outer vector) and each
-   * dof index (inner vector), this
-   * bool is true if the level
-   * degree of freedom is on the
-   * refinement edge towards the
-   * lower level excluding boundary dofs.
+   * The degrees of freedom on the the refinement edges. For each level (outer
+   * vector) and each dof index (inner vector), this bool is true if the level
+   * degree of freedom is on the refinement edge towards the lower level
+   * excluding boundary dofs.
    */
   std::vector<std::vector<bool> > interface_dofs;
 
   /**
-   * The constraints of the global
-   * system.
+   * The constraints of the global system.
    */
 public:
   SmartPointer<const ConstraintMatrix> constraints;
index df081a6989e88a39156b173eb756ebffc21e8427..f4df66f6f3e1b0552daf5f679903d0709b6214e7 100644 (file)
@@ -38,28 +38,26 @@ DEAL_II_NAMESPACE_OPEN
  * Implementation of the multigrid method.
  *
  * @warning multigrid on locally refined meshes only works with
- * <b>discontinuous finite elements</b> right now. It is not clear,
- * whether the paradigm of local smoothing we use is applicable to
- * continuous elements with hanging nodes; in fact, most people you
- * meet on conferences seem to deny this.
+ * <b>discontinuous finite elements</b> right now. It is not clear, whether
+ * the paradigm of local smoothing we use is applicable to continuous elements
+ * with hanging nodes; in fact, most people you meet on conferences seem to
+ * deny this.
  *
- * The function which starts a multigrid cycle on the finest level is
- * cycle(). Depending on the cycle type chosen with the constructor
- * (see enum Cycle), this function triggers one of the cycles
- * level_v_step() or level_step(), where the latter one can do
- * different types of cycles.
+ * The function which starts a multigrid cycle on the finest level is cycle().
+ * Depending on the cycle type chosen with the constructor (see enum Cycle),
+ * this function triggers one of the cycles level_v_step() or level_step(),
+ * where the latter one can do different types of cycles.
  *
  * Using this class, it is expected that the right hand side has been
- * converted from a vector living on the locally finest level to a
- * multilevel vector. This is a nontrivial operation, usually
- * initiated automatically by the class PreconditionMG and performed
- * by the classes derived from MGTransferBase.
+ * converted from a vector living on the locally finest level to a multilevel
+ * vector. This is a nontrivial operation, usually initiated automatically by
+ * the class PreconditionMG and performed by the classes derived from
+ * MGTransferBase.
  *
- * @note The interface of this class is still very clumsy. In
- * particular, you will have to set up quite a few auxiliary objects
- * before you can use it. Unfortunately, it seems that this can be
- * avoided only be restricting the flexibility of this class in an
- * unacceptable way.
+ * @note The interface of this class is still very clumsy. In particular, you
+ * will have to set up quite a few auxiliary objects before you can use it.
+ * Unfortunately, it seems that this can be avoided only be restricting the
+ * flexibility of this class in an unacceptable way.
  *
  * @author Guido Kanschat, 1999 - 2005
  */
@@ -84,19 +82,12 @@ public:
   typedef const VECTOR const_vector_type;
 
   /**
-   * Constructor. The
-   * DoFHandler is used to
-   * determine the highest possible
-   * level. <tt>transfer</tt> is an
-   * object performing prolongation
-   * and restriction.
+   * Constructor. The DoFHandler is used to determine the highest possible
+   * level. <tt>transfer</tt> is an object performing prolongation and
+   * restriction.
    *
-   * This function already
-   * initializes the vectors which
-   * will be used later in the
-   * course of the
-   * computations. You should
-   * therefore create objects of
+   * This function already initializes the vectors which will be used later in
+   * the course of the computations. You should therefore create objects of
    * this type as late as possible.
    */
   template <int dim>
@@ -109,9 +100,7 @@ public:
             Cycle cycle = v_cycle);
 
   /**
-   * Experimental constructor for
-   * cases in which no DoFHandler
-   * is available.
+   * Experimental constructor for cases in which no DoFHandler is available.
    *
    * @warning Not intended for general use.
    */
@@ -125,211 +114,125 @@ public:
             Cycle cycle = v_cycle);
 
   /**
-   * Reinit this class according to
-   * #minlevel and #maxlevel.
+   * Reinit this class according to #minlevel and #maxlevel.
    */
   void reinit (const unsigned int minlevel,
                const unsigned int maxlevel);
 
   /**
-   * Execute one multigrid
-   * cycle. The type of cycle is
-   * selected by the constructor
-   * argument cycle. See the enum
-   * Cycle for available types.
+   * Execute one multigrid cycle. The type of cycle is selected by the
+   * constructor argument cycle. See the enum Cycle for available types.
    */
   void cycle ();
 
   /**
-   * Execute one step of the
-   * V-cycle algorithm.  This
-   * function assumes, that the
-   * multilevel vector #defect is
-   * filled with the residual of an
-   * outer defect correction
-   * scheme. This is usually taken
-   * care of by
-   * PreconditionMG). After
-   * vcycle(), the result is in the
-   * multilevel vector
-   * #solution. See
-   * <tt>copy_*_mg</tt> in class
-   * MGTools if you want to use
+   * Execute one step of the V-cycle algorithm.  This function assumes, that
+   * the multilevel vector #defect is filled with the residual of an outer
+   * defect correction scheme. This is usually taken care of by
+   * PreconditionMG). After vcycle(), the result is in the multilevel vector
+   * #solution. See <tt>copy_*_mg</tt> in class MGTools if you want to use
    * these vectors yourself.
    *
-   * The actual work for this
-   * function is done in
-   * level_v_step().
+   * The actual work for this function is done in level_v_step().
    */
   void vcycle ();
 
   /**
-   * @deprecated This function is
-   * purely experimental and will
-   * probably never be implemented
-   * in a way that it can be
-   * released.
+   * @deprecated This function is purely experimental and will probably never
+   * be implemented in a way that it can be released.
    *
-   * Perform a multigrid cycle with
-   * a vector which is already a
-   * level vector. Use of this
-   * function assumes that there is
-   * NO local refinement and that
-   * both vectors are on the finest
-   * level of this Multigrid
-   * object.
+   * Perform a multigrid cycle with a vector which is already a level vector.
+   * Use of this function assumes that there is NO local refinement and that
+   * both vectors are on the finest level of this Multigrid object.
    */
   void vmult(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated This function is
-   * purely experimental and will
-   * probably never be implemented
-   * in a way that it can be
-   * released.
+   * @deprecated This function is purely experimental and will probably never
+   * be implemented in a way that it can be released.
    *
-   * Perform a multigrid cycle with
-   * a vector which is already a
-   * level vector. Use of this
-   * function assumes that there is
-   * NO local refinement and that
-   * both vectors are on the finest
-   * level of this Multigrid
-   * object.
+   * Perform a multigrid cycle with a vector which is already a level vector.
+   * Use of this function assumes that there is NO local refinement and that
+   * both vectors are on the finest level of this Multigrid object.
    */
   void vmult_add(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated Even worse than
-   * vmult(), this function is not
-   * even implemented, but just
-   * declared such that certain
-   * objects relying on it can be
-   * constructed.
+   * @deprecated Even worse than vmult(), this function is not even
+   * implemented, but just declared such that certain objects relying on it
+   * can be constructed.
    */
   void Tvmult(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
 
   /**
-   * @deprecated Even worse than
-   * vmult(), this function is not
-   * even implemented, but just
-   * declared such that certain
-   * objects relying on it can be
-   * constructed.
+   * @deprecated Even worse than vmult(), this function is not even
+   * implemented, but just declared such that certain objects relying on it
+   * can be constructed.
    */
   void Tvmult_add(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
 
   /**
-   * Set additional matrices to
-   * correct residual computation
-   * at refinement edges. Since we
-   * only smoothen in the interior
-   * of the refined part of the
-   * mesh, the coupling across the
-   * refinement edge is
-   * missing. This coupling is
-   * provided by these two
-   * matrices.
+   * Set additional matrices to correct residual computation at refinement
+   * edges. Since we only smoothen in the interior of the refined part of the
+   * mesh, the coupling across the refinement edge is missing. This coupling
+   * is provided by these two matrices.
    *
-   * @note While
-   * <tt>edge_out.vmult</tt> is
-   * used, for the second argument,
-   * we use
-   * <tt>edge_in.Tvmult</tt>. Thus,
-   * <tt>edge_in</tt> should be
-   * assembled in transposed
-   * form. This saves a second
-   * sparsity pattern for
-   * <tt>edge_in</tt>. In
-   * particular, for symmetric
-   * operators, both arguments can
-   * refer to the same matrix,
-   * saving assembling of one of
-   * them.
+   * @note While <tt>edge_out.vmult</tt> is used, for the second argument, we
+   * use <tt>edge_in.Tvmult</tt>. Thus, <tt>edge_in</tt> should be assembled
+   * in transposed form. This saves a second sparsity pattern for
+   * <tt>edge_in</tt>. In particular, for symmetric operators, both arguments
+   * can refer to the same matrix, saving assembling of one of them.
    */
   void set_edge_matrices (const MGMatrixBase<VECTOR> &edge_out,
                           const MGMatrixBase<VECTOR> &edge_in);
 
   /**
-   * Set additional matrices to
-   * correct residual computation
-   * at refinement edges. These
-   * matrices originate from
-   * discontinuous Galerkin methods
-   * (see FE_DGQ etc.), where they
-   * correspond to the edge fluxes
-   * at the refinement edge between
-   * two levels.
+   * Set additional matrices to correct residual computation at refinement
+   * edges. These matrices originate from discontinuous Galerkin methods (see
+   * FE_DGQ etc.), where they correspond to the edge fluxes at the refinement
+   * edge between two levels.
    *
-   * @note While
-   * <tt>edge_down.vmult</tt> is
-   * used, for the second argument,
-   * we use
-   * <tt>edge_up.Tvmult</tt>. Thus,
-   * <tt>edge_up</tt> should be
-   * assembled in transposed
-   * form. This saves a second
-   * sparsity pattern for
-   * <tt>edge_up</tt>. In
-   * particular, for symmetric
-   * operators, both arguments can
-   * refer to the same matrix,
-   * saving assembling of one of
-   * them.
+   * @note While <tt>edge_down.vmult</tt> is used, for the second argument, we
+   * use <tt>edge_up.Tvmult</tt>. Thus, <tt>edge_up</tt> should be assembled
+   * in transposed form. This saves a second sparsity pattern for
+   * <tt>edge_up</tt>. In particular, for symmetric operators, both arguments
+   * can refer to the same matrix, saving assembling of one of them.
    */
   void set_edge_flux_matrices (const MGMatrixBase<VECTOR> &edge_down,
                                const MGMatrixBase<VECTOR> &edge_up);
 
   /**
-   * Return the finest level for
-   * multigrid.
+   * Return the finest level for multigrid.
    */
   unsigned int get_maxlevel() const;
 
   /**
-   * Return the coarsest level for
-   * multigrid.
+   * Return the coarsest level for multigrid.
    */
   unsigned int get_minlevel() const;
 
   /**
-   * Set the highest level for
-   * which the multilevel method is
-   * performed. By default, this is
-   * the finest level of the
-   * Triangulation; therefore, this
-   * function will only accept
-   * arguments smaller than the
-   * current #maxlevel and not
-   * smaller than the current
-   * #minlevel.
+   * Set the highest level for which the multilevel method is performed. By
+   * default, this is the finest level of the Triangulation; therefore, this
+   * function will only accept arguments smaller than the current #maxlevel
+   * and not smaller than the current #minlevel.
    */
   void set_maxlevel (const unsigned int);
 
   /**
-   * Set the coarse level for which
-   * the multilevel method is
-   * performed. By default, this is
-   * zero. Accepted are
-   * non-negative values not larger than
+   * Set the coarse level for which the multilevel method is performed. By
+   * default, this is zero. Accepted are non-negative values not larger than
    * than the current #maxlevel.
    *
-   * If <tt>relative</tt> ist
-   * <tt>true</tt>, then this
-   * function determins the number
-   * of levels used, that is, it
-   * sets #minlevel to
+   * If <tt>relative</tt> ist <tt>true</tt>, then this function determins the
+   * number of levels used, that is, it sets #minlevel to
    * #maxlevel-<tt>level</tt>.
    *
-   * @note The mesh on the coarsest
-   * level must cover the whole
-   * domain. There may not be
-   * hanging nodes on #minlevel.
+   * @note The mesh on the coarsest level must cover the whole domain. There
+   * may not be hanging nodes on #minlevel.
    *
-   * @note If #minlevel is set to a
-   * nonzero value, do not forget
-   * to adjust your coarse grid
-   * solver!
+   * @note If #minlevel is set to a nonzero value, do not forget to adjust
+   * your coarse grid solver!
    */
   void set_minlevel (const unsigned int level,
                      bool relative = false);
@@ -340,42 +243,27 @@ public:
   void set_cycle(Cycle);
 
   /**
-   * Set the debug level. Higher
-   * values will create more
-   * debugging output during the
-   * multigrid cycles.
+   * Set the debug level. Higher values will create more debugging output
+   * during the multigrid cycles.
    */
   void set_debug (const unsigned int);
 
 private:
 
   /**
-   * The V-cycle multigrid method.
-   * <tt>level</tt> is the level the
-   * function starts on. It
-   * will usually be called for the
-   * highest level from outside,
-   * but will then call itself
-   * recursively for <tt>level-1</tt>,
-   * unless we are on #minlevel
-   * where the coarse grid solver
-   * solves the problem exactly.
+   * The V-cycle multigrid method. <tt>level</tt> is the level the function
+   * starts on. It will usually be called for the highest level from outside,
+   * but will then call itself recursively for <tt>level-1</tt>, unless we are
+   * on #minlevel where the coarse grid solver solves the problem exactly.
    */
   void level_v_step (const unsigned int level);
 
   /**
-   * The actual W-cycle or F-cycle
-   * multigrid method.
-   * <tt>level</tt> is the level
-   * the function starts on. It
-   * will usually be called for the
-   * highest level from outside,
-   * but will then call itself
-   * recursively for
-   * <tt>level-1</tt>, unless we
-   * are on #minlevel where the
-   * coarse grid solver solves the
-   * problem exactly.
+   * The actual W-cycle or F-cycle multigrid method. <tt>level</tt> is the
+   * level the function starts on. It will usually be called for the highest
+   * level from outside, but will then call itself recursively for
+   * <tt>level-1</tt>, unless we are on #minlevel where the coarse grid solver
+   * solves the problem exactly.
    */
   void level_step (const unsigned int level, Cycle cycle);
 
@@ -396,16 +284,13 @@ private:
 
 public:
   /**
-   * Input vector for the
-   * cycle. Contains the defect of
-   * the outer method projected to
-   * the multilevel vectors.
+   * Input vector for the cycle. Contains the defect of the outer method
+   * projected to the multilevel vectors.
    */
   MGLevelObject<VECTOR> defect;
 
   /**
-   * The solution update after the
-   * multigrid step.
+   * The solution update after the multigrid step.
    */
   MGLevelObject<VECTOR> solution;
 
@@ -416,9 +301,7 @@ private:
   MGLevelObject<VECTOR> t;
 
   /**
-   * Auxiliary vector for W- and
-   * F-cycles. Left uninitialized
-   * in V-cycle.
+   * Auxiliary vector for W- and F-cycles. Left uninitialized in V-cycle.
    */
   MGLevelObject<VECTOR> defect2;
 
@@ -449,45 +332,36 @@ private:
   SmartPointer<const MGSmootherBase<VECTOR>,Multigrid<VECTOR> > post_smooth;
 
   /**
-   * Edge matrix from the interior
-   * of the refined part to the
-   * refinement edge.
+   * Edge matrix from the interior of the refined part to the refinement edge.
    *
-   * @note Only <tt>vmult</tt> is
-   * used for these matrices.
+   * @note Only <tt>vmult</tt> is used for these matrices.
    */
   SmartPointer<const MGMatrixBase<VECTOR> > edge_out;
 
   /**
-   * Transpose edge matrix from the
-   * refinement edge to the
-   * interior of the refined part.
+   * Transpose edge matrix from the refinement edge to the interior of the
+   * refined part.
    *
-   * @note Only <tt>Tvmult</tt> is
-   * used for these matrices.
+   * @note Only <tt>Tvmult</tt> is used for these matrices.
    */
   SmartPointer<const MGMatrixBase<VECTOR> > edge_in;
 
   /**
    * Edge matrix from fine to coarse.
    *
-   * @note Only <tt>vmult</tt> is
-   * used for these matrices.
+   * @note Only <tt>vmult</tt> is used for these matrices.
    */
   SmartPointer<const MGMatrixBase<VECTOR>,Multigrid<VECTOR> > edge_down;
 
   /**
    * Transpose edge matrix from coarse to fine.
    *
-   * @note Only <tt>Tvmult</tt> is
-   * used for these matrices.
+   * @note Only <tt>Tvmult</tt> is used for these matrices.
    */
   SmartPointer<const MGMatrixBase<VECTOR>,Multigrid<VECTOR> > edge_up;
 
   /**
-   * Level for debug
-   * output. Defaults to zero and
-   * can be set by set_debug().
+   * Level for debug output. Defaults to zero and can be set by set_debug().
    */
   unsigned int debug;
 
@@ -496,13 +370,13 @@ private:
 
 
 /**
- * Multi-level preconditioner.
- * Here, we collect all information needed for multi-level preconditioning
- * and provide the standard interface for LAC iterative methods.
+ * Multi-level preconditioner. Here, we collect all information needed for
+ * multi-level preconditioning and provide the standard interface for LAC
+ * iterative methods.
  *
- * Furthermore, it needs functions <tt>void copy_to_mg(const VECTOR&)</tt>
- * to store @p src in the right hand side of the multi-level method and
- * <tt>void copy_from_mg(VECTOR&)</tt> to store the result of the v-cycle in @p dst.
+ * Furthermore, it needs functions <tt>void copy_to_mg(const VECTOR&)</tt> to
+ * store @p src in the right hand side of the multi-level method and <tt>void
+ * copy_from_mg(VECTOR&)</tt> to store the result of the v-cycle in @p dst.
  *
  * @author Guido Kanschat, 1999, 2000, 2001, 2002
  */
@@ -511,10 +385,8 @@ class PreconditionMG : public Subscriptor
 {
 public:
   /**
-   * Constructor.
-   * Arguments are the multigrid object,
-   * pre-smoother, post-smoother and
-   * coarse grid solver.
+   * Constructor. Arguments are the multigrid object, pre-smoother, post-
+   * smoother and coarse grid solver.
    */
   PreconditionMG(const DoFHandler<dim>     &dof_handler,
                  Multigrid<VECTOR>           &mg,
@@ -526,23 +398,18 @@ public:
   bool empty () const;
 
   /**
-   * Preconditioning operator.
-   * Calls the @p vcycle function
-   * of the @p MG object passed to
-   * the constructor.
+   * Preconditioning operator. Calls the @p vcycle function of the @p MG
+   * object passed to the constructor.
    *
-   * This is the operator used by
-   * LAC iterative solvers.
+   * This is the operator used by LAC iterative solvers.
    */
   template<class VECTOR2>
   void vmult (VECTOR2       &dst,
               const VECTOR2 &src) const;
 
   /**
-   * Preconditioning operator.
-   * Calls the @p vcycle function
-   * of the @p MG object passed to
-   * the constructor.
+   * Preconditioning operator. Calls the @p vcycle function of the @p MG
+   * object passed to the constructor.
    */
   template<class VECTOR2>
   void vmult_add (VECTOR2       &dst,
@@ -551,8 +418,7 @@ public:
   /**
    * Tranposed preconditioning operator.
    *
-   * Not implemented, but the
-   * definition may be needed.
+   * Not implemented, but the definition may be needed.
    */
   template<class VECTOR2>
   void Tvmult (VECTOR2       &dst,
@@ -561,8 +427,7 @@ public:
   /**
    * Tranposed preconditioning operator.
    *
-   * Not implemented, but the
-   * definition may be needed.
+   * Not implemented, but the definition may be needed.
    */
   template<class VECTOR2>
   void Tvmult_add (VECTOR2       &dst,
index db05d33f61fbebc000099b0fa30cc08ef73777b1..db2cd9fa56566f019606cd516b6087acb7314724 100644 (file)
@@ -30,8 +30,8 @@ DEAL_II_NAMESPACE_OPEN
 namespace mg
 {
   /**
-   * Handler and storage for all five SparseMatrix object involved in
-   * using multigrid with local refinement.
+   * Handler and storage for all five SparseMatrix object involved in using
+   * multigrid with local refinement.
    *
    * @author Baerbel Janssen, Guido Kanschat
    * @date 2013
index ba88c9c1a1393b5e4ac72df784134b5d40ec0e0c..2a643098bb661d732716b3540cbc07f550409108 100644 (file)
@@ -29,47 +29,34 @@ DEAL_II_NAMESPACE_OPEN
 namespace DataComponentInterpretation
 {
   /**
-   * The members of this enum are used to
-   * describe the logical interpretation of
-   * what the various components of a
-   * vector-valued data set mean. For
-   * example, if one has a finite element
-   * for the Stokes equations in 2d,
-   * representing components $(u,v,p)$, one
-   * would like to indicate that the first
-   * two, $u$ and $v$, represent a logical
-   * vector so that later on when we
-   * generate graphical output we can hand
-   * them off to a visualization program
-   * that will automatically know to render
-   * them as a vector field, rather than as
-   * two separate and independent scalar
-   * fields.
+   * The members of this enum are used to describe the logical interpretation
+   * of what the various components of a vector-valued data set mean. For
+   * example, if one has a finite element for the Stokes equations in 2d,
+   * representing components $(u,v,p)$, one would like to indicate that the
+   * first two, $u$ and $v$, represent a logical vector so that later on when
+   * we generate graphical output we can hand them off to a visualization
+   * program that will automatically know to render them as a vector field,
+   * rather than as two separate and independent scalar fields.
    *
-   * By passing a set of enums of the
-   * current kind to the
-   * DataOut_DoFData::add_data_vector
-   * functions, this can be achieved.
+   * By passing a set of enums of the current kind to the
+   * DataOut_DoFData::add_data_vector functions, this can be achieved.
    *
-   * See the step-22 tutorial
-   * program for an example on how this
-   * information can be used in practice.
+   * See the step-22 tutorial program for an example on how this information
+   * can be used in practice.
    *
    * @author Wolfgang Bangerth, 2007
    */
   enum DataComponentInterpretation
   {
     /**
-     * Indicates that a component of a
-     * data set corresponds to a scalar
-     * field independent of the others.
+     * Indicates that a component of a data set corresponds to a scalar field
+     * independent of the others.
      */
     component_is_scalar,
 
     /**
-     * Indicates that a component of a
-     * data set is part of a
-     * vector-valued quantity.
+     * Indicates that a component of a data set is part of a vector-valued
+     * quantity.
      */
     component_is_part_of_vector
   };
index fb7024ecd1a0935bd7379c862f20c60df558dabb..1288722fc1fad0fff4925856e74c29693380d8fa 100644 (file)
@@ -60,11 +60,11 @@ namespace internal
  * This class is the main class to provide output of data described by finite
  * element fields defined on a collection of cells.
  *
- * This class is an actual implementation of the functionality proposed by
- * the DataOut_DoFData class. It offers a function build_patches() that
- * generates the patches to be written in some graphics format from the data
- * stored in the base class. Most of the interface and an example of its
- * use is described in the documentation of the base class.
+ * This class is an actual implementation of the functionality proposed by the
+ * DataOut_DoFData class. It offers a function build_patches() that generates
+ * the patches to be written in some graphics format from the data stored in
+ * the base class. Most of the interface and an example of its use is
+ * described in the documentation of the base class.
  *
  * The only thing this class offers is the function build_patches() which
  * loops over all cells of the triangulation stored by the
@@ -90,22 +90,21 @@ namespace internal
  * mesh.
  *
  * Note that after having called build_patches() once, you can call one or
- * more of the write() functions of DataOutInterface. You can therefore
- * output the same data in more than one format without having to rebuild
- * the patches.
+ * more of the write() functions of DataOutInterface. You can therefore output
+ * the same data in more than one format without having to rebuild the
+ * patches.
  *
  *
  * <h3>User interface information</h3>
  *
  * The base classes of this class, DataOutBase, DataOutInterface and
  * DataOut_DoFData() offer several interfaces of their own. Refer to the
- * DataOutBase class's documentation for a discussion of the different
- * output formats presently supported, DataOutInterface for ways of
- * selecting which format to use upon output at run-time and without
- * the need to adapt your program when new formats become available, as
- * well as for flags to determine aspects of output. The DataOut_DoFData()
- * class's documentation has an example of using nodal data to generate
- * output.
+ * DataOutBase class's documentation for a discussion of the different output
+ * formats presently supported, DataOutInterface for ways of selecting which
+ * format to use upon output at run-time and without the need to adapt your
+ * program when new formats become available, as well as for flags to
+ * determine aspects of output. The DataOut_DoFData() class's documentation
+ * has an example of using nodal data to generate output.
  *
  *
  * <h3>Extensions</h3>
@@ -116,24 +115,23 @@ namespace internal
  * region of the domain (for example in parallel programs such as the step-18
  * example program), or for some other reason.
  *
- * For this, internally build_patches() does not generate
- * the sequence of cells to be converted into patches itself, but relies
- * on the two functions first_cell() and next_cell(). By default, they
- * return the first active cell, and the next active cell, respectively.
- * Since they are @p virtual functions, you can write your own class
- * derived from DataOut in which you overload these two functions to select other
- * cells for output. This may, for example, include only cells that are
- * in parts of a domain (e.g., if you don't care about the solution elsewhere,
- * think for example a buffer region in which you attenuate outgoing waves
- * in the Perfectly Matched Layer method) or if you don't want output to
- * be generated at all levels of an adaptively refined mesh because this
- * creates too much data (in this case, the set of cells returned by
- * your implementations of first_cell() and next_cell() will include
- * non-active cells, and DataOut::build_patches() will simply take
- * interpolated values of the solution instead of the exact values on these
- * cells children for output). Once you derive your own class, you would
- * just create an object of this type instead of an object of type DataOut,
- * and everything else will remain the same.
+ * For this, internally build_patches() does not generate the sequence of
+ * cells to be converted into patches itself, but relies on the two functions
+ * first_cell() and next_cell(). By default, they return the first active
+ * cell, and the next active cell, respectively. Since they are @p virtual
+ * functions, you can write your own class derived from DataOut in which you
+ * overload these two functions to select other cells for output. This may,
+ * for example, include only cells that are in parts of a domain (e.g., if you
+ * don't care about the solution elsewhere, think for example a buffer region
+ * in which you attenuate outgoing waves in the Perfectly Matched Layer
+ * method) or if you don't want output to be generated at all levels of an
+ * adaptively refined mesh because this creates too much data (in this case,
+ * the set of cells returned by your implementations of first_cell() and
+ * next_cell() will include non-active cells, and DataOut::build_patches()
+ * will simply take interpolated values of the solution instead of the exact
+ * values on these cells children for output). Once you derive your own class,
+ * you would just create an object of this type instead of an object of type
+ * DataOut, and everything else will remain the same.
  *
  * The two functions are not constant, so you may store information within
  * your derived class about the last accessed cell. This is useful if the
@@ -147,12 +145,12 @@ namespace internal
  * this pair of functions and they return a non-active cell, then an exception
  * will be thrown.
  *
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
  *
  * @ingroup output
  * @author Wolfgang Bangerth, 1999
@@ -196,9 +194,9 @@ public:
    * which originate from cells at the boundary of the domain can be computed
    * using the mapping, i.e. a higher order mapping leads to a representation
    * of a curved boundary by using more subdivisions. Some mappings like
-   * MappingQEulerian result in curved cells in the interior of the
-   * domain. However, there is nor easy way to get this information from the
-   * Mapping. Thus the last argument @p curved_region take one of three values
+   * MappingQEulerian result in curved cells in the interior of the domain.
+   * However, there is nor easy way to get this information from the Mapping.
+   * Thus the last argument @p curved_region take one of three values
    * resulting in no curved cells at all, curved cells at the boundary
    * (default) or curved cells in the whole domain.
    *
index e5e7a4ed6b11928f0476d01561da2408c71c7488..8f65125a1b524e868c7137f658f5aba99631b3ae 100644 (file)
@@ -48,9 +48,9 @@ namespace internal
      * do this for a number of different vector types. Fortunately, they all
      * have the same interface. So the way we go is to have a base class that
      * provides the functions to access the vector's information, and to have
-     * a derived template class that can be instantiated for each vector
-     * type. Since the vectors all have the same interface, this is no big
-     * problem, as they can all use the same general templatized code.
+     * a derived template class that can be instantiated for each vector type.
+     * Since the vectors all have the same interface, this is no big problem,
+     * as they can all use the same general templatized code.
      *
      * @author Wolfgang Bangerth, 2004
      */
@@ -295,105 +295,99 @@ namespace internal
  *   data_out.clear();
  * @endcode
  *
- * attach_dof_handler() tells this class that all future operations
- * are to take place with the DoFHandler object and the triangulation
- * it lives on. We then add the solution vector and the error
- * estimator; note that they have different dimensions, because the
- * solution is a nodal vector, here consisting of two components
- * ("x-displacement" and "y-displacement") while the error estimator
- * probably is a vector holding cell data. When attaching a data
- * vector, you have to give a name to each component of the vector,
- * which is done through an object of type <tt>vector<string></tt> as
- * second argument; if only one component is in the vector, for
- * example if we are adding cell data as in the second case, or if the
- * finite element used by the DoFHandler has only one component, then
- * you can use the second add_data_vector() function which takes a @p
- * string instead of the <tt>vector<string></tt>.
+ * attach_dof_handler() tells this class that all future operations are to
+ * take place with the DoFHandler object and the triangulation it lives on. We
+ * then add the solution vector and the error estimator; note that they have
+ * different dimensions, because the solution is a nodal vector, here
+ * consisting of two components ("x-displacement" and "y-displacement") while
+ * the error estimator probably is a vector holding cell data. When attaching
+ * a data vector, you have to give a name to each component of the vector,
+ * which is done through an object of type <tt>vector<string></tt> as second
+ * argument; if only one component is in the vector, for example if we are
+ * adding cell data as in the second case, or if the finite element used by
+ * the DoFHandler has only one component, then you can use the second
+ * add_data_vector() function which takes a @p string instead of the
+ * <tt>vector<string></tt>.
  *
  * The add_data_vector() functions have additional arguments (with default
  * values) that can be used to specify certain transformations. In particular,
  * it allows to attach DataPostprocessor arguments to compute derived
- * information from a data vector at each point at which the field will
- * be evaluated so that it can be written to a file (for example, the
- * Mach number in hypersonic flow can be computed from density and velocities;
- * step-29 also shows an example); another piece of information
- * specified through arguments with default values is how certain output
- * components should be interpreted, i.e. whether each component of the data
- * is logically an independent scalar field, or whether some of them together
- * form logically a vector-field (see the
+ * information from a data vector at each point at which the field will be
+ * evaluated so that it can be written to a file (for example, the Mach number
+ * in hypersonic flow can be computed from density and velocities; step-29
+ * also shows an example); another piece of information specified through
+ * arguments with default values is how certain output components should be
+ * interpreted, i.e. whether each component of the data is logically an
+ * independent scalar field, or whether some of them together form logically a
+ * vector-field (see the
  * DataComponentInterpretation::DataComponentInterpretation enum, and the @ref
  * step_22 "step-22" tutorial program).
  *
- * It should be noted that this class does not copy the vector given to it through
- * the add_data_vector() functions, for memory consumption reasons. It only
- * stores a reference to it, so it is in your responsibility to make sure that
- * the data vectors exist long enough.
+ * It should be noted that this class does not copy the vector given to it
+ * through the add_data_vector() functions, for memory consumption reasons. It
+ * only stores a reference to it, so it is in your responsibility to make sure
+ * that the data vectors exist long enough.
  *
  * After adding all data vectors, you need to call a function which generates
  * the patches for output from the stored data. Derived classes name this
- * function build_patches(). Finally, you write() the data in one format or other,
- * to a file.
+ * function build_patches(). Finally, you write() the data in one format or
+ * other, to a file.
  *
- * Please note that in the example above, an object of type DataOut was
- * used, i.e. an object of a derived class. This is necessary since this
- * class does not provide means to actually generate the patches, only aids to
- * store and access data.
+ * Please note that in the example above, an object of type DataOut was used,
+ * i.e. an object of a derived class. This is necessary since this class does
+ * not provide means to actually generate the patches, only aids to store and
+ * access data.
  *
- * Note that the base class of this class, DataOutInterface offers
- * several functions to ease programming with run-time determinable
- * output formats (i.e. you need not use a fixed format by calling
- * DataOutInterface::write_xxx in the above example, but you can
- * select it by a run-time parameter without having to write the
- * <tt>if () ... else ...</tt> clauses yourself), and also functions
- * and classes offering ways to control the appearance of the output
- * by setting flags for each output format.
+ * Note that the base class of this class, DataOutInterface offers several
+ * functions to ease programming with run-time determinable output formats
+ * (i.e. you need not use a fixed format by calling
+ * DataOutInterface::write_xxx in the above example, but you can select it by
+ * a run-time parameter without having to write the <tt>if () ... else
+ * ...</tt> clauses yourself), and also functions and classes offering ways to
+ * control the appearance of the output by setting flags for each output
+ * format.
  *
  *
  * <h3>Information for derived classes</h3>
  *
- * What is actually missing this class is a way to produce the patches
- * for output itself, from the stored data and degree of freedom
- * information.  Since this task is often application dependent it is
- * left to derived classes. For example, in many applications, it
- * might be wanted to limit the depth of output to a certain number of
- * refinement levels and write data from finer cells only in a way
- * interpolated to coarser cells, to reduce the amount of
- * output. Also, it might be wanted to use different numbers of
- * subdivisions on different cells when forming a patch, for example
- * to accomplish for different polynomial degrees of the trial space
- * on different cells. Also, the output need not necessarily consist
- * of a patch for each cell, but might be made up of patches for
- * faces, of other things. Take a look at derived classes to what is
- * possible in this respect.
+ * What is actually missing this class is a way to produce the patches for
+ * output itself, from the stored data and degree of freedom information.
+ * Since this task is often application dependent it is left to derived
+ * classes. For example, in many applications, it might be wanted to limit the
+ * depth of output to a certain number of refinement levels and write data
+ * from finer cells only in a way interpolated to coarser cells, to reduce the
+ * amount of output. Also, it might be wanted to use different numbers of
+ * subdivisions on different cells when forming a patch, for example to
+ * accomplish for different polynomial degrees of the trial space on different
+ * cells. Also, the output need not necessarily consist of a patch for each
+ * cell, but might be made up of patches for faces, of other things. Take a
+ * look at derived classes to what is possible in this respect.
  *
- * For this reason, it is left to a derived class to provide a
- * function, named usually build_patches() or the like, which fills
- * the #patches array of this class.
+ * For this reason, it is left to a derived class to provide a function, named
+ * usually build_patches() or the like, which fills the #patches array of this
+ * class.
  *
- * Regarding the templates of this class, it needs three values: first
- * the space dimension in which the triangulation and the DoF handler
- * operate, second the dimension of the objects which the patches
- * represent.  Although in most cases they are equal, there are also
- * classes for which this does not hold, for example if one outputs
- * the result of a computation exploiting rotational symmetry in the
- * original domain (in which the space dimension of the output would
- * be one higher than that of the DoF handler, see the
- * DataOut_Rotation() class), or one might conceive that one could
- * write a class that only outputs the solution on a cut through the
- * domain, in which case the space dimension of the output is less
- * than that of the DoF handler. The last template argument denotes
- * the dimension of the space into which the patches are embedded;
- * usually, this dimension is the same as the dimensio of the patches
- * themselves (which is also the default value of the template
- * parameter), but there might be cases where this is not so. For
- * example, in the DataOut_Faces() class, patches are generated
- * from faces of the triangulation. Thus, the dimension of the patch
- * is one less than the dimension of the embedding space, which is, in
- * this case, equal to the dimension of the triangulation and DoF
- * handler. However, for the cut through the domain mentioned above,
- * if the cut is a straight one, then the cut can be embedded into a
- * space of one dimension lower than the dimension of the
- * triangulation, so that the last template parameter has the same
+ * Regarding the templates of this class, it needs three values: first the
+ * space dimension in which the triangulation and the DoF handler operate,
+ * second the dimension of the objects which the patches represent.  Although
+ * in most cases they are equal, there are also classes for which this does
+ * not hold, for example if one outputs the result of a computation exploiting
+ * rotational symmetry in the original domain (in which the space dimension of
+ * the output would be one higher than that of the DoF handler, see the
+ * DataOut_Rotation() class), or one might conceive that one could write a
+ * class that only outputs the solution on a cut through the domain, in which
+ * case the space dimension of the output is less than that of the DoF
+ * handler. The last template argument denotes the dimension of the space into
+ * which the patches are embedded; usually, this dimension is the same as the
+ * dimensio of the patches themselves (which is also the default value of the
+ * template parameter), but there might be cases where this is not so. For
+ * example, in the DataOut_Faces() class, patches are generated from faces of
+ * the triangulation. Thus, the dimension of the patch is one less than the
+ * dimension of the embedding space, which is, in this case, equal to the
+ * dimension of the triangulation and DoF handler. However, for the cut
+ * through the domain mentioned above, if the cut is a straight one, then the
+ * cut can be embedded into a space of one dimension lower than the dimension
+ * of the triangulation, so that the last template parameter has the same
  * value as the second one.
  *
  * @ingroup output
@@ -464,9 +458,9 @@ public:
    * mapping between nodes and node values.
    *
    * This call is optional: If you add data vectors with specified DoFHandler
-   * object, then that contains all information needed to generate the
-   * output. This call is useful when you only output cell vectors and no
-   * DoFHandler at all, in which case it provides the geometry.
+   * object, then that contains all information needed to generate the output.
+   * This call is useful when you only output cell vectors and no DoFHandler
+   * at all, in which case it provides the geometry.
    */
   void attach_triangulation (const Triangulation<DH::dimension,
                              DH::space_dimension> &);
@@ -487,16 +481,16 @@ public:
    * given. However, there are corner cases where this automatic determination
    * does not work.  One example is if you compute with piecewise constant
    * elements and have a scalar solution, then there are as many cells as
-   * there are degrees of freedom (though they may be numbered
-   * differently). Another possibility is if you have a 1d mesh embedded in 2d
-   * space and the mesh consists of a closed curve of cells; in this case,
-   * there are as many nodes as there are cells, and when using a Q1 element
-   * you will have as many degrees of freedom as there are cells.  In these
-   * cases, you can change the last argument of the function from its default
-   * value #type_automatic to either #type_dof_data or #type_cell_data,
-   * depending on what the vector represents. Apart from such corner cases,
-   * you can leave the argument at its default value and let the function
-   * determine the type of the vector itself.
+   * there are degrees of freedom (though they may be numbered differently).
+   * Another possibility is if you have a 1d mesh embedded in 2d space and the
+   * mesh consists of a closed curve of cells; in this case, there are as many
+   * nodes as there are cells, and when using a Q1 element you will have as
+   * many degrees of freedom as there are cells.  In these cases, you can
+   * change the last argument of the function from its default value
+   * #type_automatic to either #type_dof_data or #type_cell_data, depending on
+   * what the vector represents. Apart from such corner cases, you can leave
+   * the argument at its default value and let the function determine the type
+   * of the vector itself.
    *
    * If it is a vector holding DoF data, the names given shall be one for each
    * component of the underlying finite element.  If it is a finite element
@@ -519,9 +513,8 @@ public:
    * DataComponentInterpretation::component_is_scalar, indicating that all
    * output components are independent scalar fields. However, if the given
    * data vector represents logical vectors, you may pass a vector that
-   * contains values
-   * DataComponentInterpretation::component_is_part_of_vector. In the example
-   * above, one would pass in a vector with components
+   * contains values DataComponentInterpretation::component_is_part_of_vector.
+   * In the example above, one would pass in a vector with components
    * (DataComponentInterpretation::component_is_part_of_vector,
    * DataComponentInterpretation::component_is_part_of_vector,
    * DataComponentInterpretation::component_is_scalar) for (u,v,p).
@@ -619,12 +612,12 @@ public:
    * includes all of the usual vector types, but also IndexSet (see step-41
    * for a use of this).
    *
-   * @note The DataPostprocessor object (i.e., in reality the object of your derived
-   * class) has to live until the DataOut object is destroyed as the latter keeps
-   * a pointer to the former and will complain if the object pointed to is
-   * destroyed while the latter still has a pointer to it. If both the data
-   * postprocessor and DataOut objects are local variables of a function
-   * (as they are, for example, in step-29), then you can avoid this
+   * @note The DataPostprocessor object (i.e., in reality the object of your
+   * derived class) has to live until the DataOut object is destroyed as the
+   * latter keeps a pointer to the former and will complain if the object
+   * pointed to is destroyed while the latter still has a pointer to it. If
+   * both the data postprocessor and DataOut objects are local variables of a
+   * function (as they are, for example, in step-29), then you can avoid this
    * error by declaring the data postprocessor variable before the DataOut
    * variable as objects are destroyed in reverse order of declaration.
    */
@@ -693,8 +686,8 @@ public:
   /**
    * Release the pointers to the data vectors and the DoF handler. You have to
    * set all data entries again using the add_data_vector() function. The
-   * pointer to the dof handler is cleared as well, along with all other
-   * data. In effect, this function resets everything to a virgin state.
+   * pointer to the dof handler is cleared as well, along with all other data.
+   * In effect, this function resets everything to a virgin state.
    */
   virtual void clear ();
 
index a9b3df8f2f8a2a251dd911b880ad47f4ccc79e2e..16f5c88c8267554d0f4324d2a0410a91b3208d6e 100644 (file)
@@ -31,13 +31,9 @@ namespace internal
   namespace DataOutFaces
   {
     /**
-     * A derived class for use in the
-     * DataOutFaces class. This is
-     * a class for the
-     * AdditionalData kind of data
-     * structure discussed in the
-     * documentation of the
-     * WorkStream context.
+     * A derived class for use in the DataOutFaces class. This is a class for
+     * the AdditionalData kind of data structure discussed in the
+     * documentation of the WorkStream context.
      */
     template <int dim, int spacedim>
     struct ParallelData : public internal::DataOut::ParallelDataBase<dim,spacedim>
@@ -57,64 +53,59 @@ namespace internal
 
 
 /**
- * This class generates output from faces of a triangulation. It might
- * be used to generate output only for the surface of the
- * triangulation (this is the default of this class), or for all faces
- * of active cells, as specified in the constructor.
- * The output of this class is a set of
- * patches (as defined by the class DataOutBase::Patch()), one for
- * each face for which output is to be generated. These patches can
- * then be written in several graphical data formats by the functions
- * of the underlying classes.
+ * This class generates output from faces of a triangulation. It might be used
+ * to generate output only for the surface of the triangulation (this is the
+ * default of this class), or for all faces of active cells, as specified in
+ * the constructor. The output of this class is a set of patches (as defined
+ * by the class DataOutBase::Patch()), one for each face for which output is
+ * to be generated. These patches can then be written in several graphical
+ * data formats by the functions of the underlying classes.
  *
  * <h3>Interface</h3>
  *
- * The interface of this class is copied from the DataOut
- * class. Furthermore, they share the common parent class
- * DataOut_DoFData. See the reference of these two classes for a
- * discussion of the interface.
+ * The interface of this class is copied from the DataOut class. Furthermore,
+ * they share the common parent class DataOut_DoFData. See the reference of
+ * these two classes for a discussion of the interface.
  *
  *
  * <h3>Extending this class</h3>
  *
- * The sequence of faces to generate patches from is generated in the
- * same way as in the DataOut class; see there for a description of
- * the respective interface. The functions generating the sequence of
- * faces which shall be used to generate output, are called
- * first_face() and next_face().
+ * The sequence of faces to generate patches from is generated in the same way
+ * as in the DataOut class; see there for a description of the respective
+ * interface. The functions generating the sequence of faces which shall be
+ * used to generate output, are called first_face() and next_face().
  *
- * Since we need to initialize objects of type FEValues with the
- * faces generated from these functions, it is not sufficient that
- * they only return face iterators. Rather, we need a pair of cell and
- * the number of the face, as the values of finite element fields need
- * not necessarily be unique on a face (think of discontinuous finite
- * elements, where the value of the finite element field depend on the
- * direction from which you approach a face, thus it is necessary to
- * use a pair of cell and face, rather than only a face
- * iterator). Therefore, this class defines a @p typedef which
- * creates a type @p FaceDescriptor that is an abbreviation for a
- * pair of cell iterator and face number. The functions @p first_face
- * and @p next_face operate on objects of this type.
+ * Since we need to initialize objects of type FEValues with the faces
+ * generated from these functions, it is not sufficient that they only return
+ * face iterators. Rather, we need a pair of cell and the number of the face,
+ * as the values of finite element fields need not necessarily be unique on a
+ * face (think of discontinuous finite elements, where the value of the finite
+ * element field depend on the direction from which you approach a face, thus
+ * it is necessary to use a pair of cell and face, rather than only a face
+ * iterator). Therefore, this class defines a @p typedef which creates a type
+ * @p FaceDescriptor that is an abbreviation for a pair of cell iterator and
+ * face number. The functions @p first_face and @p next_face operate on
+ * objects of this type.
  *
- * Extending this class might, for example, be useful if you only want
- * output from certain portions of the boundary, e.g. as indicated by
- * the boundary indicator of the respective faces. However, it is also
- * conceivable that one generates patches not from boundary faces, but
- * from interior faces that are selected due to other criteria; one
- * application might be to use only those faces where one component of
- * the solution attains a certain value, in order to display the
- * values of other solution components on these faces. Other
- * applications certainly exist, for which the author is not
- * imaginative enough.
+ * Extending this class might, for example, be useful if you only want output
+ * from certain portions of the boundary, e.g. as indicated by the boundary
+ * indicator of the respective faces. However, it is also conceivable that one
+ * generates patches not from boundary faces, but from interior faces that are
+ * selected due to other criteria; one application might be to use only those
+ * faces where one component of the solution attains a certain value, in order
+ * to display the values of other solution components on these faces. Other
+ * applications certainly exist, for which the author is not imaginative
+ * enough.
  *
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
  *
- * @todo Reimplement this whole class using actual FEFaceValues and MeshWorker.
+ * @todo Reimplement this whole class using actual FEFaceValues and
+ * MeshWorker.
  *
  * @ingroup output
  * @author Wolfgang Bangerth, Guido Kanschat, 2000, 2011
@@ -125,8 +116,8 @@ class DataOutFaces : public DataOut_DoFData<DH,DH::dimension-1,
 {
 public:
   /**
-   * An abbreviation for the dimension of the DoFHandler object we work
-   * with. Faces are then <code>dimension-1</code> dimensional objects.
+   * An abbreviation for the dimension of the DoFHandler object we work with.
+   * Faces are then <code>dimension-1</code> dimensional objects.
    */
   static const unsigned int dimension = DH::dimension;
 
@@ -137,148 +128,87 @@ public:
   static const unsigned int space_dimension = DH::space_dimension;
 
   /**
-   * Typedef to the iterator type
-   * of the dof handler class under
+   * Typedef to the iterator type of the dof handler class under
    * consideration.
    */
   typedef typename DataOut_DoFData<DH,dimension-1,
           dimension>::cell_iterator cell_iterator;
 
   /**
-   * Constructor determining
-   * whether a surface mesh
-   * (default) or the whole wire
-   * basket is written.
+   * Constructor determining whether a surface mesh (default) or the whole
+   * wire basket is written.
    */
   DataOutFaces (const bool surface_only = true);
 
   /**
-   * This is the central function
-   * of this class since it builds
-   * the list of patches to be
-   * written by the low-level
-   * functions of the base
-   * class. See the general
-   * documentation of this class
-   * for further information.
+   * This is the central function of this class since it builds the list of
+   * patches to be written by the low-level functions of the base class. See
+   * the general documentation of this class for further information.
    *
-   * The function supports
-   * multithreading, if deal.II is
-   * compiled in multithreading
-   * mode.
+   * The function supports multithreading, if deal.II is compiled in
+   * multithreading mode.
    */
   virtual void
   build_patches (const unsigned int n_subdivisions = 0);
 
   /**
-   * Same as above, except that the
-   * additional first parameter
-   * defines a mapping that is to
-   * be used in the generation of
-   * output. If
-   * <tt>n_subdivisions>1</tt>, the
-   * points interior of subdivided
-   * patches which originate from
-   * cells at the boundary of the
-   * domain can be computed using the
-   * mapping, i.e. a higher order
-   * mapping leads to a
-   * representation of a curved
-   * boundary by using more
-   * subdivisions.
+   * Same as above, except that the additional first parameter defines a
+   * mapping that is to be used in the generation of output. If
+   * <tt>n_subdivisions>1</tt>, the points interior of subdivided patches
+   * which originate from cells at the boundary of the domain can be computed
+   * using the mapping, i.e. a higher order mapping leads to a representation
+   * of a curved boundary by using more subdivisions.
    *
-   * Even for non-curved cells the
-   * mapping argument can be used
-   * for the Eulerian mappings (see
-   * class MappingQ1Eulerian) where
-   * a mapping is used not only to
-   * determine the position of
-   * points interior to a cell, but
-   * also of the vertices.  It
-   * offers an opportunity to watch
-   * the solution on a deformed
-   * triangulation on which the
-   * computation was actually
-   * carried out, even if the mesh
-   * is internally stored in its
-   * undeformed configuration and
-   * the deformation is only
-   * tracked by an additional
-   * vector that holds the
+   * Even for non-curved cells the mapping argument can be used for the
+   * Eulerian mappings (see class MappingQ1Eulerian) where a mapping is used
+   * not only to determine the position of points interior to a cell, but also
+   * of the vertices.  It offers an opportunity to watch the solution on a
+   * deformed triangulation on which the computation was actually carried out,
+   * even if the mesh is internally stored in its undeformed configuration and
+   * the deformation is only tracked by an additional vector that holds the
    * deformation of each vertex.
    *
-   * @todo The @p mapping argument should be
-   * replaced by a hp::MappingCollection in
-   * case of a hp::DoFHandler.
+   * @todo The @p mapping argument should be replaced by a
+   * hp::MappingCollection in case of a hp::DoFHandler.
    */
   virtual void build_patches (const Mapping<dimension> &mapping,
                               const unsigned int n_subdivisions = 0);
 
   /**
-   * Declare a way to describe a
-   * face which we would like to
-   * generate output for. The usual
-   * way would, of course, be to
-   * use an object of type
-   * <tt>DoFHandler<dim>::face_iterator</tt>,
-   * but since we have to describe
-   * faces to objects of type
-   * FEValues, we can only
-   * represent faces by pairs of a
-   * cell and the number of the
-   * face. This pair is here
-   * aliased to a name that is
-   * better to type.
+   * Declare a way to describe a face which we would like to generate output
+   * for. The usual way would, of course, be to use an object of type
+   * <tt>DoFHandler<dim>::face_iterator</tt>, but since we have to describe
+   * faces to objects of type FEValues, we can only represent faces by pairs
+   * of a cell and the number of the face. This pair is here aliased to a name
+   * that is better to type.
    */
   typedef typename std::pair<cell_iterator,unsigned int> FaceDescriptor;
 
 
   /**
-   * Return the first face which we
-   * want output for. The default
-   * implementation returns the
-   * first face of an active cell
-   * or the first such on the
-   * boundary.
+   * Return the first face which we want output for. The default
+   * implementation returns the first face of an active cell or the first such
+   * on the boundary.
    *
-   * For more general sets,
-   * overload this function in a
-   * derived class.
+   * For more general sets, overload this function in a derived class.
    */
   virtual FaceDescriptor first_face ();
 
   /**
-   * Return the next face after
-   * which we want output
-   * for. If there are no more
-   * faces, <tt>dofs->end()</tt> is
-   * returned as the first
-   * component of the return value.
+   * Return the next face after which we want output for. If there are no more
+   * faces, <tt>dofs->end()</tt> is returned as the first component of the
+   * return value.
    *
-   * The default implementation
-   * returns the next face of an
-   * active cell, or the next such
-   * on the boundary.
+   * The default implementation returns the next face of an active cell, or
+   * the next such on the boundary.
    *
-   * This function traverses the
-   * mesh cell by cell (active
-   * only), and then through all
-   * faces of the cell. As a
-   * result, interior faces are
-   * output twice.
-
-   * This function can be
-   * overloaded in a derived
-   * class to select a different
-   * set of faces. Note that the
-   * default implementation assumes
-   * that the given @p face is
-   * active, which is guaranteed as
-   * long as first_face() is also
-   * used from the default
-   * implementation. Overloading
-   * only one of the two functions
-   * should be done with care.
+   * This function traverses the mesh cell by cell (active only), and then
+   * through all faces of the cell. As a result, interior faces are output
+   * twice.  This function can be overloaded in a derived class to select a
+   * different set of faces. Note that the default implementation assumes that
+   * the given @p face is active, which is guaranteed as long as first_face()
+   * is also used from the default implementation. Overloading only one of the
+   * two functions should be done with care.
    */
   virtual FaceDescriptor next_face (const FaceDescriptor &face);
 
@@ -297,16 +227,12 @@ public:
 
 private:
   /**
-   * Parameter deciding between
-   * surface meshes and full wire
-   * basket.
+   * Parameter deciding between surface meshes and full wire basket.
    */
   const bool surface_only;
 
   /**
-   * Build one patch. This function
-   * is called in a WorkStream
-   * context.
+   * Build one patch. This function is called in a WorkStream context.
    */
   void build_one_patch (const FaceDescriptor *cell_and_face,
                         internal::DataOutFaces::ParallelData<dimension, dimension> &data,
index 593a520ffece10e0304fd16303e204441a30d2c1..c32261a021504a112f8b2da5a77b9db2b2629363 100644 (file)
@@ -31,13 +31,9 @@ namespace internal
   namespace DataOutRotation
   {
     /**
-     * A derived class for use in the
-     * DataOutFaces class. This is
-     * a class for the
-     * AdditionalData kind of data
-     * structure discussed in the
-     * documentation of the
-     * WorkStream class.
+     * A derived class for use in the DataOutFaces class. This is a class for
+     * the AdditionalData kind of data structure discussed in the
+     * documentation of the WorkStream class.
      */
     template <int dim, int spacedim>
     struct ParallelData : public internal::DataOut::ParallelDataBase<dim,spacedim>
@@ -60,65 +56,61 @@ namespace internal
 
 
 /**
- * This class generates output in the full domain of computations that
- * were done using rotational symmetry of domain and solution. In
- * particular, if a computation of a three dimensional problem with
- * rotational symmetry around the @p z-axis (i.e. in the
- * @p r-z-plane) was done, then this class can be used to generate
- * the output in the original @p x-y-z space. In order to do so, it
- * generates from each cell in the computational mesh a cell in the
- * space with dimension one greater than that of the DoFHandler
- * object. The resulting output will then consist of hexahedra forming
- * an object that has rotational symmetry around the z-axis. As most
- * graphical programs can not represent ring-like structures, the
- * angular (rotation) variable is discretized into a finite number of
- * intervals as well; the number of these intervals must be given to
- * the @p build_patches function. It is noted, however, that while
- * this function generates nice pictures of the whole domain, it often
- * produces <em>very</em> large output files.
+ * This class generates output in the full domain of computations that were
+ * done using rotational symmetry of domain and solution. In particular, if a
+ * computation of a three dimensional problem with rotational symmetry around
+ * the @p z-axis (i.e. in the @p r-z-plane) was done, then this class can be
+ * used to generate the output in the original @p x-y-z space. In order to do
+ * so, it generates from each cell in the computational mesh a cell in the
+ * space with dimension one greater than that of the DoFHandler object. The
+ * resulting output will then consist of hexahedra forming an object that has
+ * rotational symmetry around the z-axis. As most graphical programs can not
+ * represent ring-like structures, the angular (rotation) variable is
+ * discretized into a finite number of intervals as well; the number of these
+ * intervals must be given to the @p build_patches function. It is noted,
+ * however, that while this function generates nice pictures of the whole
+ * domain, it often produces <em>very</em> large output files.
  *
  *
  * <h3>Interface</h3>
  *
- * The interface of this class is copied from the DataOut
- * class. Furthermore, they share the common parent class
- * DataOut_DoFData(). See the reference of these two classes for a
- * discussion of the interface and how to extend it by deriving
- * further classes from this class.
+ * The interface of this class is copied from the DataOut class. Furthermore,
+ * they share the common parent class DataOut_DoFData(). See the reference of
+ * these two classes for a discussion of the interface and how to extend it by
+ * deriving further classes from this class.
  *
  *
  * <h3>Details for 1d computations</h3>
  *
- * The one coordinate in the triangulation used by the
- * DoFHandler object passed to this class is taken as the radial
- * variable, and the output will then be either a circle or a ring
- * domain. It is in the user's responsibility to assure that the
- * radial coordinate only attains non-negative values.
+ * The one coordinate in the triangulation used by the DoFHandler object
+ * passed to this class is taken as the radial variable, and the output will
+ * then be either a circle or a ring domain. It is in the user's
+ * responsibility to assure that the radial coordinate only attains non-
+ * negative values.
  *
  *
  * <h3>Details for 2d computations</h3>
  *
- * We consider the computation (represented by the DoFHandler
- * object that is attached to this class) to have happened in the
- * @p r-z-plane, where @p r is the radial variable and @p z denotes
- * the axis of revolution around which the solution is symmetric. The
- * output is in @p x-y-z space, where the radial dependence is
- * transformed to the @p x-y plane. At present, it is not possible to
- * exchange the meaning of the first and second variable of the plane
- * in which the simulation was made, i.e. generate output from a
- * simulation where the first variable denoted the symmetry axis, and
- * the second denoted the radial variable. You have to take that into
- * account when first programming your application.
+ * We consider the computation (represented by the DoFHandler object that is
+ * attached to this class) to have happened in the @p r-z-plane, where @p r is
+ * the radial variable and @p z denotes the axis of revolution around which
+ * the solution is symmetric. The output is in @p x-y-z space, where the
+ * radial dependence is transformed to the @p x-y plane. At present, it is not
+ * possible to exchange the meaning of the first and second variable of the
+ * plane in which the simulation was made, i.e. generate output from a
+ * simulation where the first variable denoted the symmetry axis, and the
+ * second denoted the radial variable. You have to take that into account when
+ * first programming your application.
  *
- * It is in the responsibility of the user to make sure that the
- * radial variable attains only non-negative values.
+ * It is in the responsibility of the user to make sure that the radial
+ * variable attains only non-negative values.
  *
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
  *
  * @ingroup output
  * @author Wolfgang Bangerth, 2000
@@ -128,8 +120,8 @@ class DataOutRotation : public DataOut_DoFData<DH,DH::dimension+1>
 {
 public:
   /**
-   * An abbreviation for the dimension of the DoFHandler object we work
-   * with. Faces are then <code>dimension-1</code> dimensional objects.
+   * An abbreviation for the dimension of the DoFHandler object we work with.
+   * Faces are then <code>dimension-1</code> dimensional objects.
    */
   static const unsigned int dimension = DH::dimension;
 
@@ -140,68 +132,43 @@ public:
   static const unsigned int space_dimension = DH::space_dimension;
 
   /**
-   * Typedef to the iterator type
-   * of the dof handler class under
+   * Typedef to the iterator type of the dof handler class under
    * consideration.
    */
   typedef typename DataOut_DoFData<DH,dimension+1>::cell_iterator cell_iterator;
 
   /**
-   * This is the central function
-   * of this class since it builds
-   * the list of patches to be
-   * written by the low-level
-   * functions of the base
-   * class. See the general
-   * documentation of this class
-   * for further information.
+   * This is the central function of this class since it builds the list of
+   * patches to be written by the low-level functions of the base class. See
+   * the general documentation of this class for further information.
    *
-   * In addition to the same
-   * parameters as found in the
-   * respective function of the
-   * DataOut class, the first
-   * parameter denotes into how
-   * many intervals the angular
-   * (rotation) variable is to be
-   * subdivided.
+   * In addition to the same parameters as found in the respective function of
+   * the DataOut class, the first parameter denotes into how many intervals
+   * the angular (rotation) variable is to be subdivided.
    *
-   * The function supports
-   * multithreading, if deal.II is
-   * compiled in multithreading
-   * mode.
+   * The function supports multithreading, if deal.II is compiled in
+   * multithreading mode.
    */
   virtual void build_patches (const unsigned int n_patches_per_circle,
                               const unsigned int n_subdivisions = 0);
 
   /**
-   * Return the first cell which we
-   * want output for. The default
-   * implementation returns the
-   * first @ref GlossActive "active cell",
-   * but you might want to
-   * return other cells in a
-   * derived class.
+   * Return the first cell which we want output for. The default
+   * implementation returns the first @ref GlossActive "active cell", but you
+   * might want to return other cells in a derived class.
    */
   virtual cell_iterator first_cell ();
 
   /**
-   * Return the next cell after @p cell which
-   * we want output for.
-   * If there are no more cells,
-   * <tt>dofs->end()</tt> shall be returned.
+   * Return the next cell after @p cell which we want output for. If there are
+   * no more cells, <tt>dofs->end()</tt> shall be returned.
    *
-   * The default
-   * implementation returns the next
-   * active cell, but you might want
-   * to return other cells in a derived
-   * class. Note that the default
-   * implementation assumes that
-   * the given @p cell is active, which
-   * is guaranteed as long as @p first_cell
-   * is also used from the default
-   * implementation. Overloading only one
-   * of the two functions might not be
-   * a good idea.
+   * The default implementation returns the next active cell, but you might
+   * want to return other cells in a derived class. Note that the default
+   * implementation assumes that the given @p cell is active, which is
+   * guaranteed as long as @p first_cell is also used from the default
+   * implementation. Overloading only one of the two functions might not be a
+   * good idea.
    */
   virtual cell_iterator next_cell (const cell_iterator &cell);
 
@@ -221,12 +188,9 @@ public:
 
 private:
   /**
-   * Builds every @p n_threads's
-   * patch. This function may be
-   * called in parallel.
-   * If multithreading is not
-   * used, the function is called
-   * once and generates all patches.
+   * Builds every @p n_threads's patch. This function may be called in
+   * parallel. If multithreading is not used, the function is called once and
+   * generates all patches.
    */
   void
   build_one_patch (const cell_iterator *cell,
index a956009ad08016e589a7f8cb4594f7c4bb4af072..57e32f40b3c595b50dee98a50e1680ac6e79782c 100644 (file)
@@ -30,48 +30,46 @@ DEAL_II_NAMESPACE_OPEN
 template <int dim, int spacedim> class DoFHandler;
 
 /**
- * This class is used to stack the output from several computations
- * into one output file by stacking the data sets in another
- * co-ordinate direction orthogonal to the space directions. The most
- * common use is to stack the results of several time steps into one
- * space-time output file, or for example to connect the results of
- * solutions of a parameter dependent equation for several parameter
- * value together into one. The interface is mostly modelled after the
- * DataOut class, see there for some more documentation.
+ * This class is used to stack the output from several computations into one
+ * output file by stacking the data sets in another co-ordinate direction
+ * orthogonal to the space directions. The most common use is to stack the
+ * results of several time steps into one space-time output file, or for
+ * example to connect the results of solutions of a parameter dependent
+ * equation for several parameter value together into one. The interface is
+ * mostly modelled after the DataOut class, see there for some more
+ * documentation.
  *
- * We will explain the concept for a time dependent problem, but
- * instead of the time any parameter can be substituted. In our
- * example, a solution of an equation is computed for each discrete
- * time level. This is then added to an object of the present class
- * and after all time levels are added, a space-time plot will be
- * written in any of the output formats supported by the base
- * class. Upon output, the (spatial) solution on each time level is
- * extended into the time direction by writing it twice, once for the
- * time level itself and once for a time equal to the time level minus
- * a given time step. These two copies are connected, to form a
- * space-time slab, with constant values in time.
+ * We will explain the concept for a time dependent problem, but instead of
+ * the time any parameter can be substituted. In our example, a solution of an
+ * equation is computed for each discrete time level. This is then added to an
+ * object of the present class and after all time levels are added, a space-
+ * time plot will be written in any of the output formats supported by the
+ * base class. Upon output, the (spatial) solution on each time level is
+ * extended into the time direction by writing it twice, once for the time
+ * level itself and once for a time equal to the time level minus a given time
+ * step. These two copies are connected, to form a space-time slab, with
+ * constant values in time.
  *
- * Due to the piecewise constant output in time, the written solution
- * will in general be discontinuous at discrete time levels, but the
- * output is still sufficient in most cases. More sophisticated
- * interpolations in time may be added in the future.
+ * Due to the piecewise constant output in time, the written solution will in
+ * general be discontinuous at discrete time levels, but the output is still
+ * sufficient in most cases. More sophisticated interpolations in time may be
+ * added in the future.
  *
  *
  * <h3>Example of Use</h3>
  *
- * The following little example shall illustrate the different steps
- * of use of this class. It is assumed that the finite element used is
- * composed of two components, @p u and @p v, that the solution vector
- * is named @p solution and that a vector @p error is computed which
- * contains an error indicator for each spatial cell.
+ * The following little example shall illustrate the different steps of use of
+ * this class. It is assumed that the finite element used is composed of two
+ * components, @p u and @p v, that the solution vector is named @p solution
+ * and that a vector @p error is computed which contains an error indicator
+ * for each spatial cell.
  *
- * Note that unlike for the DataOut class it is necessary to first
- * declare data vectors and the names of the components before first
- * use. This is because on all time levels the same data should be
- * present to produce reasonable time-space output. The output is
- * generated with two subdivisions in each space and time direction,
- * which is suitable for quadratic finite elements in space, for
- * example.
+ * Note that unlike for the DataOut class it is necessary to first declare
+ * data vectors and the names of the components before first use. This is
+ * because on all time levels the same data should be present to produce
+ * reasonable time-space output. The output is generated with two subdivisions
+ * in each space and time direction, which is suitable for quadratic finite
+ * elements in space, for example.
  *
  * @code
  *   DataOutStack<dim> data_out_stack;
@@ -111,110 +109,77 @@ class DataOutStack : public DataOutInterface<dim+1>
 {
 public:
   /**
-   * Data type declaring the two types
-   * of vectors which are used in this
+   * Data type declaring the two types of vectors which are used in this
    * class.
    */
   enum VectorType { cell_vector, dof_vector };
 
   /**
-   * Destructor. Only declared to make
-   * it @p virtual.
+   * Destructor. Only declared to make it @p virtual.
    */
   virtual ~DataOutStack ();
 
   /**
-   * Start the next set of data for a
-   * specific parameter value. The argument
-   * @p parameter_step denotes the interval
-   * (in backward direction, counted from
-   * @p parameter_value) with which the
-   * output will be extended in parameter
-   * direction, i.e. orthogonal to the
-   * space directions.
+   * Start the next set of data for a specific parameter value. The argument
+   * @p parameter_step denotes the interval (in backward direction, counted
+   * from @p parameter_value) with which the output will be extended in
+   * parameter direction, i.e. orthogonal to the space directions.
    */
   void new_parameter_value (const double parameter_value,
                             const double parameter_step);
 
   /**
-   * Attach the DoF handler for the
-   * grid and data associated with the
-   * parameter previously set by
-   * @p new_parameter_value.
+   * Attach the DoF handler for the grid and data associated with the
+   * parameter previously set by @p new_parameter_value.
    *
-   * This has to happen before adding
-   * data vectors for the present
-   * parameter value.
+   * This has to happen before adding data vectors for the present parameter
+   * value.
    */
   void attach_dof_handler (const DH &dof_handler);
 
   /**
-   * Declare a data vector. The @p vector_type
-   * argument determines whether the data
-   * vector will be considered as DoF or
-   * cell data.
+   * Declare a data vector. The @p vector_type argument determines whether the
+   * data vector will be considered as DoF or cell data.
    *
-   * This version may be called if the
-   * finite element presently used by the
-   * DoFHandler (and previously attached
-   * to this object) has only one component
-   * and therefore only one name needs to
-   * be given.
+   * This version may be called if the finite element presently used by the
+   * DoFHandler (and previously attached to this object) has only one
+   * component and therefore only one name needs to be given.
    */
   void declare_data_vector (const std::string &name,
                             const VectorType   vector_type);
 
   /**
-   * Declare a data vector. The @p vector_type
-   * argument determines whether the data
-   * vector will be considered as DoF or
-   * cell data.
+   * Declare a data vector. The @p vector_type argument determines whether the
+   * data vector will be considered as DoF or cell data.
    *
-   * This version must be called if the
-   * finite element presently used by the
-   * DoFHandler (and previously attached
-   * to this object) has more than one
-   * component and therefore more than one
-   * name needs to be given. However, you
-   * can also call this function with a
-   * <tt>std::vector@<std::string@></tt> containing only one
-   * element if the finite element has
-   * only one component.
+   * This version must be called if the finite element presently used by the
+   * DoFHandler (and previously attached to this object) has more than one
+   * component and therefore more than one name needs to be given. However,
+   * you can also call this function with a
+   * <tt>std::vector@<std::string@></tt> containing only one element if the
+   * finite element has only one component.
    */
   void declare_data_vector (const std::vector<std::string> &name,
                             const VectorType                vector_type);
 
 
   /**
-   * Add a data vector for the presently
-   * set value of the parameter.
+   * Add a data vector for the presently set value of the parameter.
    *
-   * This version may be called if the
-   * finite element presently used by the
-   * DoFHandler (and previously attached
-   * to this object) has only one component
-   * and therefore only one name needs to
-   * be given.
+   * This version may be called if the finite element presently used by the
+   * DoFHandler (and previously attached to this object) has only one
+   * component and therefore only one name needs to be given.
    *
-   * If @p vec is a vector with
-   * multiple components this
-   * function will generate
-   * distinct names for all
-   * components by appending an
-   * underscore and the number of
-   * each component to @p name
+   * If @p vec is a vector with multiple components this function will
+   * generate distinct names for all components by appending an underscore and
+   * the number of each component to @p name
    *
-   * The data vector must have been
-   * registered using the @p declare_data_vector
-   * function before actually using it the
-   * first time.
+   * The data vector must have been registered using the @p
+   * declare_data_vector function before actually using it the first time.
    *
-   * Note that a copy of this vector is
-   * stored until @p finish_parameter_value
-   * is called the next time, so if you are
-   * short of memory you may want to call
-   * this function only after all
-   * computations involving large matrices
+   * Note that a copy of this vector is stored until @p finish_parameter_value
+   * is called the next time, so if you are short of memory you may want to
+   * call this function only after all computations involving large matrices
    * are already done.
    */
   template <typename number>
@@ -222,31 +187,21 @@ public:
                         const std::string    &name);
 
   /**
-   * Add a data vector for the presently
-   * set value of the parameter.
+   * Add a data vector for the presently set value of the parameter.
    *
-   * This version must be called if the
-   * finite element presently used by the
-   * DoFHandler (and previously attached
-   * to this object) has more than one
-   * component and therefore more than one
-   * name needs to be given. However, you
-   * can also call this function with a
-   * <tt>std::vector@<std::string@></tt> containing only one
-   * element if the finite element has
-   * only one component.
+   * This version must be called if the finite element presently used by the
+   * DoFHandler (and previously attached to this object) has more than one
+   * component and therefore more than one name needs to be given. However,
+   * you can also call this function with a
+   * <tt>std::vector@<std::string@></tt> containing only one element if the
+   * finite element has only one component.
    *
-   * The data vector must have been
-   * registered using the @p declare_data_vector
-   * function before actually using it the
-   * first time.
+   * The data vector must have been registered using the @p
+   * declare_data_vector function before actually using it the first time.
    *
-   * Note that a copy of this vector is
-   * stored until @p finish_parameter_value
-   * is called the next time, so if you are
-   * short of memory you may want to call
-   * this function only after all
-   * computations involving large matrices
+   * Note that a copy of this vector is stored until @p finish_parameter_value
+   * is called the next time, so if you are short of memory you may want to
+   * call this function only after all computations involving large matrices
    * are already done.
    */
   template <typename number>
@@ -254,44 +209,34 @@ public:
                         const std::vector<std::string> &names);
 
   /**
-   * Actually build the patches for output
-   * by the base classes from the data
-   * stored in the data vectors and using
-   * the previously attached DoFHandler
+   * Actually build the patches for output by the base classes from the data
+   * stored in the data vectors and using the previously attached DoFHandler
    * object.
    *
-   * By @p n_subdivisions you can decide
-   * into how many subdivisions (in each
-   * space and parameter direction) each
-   * patch is divided. This is useful
-   * if higher order elements are used.
-   * Note however, that the number of
-   * subdivisions in parameter direction
-   * is always the same as the one is space
-   * direction for technical reasons.
+   * By @p n_subdivisions you can decide into how many subdivisions (in each
+   * space and parameter direction) each patch is divided. This is useful if
+   * higher order elements are used. Note however, that the number of
+   * subdivisions in parameter direction is always the same as the one is
+   * space direction for technical reasons.
    */
   void build_patches (const unsigned int n_subdivisions = 0);
 
   /**
-   * Release all data that is no
-   * more needed once @p build_patches
-   * was called and all other transactions
-   * for a given parameter value are done.
+   * Release all data that is no more needed once @p build_patches was called
+   * and all other transactions for a given parameter value are done.
    *
    * Couterpart of @p new_parameter_value.
    */
   void finish_parameter_value ();
 
   /**
-   * Clear all data presently stored
-   * in this object.
+   * Clear all data presently stored in this object.
    */
   void clear ();
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -364,28 +309,24 @@ private:
   double                               parameter;
 
   /**
-   * Present parameter step, i.e.
-   * length of the parameter interval
-   * to be written next.
+   * Present parameter step, i.e. length of the parameter interval to be
+   * written next.
    */
   double                               parameter_step;
 
   /**
-   * DoF handler to be used for the data
-   * corresponding to the present parameter
-   * value.
+   * DoF handler to be used for the data corresponding to the present
+   * parameter value.
    */
   SmartPointer<const DH,DataOutStack<dim,spacedim,DH> > dof_handler;
 
   /**
-   * List of patches of all past and
-   * present parameter value data sets.
+   * List of patches of all past and present parameter value data sets.
    */
   std::vector< dealii::DataOutBase::Patch<dim+1,dim+1> >   patches;
 
   /**
-   * Structure holding data vectors
-   * (cell and dof data) for the present
+   * Structure holding data vectors (cell and dof data) for the present
    * parameter value.
    */
   struct DataVector
@@ -396,15 +337,13 @@ private:
     Vector<double> data;
 
     /**
-     * Names of the different components
-     * within each such data set.
+     * Names of the different components within each such data set.
      */
     std::vector<std::string> names;
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
   };
@@ -420,21 +359,16 @@ private:
   std::vector<DataVector> cell_data;
 
   /**
-   * This is the function through
-   * which derived classes propagate
-   * preprocessed data in the form of
-   * Patch structures (declared in
-   * the base class DataOutBase) to
-   * the actual output function.
+   * This is the function through which derived classes propagate preprocessed
+   * data in the form of Patch structures (declared in the base class
+   * DataOutBase) to the actual output function.
    */
   virtual const std::vector< dealii::DataOutBase::Patch<dim+1,dim+1> > & get_patches () const;
 
 
   /**
-   * Virtual function through
-   * which the names of data sets are
-   * obtained by the output functions
-   * of the base class.
+   * Virtual function through which the names of data sets are obtained by the
+   * output functions of the base class.
    */
   virtual std::vector<std::string> get_dataset_names () const;
 };
index 1da010368c65f2a14dba20edbb349cd830af4670..cc4e2b86c7ac0673761443bd51ec60b426fbe30b 100644 (file)
@@ -31,81 +31,80 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class provides an interface to compute derived quantities from
- * solution that can then be output in graphical formats for visualization,
+ * This class provides an interface to compute derived quantities from a
+ * solution that can then be output in graphical formats for visualization,
  * using facilities such as the DataOut class.
  *
  * For the (graphical) output of a FE solution one frequently wants to include
  * derived quantities, which are calculated from the values of the solution
  * and possibly the first and second derivates of the solution. Examples are
- * the calculation of Mach numbers from velocity and density in supersonic flow
- * computations, or the computation of the magnitude of a complex-valued
+ * the calculation of Mach numbers from velocity and density in supersonic
+ * flow computations, or the computation of the magnitude of a complex-valued
  * solution as demonstrated in step-29. Other uses are shown in step-32 and
- * step-33. This class offers the interface to perform such
- * postprocessing. Given the values and derivatives of the solution at those
- * points where we want to generated output, the functions of this class can
- * be overloaded to compute new quantities.
+ * step-33. This class offers the interface to perform such postprocessing.
+ * Given the values and derivatives of the solution at those points where we
+ * want to generated output, the functions of this class can be overloaded to
+ * compute new quantities.
  *
- * A data vector and an object of a class derived from the current one can
- * be given to the DataOut::add_data_vector() function (and similarly for
- * DataOutRotation and DataOutFaces). This will cause
- * DataOut::build_patches() to compute the derived quantities instead of using
- * the data provided by the data vector (typically the solution vector). Note
- * that the DataPostprocessor object (i.e., in reality the object of your derived
- * class) has to live until the DataOut object is destroyed as the latter keeps
- * a pointer to the former and will complain if the object pointed to is
+ * A data vector and an object of a class derived from the current one can be
+ * given to the DataOut::add_data_vector() function (and similarly for
+ * DataOutRotation and DataOutFaces). This will cause DataOut::build_patches()
+ * to compute the derived quantities instead of using the data provided by the
+ * data vector (typically the solution vector). Note that the
+ * DataPostprocessor object (i.e., in reality the object of your derived
+ * class) has to live until the DataOut object is destroyed as the latter
+ * keeps a pointer to the former and will complain if the object pointed to is
  * destroyed while the latter still has a pointer to it. If both the data
- * postprocessor and DataOut objects are local variables of a function
- * (as they are, for example, in step-29), then you can avoid this
- * error by declaring the data postprocessor variable before the DataOut
- * variable as objects are destroyed in reverse order of declaration.
+ * postprocessor and DataOut objects are local variables of a function (as
+ * they are, for example, in step-29), then you can avoid this error by
+ * declaring the data postprocessor variable before the DataOut variable as
+ * objects are destroyed in reverse order of declaration.
  *
- * In order not to perform needless calculations, DataPostprocessor
- * has to provide information which input data is needed for the
- * calculation of the derived quantities, i.e. whether it needs the
- * values, the first derivative and/or the second derivative of the
- * provided data. DataPostprocessor objects which are used in
- * combination with a DataOutFaces object can also ask for the normal
- * vectors at each point. The information which data is needed has to
- * be provided via the UpdateFlags returned by the virtual function
- * get_needed_update_flags(). It is your responsibility to use only
- * those values which were updated in the calculation of derived
- * quantities. The DataOut object will provide references to the
- * requested data in the call to compute_derived_quantities_scalar()
- * or compute_derived_quantities_vector() (DataOut decides which of
- * the two functions to call depending on whether the finite element
- * in use has only a single, or multiple vector components; note that
- * this is only determined by the number of components in the finite
- * element in use, and not by whether the data computed by a class
- * derived from the current one is scalar or vector valued).
+ * In order not to perform needless calculations, DataPostprocessor has to
+ * provide information which input data is needed for the calculation of the
+ * derived quantities, i.e. whether it needs the values, the first derivative
+ * and/or the second derivative of the provided data. DataPostprocessor
+ * objects which are used in combination with a DataOutFaces object can also
+ * ask for the normal vectors at each point. The information which data is
+ * needed has to be provided via the UpdateFlags returned by the virtual
+ * function get_needed_update_flags(). It is your responsibility to use only
+ * those values which were updated in the calculation of derived quantities.
+ * The DataOut object will provide references to the requested data in the
+ * call to compute_derived_quantities_scalar() or
+ * compute_derived_quantities_vector() (DataOut decides which of the two
+ * functions to call depending on whether the finite element in use has only a
+ * single, or multiple vector components; note that this is only determined by
+ * the number of components in the finite element in use, and not by whether
+ * the data computed by a class derived from the current one is scalar or
+ * vector valued).
  *
- * Furthermore, derived classes have to implement the get_names()
- * function, where the number of output variables returned
- * by the latter function has to match the size of the vector returned by the
- * former. Furthermore, this number has to match the number of computed
- * quantities, of course.
+ * Furthermore, derived classes have to implement the get_names() function,
+ * where the number of output variables returned by the latter function has to
+ * match the size of the vector returned by the former. Furthermore, this
+ * number has to match the number of computed quantities, of course.
  *
  *
  * <h3>Use in simpler cases</h3>
  *
- * Deriving from the current class allows to implement very general postprocessors.
- * For example, in the step-32 program, we implement a postprocessor that
- * takes a solution that consists of velocity, pressure and temperature (dim+2
- * components) and computes a variety of output quantities, some of which
- * are vector valued and some of which are scalar. On the other hand,
- * in step-29 we implement a postprocessor that only computes the magnitude
- * of a complex number given by a two-component finite element. It seems silly
- * to have to implement four virtual functions for this
- * (compute_derived_quantities_scalar() or compute_derived_quantities_vector(),
- * get_names(), get_update_flags() and get_data_component_interpretation()).
+ * Deriving from the current class allows to implement very general
+ * postprocessors. For example, in the step-32 program, we implement a
+ * postprocessor that takes a solution that consists of velocity, pressure and
+ * temperature (dim+2 components) and computes a variety of output quantities,
+ * some of which are vector valued and some of which are scalar. On the other
+ * hand, in step-29 we implement a postprocessor that only computes the
+ * magnitude of a complex number given by a two-component finite element. It
+ * seems silly to have to implement four virtual functions for this
+ * (compute_derived_quantities_scalar() or
+ * compute_derived_quantities_vector(), get_names(), get_update_flags() and
+ * get_data_component_interpretation()).
  *
  * To this end there are two classes DataPostprocessorScalar and
- * DataPostprocessorVector that are meant to be used if the output quantity
- * is either a single scalar or a single vector (here used meaning to have
+ * DataPostprocessorVector that are meant to be used if the output quantity is
+ * either a single scalar or a single vector (here used meaning to have
  * exactly dim components). When using these classes, one only has to write a
  * constructor that passes the name of the output variable and the update
- * flags to the constructor of the base class and overload the function
- * that actually computes the results.
+ * flags to the constructor of the base class and overload the function that
+ * actually computes the results.
  *
  * @ingroup output
  * @author Tobias Leicht, 2007
@@ -115,23 +114,18 @@ class DataPostprocessor: public Subscriptor
 {
 public:
   /**
-   * Virtual desctructor for safety. Does not
-   * do anything.
+   * Virtual desctructor for safety. Does not do anything.
    */
   virtual ~DataPostprocessor ();
 
   /**
    * @deprecated
    *
-   * This function only exists for backward
-   * compatibility as this is the interface
-   * provided by previous versions of the
-   * library. The default implementation of
-   * the other function of same name below
-   * calls this function by simply dropping
-   * the argument that denotes the
-   * evaluation points. Since this function
-   * might at one point go away, you should
+   * This function only exists for backward compatibility as this is the
+   * interface provided by previous versions of the library. The default
+   * implementation of the other function of same name below calls this
+   * function by simply dropping the argument that denotes the evaluation
+   * points. Since this function might at one point go away, you should
    * overload the other function instead.
    */
   virtual
@@ -143,31 +137,18 @@ public:
                                      std::vector<Vector<double> >      &computed_quantities) const DEAL_II_DEPRECATED;
 
   /**
-   * This is the main function which actually
-   * performs the postprocessing. The last
-   * argument is a reference to the
-   * postprocessed data which has correct
-   * size already and must be filled by this
-   * function. @p uh is a reference to a
-   * vector of data values at all points, @p
-   * duh the same for gradients, @p dduh for
-   * second derivatives and @p normals is a
-   * reference to the normal vectors. Note,
-   * that the last four references will only
-   * contain valid data, if the respective
-   * flags are returned by @p
-   * get_needed_update_flags, otherwise those
-   * vectors will be in an unspecified
-   * state. @p normals will always be an
-   * empty vector when working on cells, not
-   * on faces.
+   * This is the main function which actually performs the postprocessing. The
+   * last argument is a reference to the postprocessed data which has correct
+   * size already and must be filled by this function. @p uh is a reference to
+   * a vector of data values at all points, @p duh the same for gradients, @p
+   * dduh for second derivatives and @p normals is a reference to the normal
+   * vectors. Note, that the last four references will only contain valid
+   * data, if the respective flags are returned by @p get_needed_update_flags,
+   * otherwise those vectors will be in an unspecified state. @p normals will
+   * always be an empty vector when working on cells, not on faces.
    *
-   * This function is called when
-   * the original data vector
-   * represents scalar data,
-   * i.e. the finite element in use
-   * has only a single vector
-   * component.
+   * This function is called when the original data vector represents scalar
+   * data, i.e. the finite element in use has only a single vector component.
    */
   virtual
   void
@@ -181,15 +162,11 @@ public:
   /**
    * @deprecated
    *
-   * This function only exists for backward
-   * compatibility as this is the interface
-   * provided by previous versions of the
-   * library. The default implementation of
-   * the other function of same name below
-   * calls this function by simply dropping
-   * the argument that denotes the
-   * evaluation points. Since this function
-   * might at one point go away, you should
+   * This function only exists for backward compatibility as this is the
+   * interface provided by previous versions of the library. The default
+   * implementation of the other function of same name below calls this
+   * function by simply dropping the argument that denotes the evaluation
+   * points. Since this function might at one point go away, you should
    * overload the other function instead.
    */
   virtual
@@ -201,13 +178,9 @@ public:
                                      std::vector<Vector<double> >                    &computed_quantities) const DEAL_II_DEPRECATED;
 
   /**
-   * Same as the
-   * compute_derived_quantities_scalar()
-   * function, but this function is called
-   * when the original data vector
-   * represents vector data, i.e. the
-   * finite element in use has multiple
-   * vector components.
+   * Same as the compute_derived_quantities_scalar() function, but this
+   * function is called when the original data vector represents vector data,
+   * i.e. the finite element in use has multiple vector components.
    */
   virtual
   void
@@ -219,63 +192,43 @@ public:
                                      std::vector<Vector<double> >                    &computed_quantities) const;
 
   /**
-   * Return the vector of strings describing
-   * the names of the computed quantities.
+   * Return the vector of strings describing the names of the computed
+   * quantities.
    */
   virtual std::vector<std::string> get_names () const = 0;
 
   /**
-   * This functions returns
-   * information about how the
-   * individual components of
-   * output files that consist of
-   * more than one data set are to
-   * be interpreted.
+   * This functions returns information about how the individual components of
+   * output files that consist of more than one data set are to be
+   * interpreted.
    *
-   * For example, if one has a finite
-   * element for the Stokes equations in
-   * 2d, representing components (u,v,p),
-   * one would like to indicate that the
-   * first two, u and v, represent a
-   * logical vector so that later on when
-   * we generate graphical output we can
-   * hand them off to a visualization
-   * program that will automatically know
-   * to render them as a vector field,
-   * rather than as two separate and
-   * independent scalar fields.
+   * For example, if one has a finite element for the Stokes equations in 2d,
+   * representing components (u,v,p), one would like to indicate that the
+   * first two, u and v, represent a logical vector so that later on when we
+   * generate graphical output we can hand them off to a visualization program
+   * that will automatically know to render them as a vector field, rather
+   * than as two separate and independent scalar fields.
    *
-   * The default implementation of this
-   * function returns a vector of values
-   * DataComponentInterpretation::component_is_scalar,
-   * indicating that all output components
-   * are independent scalar
-   * fields. However, if a derived class
-   * produces data that represents vectors,
-   * it may return a vector that contains
-   * values
-   * DataComponentInterpretation::component_is_part_of_vector. In
-   * the example above, one would return a
-   * vector with components
+   * The default implementation of this function returns a vector of values
+   * DataComponentInterpretation::component_is_scalar, indicating that all
+   * output components are independent scalar fields. However, if a derived
+   * class produces data that represents vectors, it may return a vector that
+   * contains values DataComponentInterpretation::component_is_part_of_vector.
+   * In the example above, one would return a vector with components
    * (DataComponentInterpretation::component_is_part_of_vector,
    * DataComponentInterpretation::component_is_part_of_vector,
-   * DataComponentInterpretation::component_is_scalar)
-   * for (u,v,p).
+   * DataComponentInterpretation::component_is_scalar) for (u,v,p).
    */
   virtual
   std::vector<DataComponentInterpretation::DataComponentInterpretation>
   get_data_component_interpretation () const;
 
   /**
-   * Return, which data has to be provided to
-   * compute the derived quantities. This has
-   * to be a combination of @p update_values,
-   * @p update_gradients and @p
-   * update_hessians. If the
-   * DataPostprocessor is to be used in
-   * combination with DataOutFaces, you may
-   * also ask for a update of normals via the
-   * @p update_normal_vectors flag.
+   * Return, which data has to be provided to compute the derived quantities.
+   * This has to be a combination of @p update_values, @p update_gradients and
+   * @p update_hessians. If the DataPostprocessor is to be used in combination
+   * with DataOutFaces, you may also ask for a update of normals via the @p
+   * update_normal_vectors flag.
    */
   virtual UpdateFlags get_needed_update_flags () const = 0;
 };
@@ -283,13 +236,13 @@ public:
 
 
 /**
- * This class provides a simpler interface to the functionality offered by
- * the DataPostprocessor class in case one wants to compute only a
- * single scalar quantity from the finite element field passed to the
- * DataOut class. For this particular case, it is clear what the returned
- * value of DataPostprocessor::get_data_component_interpretation() should
- * be and we pass the values returned by get_names() and get_needed_update_flags()
- * to the constructor so that derived classes do not have to implement these
+ * This class provides a simpler interface to the functionality offered by the
+ * DataPostprocessor class in case one wants to compute only a single scalar
+ * quantity from the finite element field passed to the DataOut class. For
+ * this particular case, it is clear what the returned value of
+ * DataPostprocessor::get_data_component_interpretation() should be and we
+ * pass the values returned by get_names() and get_needed_update_flags() to
+ * the constructor so that derived classes do not have to implement these
  * functions by hand.
  *
  * All derived classes have to do is implement a constructor and overload
@@ -306,44 +259,32 @@ class DataPostprocessorScalar : public DataPostprocessor<dim>
 {
 public:
   /**
-   * Constructor. Take the name of the single scalar variable
-   * computed by classes derived from the current one, as well
-   * as the update flags necessary to compute this quantity.
+   * Constructor. Take the name of the single scalar variable computed by
+   * classes derived from the current one, as well as the update flags
+   * necessary to compute this quantity.
    *
-   * @param name The name by which the scalar variable
-   *   computed by this class should be made available in
-   *   graphical output files.
-   * @param update_flags This has
-   * to be a combination of @p update_values,
-   * @p update_gradients and @p
-   * update_hessians. If the
-   * DataPostprocessor is to be used in
-   * combination with DataOutFaces, you may
-   * also ask for a update of normals via the
-   * @p update_normal_vectors flag.
-   **/
+   * @param name The name by which the scalar variable computed by this class
+   * should be made available in graphical output files.
+   * @param update_flags This has to be a combination of @p update_values, @p
+   * update_gradients and @p update_hessians. If the DataPostprocessor is to
+   * be used in combination with DataOutFaces, you may also ask for a update
+   * of normals via the @p update_normal_vectors flag.
+   */
   DataPostprocessorScalar (const std::string &name,
                            const UpdateFlags  update_flags);
 
   /**
-   * Return the vector of strings describing
-   * the names of the computed quantities.
-   * Given the purpose of this class, this
-   * is a vector with a single entry equal
-   * to the name given to the constructor.
+   * Return the vector of strings describing the names of the computed
+   * quantities. Given the purpose of this class, this is a vector with a
+   * single entry equal to the name given to the constructor.
    */
   virtual std::vector<std::string> get_names () const;
 
   /**
-   * This functions returns
-   * information about how the
-   * individual components of
-   * output files that consist of
-   * more than one data set are to
-   * be interpreted. Since the current
-   * class is meant to be used for a
-   * single scalar result variable,
-   * the returned value is obviously
+   * This functions returns information about how the individual components of
+   * output files that consist of more than one data set are to be
+   * interpreted. Since the current class is meant to be used for a single
+   * scalar result variable, the returned value is obviously
    * DataComponentInterpretation::component_is_scalar.
    */
   virtual
@@ -351,18 +292,15 @@ public:
   get_data_component_interpretation () const;
 
   /**
-   * Return, which data has to be provided to
-   * compute the derived quantities.
-   * The flags returned here are the ones
-   * passed to the constructor of this
+   * Return, which data has to be provided to compute the derived quantities.
+   * The flags returned here are the ones passed to the constructor of this
    * class.
    */
   virtual UpdateFlags get_needed_update_flags () const;
 
 private:
   /**
-   * Copies of the two arguments given to the constructor of this
-   * class.
+   * Copies of the two arguments given to the constructor of this class.
    */
   const std::string name;
   const UpdateFlags update_flags;
@@ -371,22 +309,22 @@ private:
 
 
 /**
- * This class provides a simpler interface to the functionality offered by
- * the DataPostprocessor class in case one wants to compute only a
- * single vector quantity (defined as having exactly dim components)
- * from the finite element field passed to the
- * DataOut class. For this particular case, it is clear what the returned
- * value of DataPostprocessor::get_data_component_interpretation() should
- * be and we pass the values returned by get_names() and get_needed_update_flags()
- * to the constructor so that derived classes do not have to implement these
+ * This class provides a simpler interface to the functionality offered by the
+ * DataPostprocessor class in case one wants to compute only a single vector
+ * quantity (defined as having exactly dim components) from the finite element
+ * field passed to the DataOut class. For this particular case, it is clear
+ * what the returned value of
+ * DataPostprocessor::get_data_component_interpretation() should be and we
+ * pass the values returned by get_names() and get_needed_update_flags() to
+ * the constructor so that derived classes do not have to implement these
  * functions by hand.
  *
  * All derived classes have to do is implement a constructor and overload
  * either DataPostprocessor::compute_derived_quantities_scalar() or
  * DataPostprocessor::compute_derived_quantities_vector().
  *
- * An example of how the closely related class DataPostprocessorScalar is
- * used can be found in step-29.
+ * An example of how the closely related class DataPostprocessorScalar is used
+ * can be found in step-29.
  *
  * @ingroup output
  * @author Wolfgang Bangerth, 2011
@@ -396,64 +334,48 @@ class DataPostprocessorVector : public DataPostprocessor<dim>
 {
 public:
   /**
-   * Constructor. Take the name of the single vector variable
-   * computed by classes derived from the current one, as well
-   * as the update flags necessary to compute this quantity.
+   * Constructor. Take the name of the single vector variable computed by
+   * classes derived from the current one, as well as the update flags
+   * necessary to compute this quantity.
    *
-   * @param name The name by which the vector variable
-   *   computed by this class should be made available in
-   *   graphical output files.
-   * @param update_flags This has
-   * to be a combination of @p update_values,
-   * @p update_gradients and @p
-   * update_hessians. If the
-   * DataPostprocessor is to be used in
-   * combination with DataOutFaces, you may
-   * also ask for a update of normals via the
-   * @p update_normal_vectors flag.
-   **/
+   * @param name The name by which the vector variable computed by this class
+   * should be made available in graphical output files.
+   * @param update_flags This has to be a combination of @p update_values, @p
+   * update_gradients and @p update_hessians. If the DataPostprocessor is to
+   * be used in combination with DataOutFaces, you may also ask for a update
+   * of normals via the @p update_normal_vectors flag.
+   */
   DataPostprocessorVector (const std::string &name,
                            const UpdateFlags  update_flags);
 
   /**
-   * Return the vector of strings describing
-   * the names of the computed quantities.
-   * Given the purpose of this class, this
-   * is a vector with dim entries all equal
-   * to the name given to the constructor.
+   * Return the vector of strings describing the names of the computed
+   * quantities. Given the purpose of this class, this is a vector with dim
+   * entries all equal to the name given to the constructor.
    */
   virtual std::vector<std::string> get_names () const;
 
   /**
-   * This functions returns
-   * information about how the
-   * individual components of
-   * output files that consist of
-   * more than one data set are to
-   * be interpreted. Since the current
-   * class is meant to be used for a
-   * single vector result variable,
-   * the returned value is obviously
-   * DataComponentInterpretation::component_is_part
-   * repeated dim times.
+   * This functions returns information about how the individual components of
+   * output files that consist of more than one data set are to be
+   * interpreted. Since the current class is meant to be used for a single
+   * vector result variable, the returned value is obviously
+   * DataComponentInterpretation::component_is_part repeated dim times.
    */
   virtual
   std::vector<DataComponentInterpretation::DataComponentInterpretation>
   get_data_component_interpretation () const;
 
   /**
-   * Return which data has to be provided to
-   * compute the derived quantities.
-   * The flags returned here are the ones
-   * passed to the constructor of this
+   * Return which data has to be provided to compute the derived quantities.
+   * The flags returned here are the ones passed to the constructor of this
    * class.
    */
   virtual UpdateFlags get_needed_update_flags () const;
 
 private:
   /**
-   * Copies of the two arguments given to the constructor of this
-   * class.
+   * Copies of the two arguments given to the constructor of this class.
    */
   const std::string name;
   const UpdateFlags update_flags;
index da68daee45e66394fb3f2f09b65d8024ea12afe2..e0b91712ac64f01c30d760f8e830bece9c8cbfb6 100644 (file)
@@ -40,49 +40,39 @@ namespace hp
 
 
 /**
- * This namespace provides functions that compute a cell-wise approximation of the norm of a
- * derivative of a finite element field by taking difference quotients
- * between neighboring cells. This is a rather simple but efficient
- * form to get an error indicator, since it can be computed with
- * relatively little numerical effort and yet gives a reasonable
- * approximation.
+ * This namespace provides functions that compute a cell-wise approximation of
+ * the norm of a derivative of a finite element field by taking difference
+ * quotients between neighboring cells. This is a rather simple but efficient
+ * form to get an error indicator, since it can be computed with relatively
+ * little numerical effort and yet gives a reasonable approximation.
  *
- * The way the difference quotients are computed on cell $K$ is the
- * following (here described for the approximation of the gradient of
- * a finite element field, but see below for higher derivatives): let
- * $K'$ be a neighboring cell, and let $y_{K'}=x_{K'}-x_K$ be the
- * distance vector between the centers of the two cells, then
- *   $ \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }$
- * is an approximation of the directional derivative
- *   $ \nabla u(x_K) \cdot \frac{y_{K'}}{ \|y_{K'}\| }.$
- * By multiplying both terms by $\frac{y_{K'}}{ \|y_{K'}\| }$ from the
- * left and summing over all neighbors $K'$, we obtain
- *   $ \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
- *                      \frac{y_{K'}^T}{ \|y_{K'}\| } \right) \nabla u(x_K)
- *     \approx
- *     \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
- *                      \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }  \right).$
+ * The way the difference quotients are computed on cell $K$ is the following
+ * (here described for the approximation of the gradient of a finite element
+ * field, but see below for higher derivatives): let $K'$ be a neighboring
+ * cell, and let $y_{K'}=x_{K'}-x_K$ be the distance vector between the
+ * centers of the two cells, then $ \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\|
+ * }$ is an approximation of the directional derivative $ \nabla u(x_K) \cdot
+ * \frac{y_{K'}}{ \|y_{K'}\| }.$ By multiplying both terms by $\frac{y_{K'}}{
+ * \|y_{K'}\| }$ from the left and summing over all neighbors $K'$, we obtain
+ * $ \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|} \frac{y_{K'}^T}{ \|y_{K'}\| }
+ * \right) \nabla u(x_K) \approx \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
+ * \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }  \right).$
  *
- * Thus, if the matrix
- *   $ Y =  \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
- *                           \frac{y_{K'}^T}{ \|y_{K'}\| } \right)$ is
- * regular (which is the case when the vectors $y_{K'}$ to all neighbors span
- * the whole space), we can obtain an approximation to the true gradient by
- *   $ \nabla u(x_K)
- *     \approx
- *     Y^{-1} \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
- *                             \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }
- *                      \right).$
- * This is a quantity that is easily computed. The value returned for
- * each cell when calling the @p approximate_gradient function of
- * this class is the $l_2$ norm of this approximation to the
- * gradient. To make this a useful quantity, you may want to scale
- * each element by the correct power of the respective cell size.
+ * Thus, if the matrix $ Y =  \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
+ * \frac{y_{K'}^T}{ \|y_{K'}\| } \right)$ is regular (which is the case when
+ * the vectors $y_{K'}$ to all neighbors span the whole space), we can obtain
+ * an approximation to the true gradient by $ \nabla u(x_K) \approx Y^{-1}
+ * \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|} \frac{u_h(x_{K'}) - u_h(x_K)}{
+ * \|y_{K'}\| } \right).$ This is a quantity that is easily computed. The
+ * value returned for each cell when calling the @p approximate_gradient
+ * function of this class is the $l_2$ norm of this approximation to the
+ * gradient. To make this a useful quantity, you may want to scale each
+ * element by the correct power of the respective cell size.
  *
- * The computation of this quantity must fail if a cell has only
- * neighbors for which the direction vectors $y_K$ do not span the
- * whole space, since then the matrix $Y$ is no longer invertible. If
- * this happens, you will get an error similar to this one:
+ * The computation of this quantity must fail if a cell has only neighbors for
+ * which the direction vectors $y_K$ do not span the whole space, since then
+ * the matrix $Y$ is no longer invertible. If this happens, you will get an
+ * error similar to this one:
  * @code
  * --------------------------------------------------------
  * An error occurred in line <749> of file <source/numerics/derivative_approximation.cc> in function
@@ -97,91 +87,76 @@ namespace hp
  * (none)
  * --------------------------------------------------------
  * @endcode
- * As can easily be verified, this can only happen on very
- * coarse grids, when some cells and all their neighbors have not been
- * refined even once. You should therefore only call the functions of
- * this class if all cells are at least once refined. In practice this
- * is not much of a restriction.
+ * As can easily be verified, this can only happen on very coarse grids, when
+ * some cells and all their neighbors have not been refined even once. You
+ * should therefore only call the functions of this class if all cells are at
+ * least once refined. In practice this is not much of a restriction.
  *
  *
  * <h3>Approximation of higher derivatives</h3>
  *
- * Similar to the reasoning above, approximations to higher
- * derivatives can be computed in a similar fashion. For example, the
- * tensor of second derivatives is approximated by the formula
- *   $ \nabla^2 u(x_K)
- *     \approx
- *     Y^{-1}
- *     \sum_{K'}
- *        \left(
- *           \frac{y_{K'}}{\|y_{K'}\|} \otimes
- *           \frac{\nabla u_h(x_{K'}) - \nabla u_h(x_K)}{ \|y_{K'}\| }
- *        \right),
- *   $
- * where $\otimes$ denotes the outer product of two vectors. Note that
- * unlike the true tensor of second derivatives, its approximation is
- * not necessarily symmetric. This is due to the fact that in the
- * derivation, it is not clear whether we shall consider as projected
- * second derivative the term $\nabla^2 u y_{KK'}$ or $y_{KK'}^T
- * \nabla^2 u$. Depending on which choice we take, we obtain one
- * approximation of the tensor of second derivatives or its
- * transpose. To avoid this ambiguity, as result we take the
- * symmetrized form, which is the mean value of the approximation and
- * its transpose.
+ * Similar to the reasoning above, approximations to higher derivatives can be
+ * computed in a similar fashion. For example, the tensor of second
+ * derivatives is approximated by the formula $ \nabla^2 u(x_K) \approx Y^{-1}
+ * \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|} \otimes \frac{\nabla u_h(x_{K'})
+ * - \nabla u_h(x_K)}{ \|y_{K'}\| } \right), $ where $\otimes$ denotes the
+ * outer product of two vectors. Note that unlike the true tensor of second
+ * derivatives, its approximation is not necessarily symmetric. This is due to
+ * the fact that in the derivation, it is not clear whether we shall consider
+ * as projected second derivative the term $\nabla^2 u y_{KK'}$ or $y_{KK'}^T
+ * \nabla^2 u$. Depending on which choice we take, we obtain one approximation
+ * of the tensor of second derivatives or its transpose. To avoid this
+ * ambiguity, as result we take the symmetrized form, which is the mean value
+ * of the approximation and its transpose.
  *
- * The returned value on each cell is the spectral norm of the
- * approximated tensor of second derivatives, i.e. the largest
- * eigenvalue by absolute value. This equals the largest curvature of
- * the finite element field at each cell, and the spectral norm is the
- * matrix norm associated to the $l_2$ vector norm.
+ * The returned value on each cell is the spectral norm of the approximated
+ * tensor of second derivatives, i.e. the largest eigenvalue by absolute
+ * value. This equals the largest curvature of the finite element field at
+ * each cell, and the spectral norm is the matrix norm associated to the $l_2$
+ * vector norm.
  *
- * Even higher than the second derivative can be obtained along the
- * same lines as exposed above.
+ * Even higher than the second derivative can be obtained along the same lines
+ * as exposed above.
  *
  *
  * <h3>Refinement indicators based on the derivatives</h3>
  *
- * If you would like to base a refinement criterion upon these
- * approximation of the derivatives, you will have to scale the results
- * of this class by an appropriate power of the mesh width. For
- * example, since
- * $\|u-u_h\|^2_{L_2} \le C h^2 \|\nabla u\|^2_{L_2}$, it might be the
- * right thing to scale the indicators as $\eta_K = h \|\nabla u\|_K$,
- * i.e. $\eta_K = h^{1+d/2} \|\nabla u\|_{\infty;K}$, i.e. the right
- * power is $1+d/2$.
+ * If you would like to base a refinement criterion upon these approximation
+ * of the derivatives, you will have to scale the results of this class by an
+ * appropriate power of the mesh width. For example, since $\|u-u_h\|^2_{L_2}
+ * \le C h^2 \|\nabla u\|^2_{L_2}$, it might be the right thing to scale the
+ * indicators as $\eta_K = h \|\nabla u\|_K$, i.e. $\eta_K = h^{1+d/2}
+ * \|\nabla u\|_{\infty;K}$, i.e. the right power is $1+d/2$.
  *
- * Likewise, for the second derivative, one should choose a power of
- * the mesh size $h$ one higher than for the gradient.
+ * Likewise, for the second derivative, one should choose a power of the mesh
+ * size $h$ one higher than for the gradient.
  *
  *
  * <h3>Implementation</h3>
  *
- * The formulae for the computation of approximations to the gradient
- * and to the tensor of second derivatives shown above are very much
- * alike. The basic difference is that in one case the finite
- * difference quotient is a scalar, while in the other case it is a
- * vector. For higher derivatives, this would be a tensor of even
- * higher rank. We then have to form the outer product of this
- * difference quotient with the distance vector $y_{KK'}$, symmetrize
- * it, contract it with the matrix $Y^{-1}$ and compute its norm. To
- * make the implementation simpler and to allow for code reuse, all
- * these operations that are dependent on the actual order of the
- * derivatives to be approximated, as well as the computation of the
- * quantities entering the difference quotient, have been separated
- * into auxiliary nested classes (names @p Gradient and
- * @p SecondDerivative) and the main algorithm is simply passed one
- * or the other data types and asks them to perform the order
- * dependent operations. The main framework that is independent of
- * this, such as finding all active neighbors, or setting up the
- * matrix $Y$ is done in the main function @p approximate.
+ * The formulae for the computation of approximations to the gradient and to
+ * the tensor of second derivatives shown above are very much alike. The basic
+ * difference is that in one case the finite difference quotient is a scalar,
+ * while in the other case it is a vector. For higher derivatives, this would
+ * be a tensor of even higher rank. We then have to form the outer product of
+ * this difference quotient with the distance vector $y_{KK'}$, symmetrize it,
+ * contract it with the matrix $Y^{-1}$ and compute its norm. To make the
+ * implementation simpler and to allow for code reuse, all these operations
+ * that are dependent on the actual order of the derivatives to be
+ * approximated, as well as the computation of the quantities entering the
+ * difference quotient, have been separated into auxiliary nested classes
+ * (names @p Gradient and @p SecondDerivative) and the main algorithm is
+ * simply passed one or the other data types and asks them to perform the
+ * order dependent operations. The main framework that is independent of this,
+ * such as finding all active neighbors, or setting up the matrix $Y$ is done
+ * in the main function @p approximate.
  *
- * Due to this way of operation, the class may be easily extended for
- * higher oder derivatives than are presently implemented. Basically,
- * only an additional class along the lines of the derivative
- * descriptor classes @p Gradient and @p SecondDerivative has to be
- * implemented, with the respective typedefs and functions replaced by
- * the appropriate analogues for the derivative that is to be
- * approximated.
+ * Due to this way of operation, the class may be easily extended for higher
+ * oder derivatives than are presently implemented. Basically, only an
+ * additional class along the lines of the derivative descriptor classes @p
+ * Gradient and @p SecondDerivative has to be implemented, with the respective
+ * typedefs and functions replaced by the appropriate analogues for the
+ * derivative that is to be approximated.
  *
  * @ingroup numerics
  * @author Wolfgang Bangerth, 2000
index a4af33183276693a074231bfb2eb6f5fbeabfeaa..dd07fc62d77b852fa9667d21a85782c0fcf8af5d 100644 (file)
@@ -33,9 +33,8 @@ DEAL_II_NAMESPACE_OPEN
 namespace Algorithms
 {
   /**
-   * An output operator writing a separate file in each step and
-   * writing the vectors as finite element functions with respect to a
-   * given DoFHandler.
+   * An output operator writing a separate file in each step and writing the
+   * vectors as finite element functions with respect to a given DoFHandler.
    */
   template <class VECTOR, int dim, int spacedim=dim>
   class DoFOutputOperator : public OutputOperator<VECTOR>
index abab4ed24ede07c0baab92f7129181afde78776a..48ab06eefb37c91820218ab6fd78fd4f4196ab2e 100644 (file)
@@ -30,22 +30,21 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * Print intermediate solutions in solvers.  This is derived from a
- * solver class provided as template argument.  It implements the
- * @p print_vector function of the solver using a
- * DoFHandler. This way, the intermediate vectors can be viewed
- * as finite element functions. This class might be used first to
- * understand how solvers work (for example to visualize the smoothing
- * properties of various solvers, e.g. in a multigrid context), and
- * second to investigate why and how a solver fails to solve certain
- * classes of problems.
+ * Print intermediate solutions in solvers.  This is derived from a solver
+ * class provided as template argument.  It implements the @p print_vector
+ * function of the solver using a DoFHandler. This way, the intermediate
+ * vectors can be viewed as finite element functions. This class might be used
+ * first to understand how solvers work (for example to visualize the
+ * smoothing properties of various solvers, e.g. in a multigrid context), and
+ * second to investigate why and how a solver fails to solve certain classes
+ * of problems.
  *
- * Objects of this class are provided with a solver class through a
- * template argument, and with a file name (as a string), with which a
- * new file is constructed in each iteration (named
- * <tt>basename.[step].[suffix]</tt>) and into which the solution is
- * written as a finite element field using the DataOut class.
- * Please note that this class may produce enormous amounts of data!
+ * Objects of this class are provided with a solver class through a template
+ * argument, and with a file name (as a string), with which a new file is
+ * constructed in each iteration (named <tt>basename.[step].[suffix]</tt>) and
+ * into which the solution is written as a finite element field using the
+ * DataOut class. Please note that this class may produce enormous amounts of
+ * data!
  *
  * @ingroup output
  * @author Guido Kanschat, 2000
@@ -55,16 +54,11 @@ class DoFPrintSolverStep : public SOLVER
 {
 public:
   /**
-   * Constructor.  First, we take
-   * the arguments needed for the
-   * solver. @p data_out is the
-   * object doing the output as a
-   * finite element function.
+   * Constructor.  First, we take the arguments needed for the solver. @p
+   * data_out is the object doing the output as a finite element function.
    *
-   * One output file with the name
-   * <tt>basename.[step].[suffix]</tt>
-   * will be produced for each
-   * iteration step.
+   * One output file with the name <tt>basename.[step].[suffix]</tt> will be
+   * produced for each iteration step.
    */
   DoFPrintSolverStep (SolverControl &control,
                       VectorMemory<VECTOR> &mem,
@@ -72,8 +66,7 @@ public:
                       const std::string &basename);
 
   /**
-   * Call-back function for the
-   * iterative method.
+   * Call-back function for the iterative method.
    */
   virtual void print_vectors (const unsigned int step,
                               const VECTOR &x,
index 0e2019f4e85552e8a3dcda19a556067db4076650..2cf43e70b58f9ad22c200add4a6f00f0e68495b6 100644 (file)
@@ -40,192 +40,185 @@ namespace hp
 
 
 /**
- *  Implementation of the error indicator by Kelly, Gago, Zienkiewicz
- *  and Babuska.  This error indicator tries to approximate the error
- *  per cell by integration of the jump of the gradient of the
- *  solution along the faces of each cell.  It can be understood as a
- *  gradient recovery estimator; see the survey of Ainsworth for a
- *  complete discussion.
+ * Implementation of the error indicator by Kelly, Gago, Zienkiewicz and
+ * Babuska.  This error indicator tries to approximate the error per cell by
+ * integration of the jump of the gradient of the solution along the faces of
+ * each cell.  It can be understood as a gradient recovery estimator; see the
+ * survey of Ainsworth for a complete discussion.
  *
- *  @note In spite of the name, this is not truly an a posteriori
- *  error estimator, even if applied to the Poisson problem only. It
- *  gives good hints for mesh refinement, but the estimate is not to
- *  be trusted. For higher order trial spaces the integrals computed
- *  here tend to zero faster than the error itself, thus ruling out
- *  the values as error estimators.
+ * @note In spite of the name, this is not truly an a posteriori error
+ * estimator, even if applied to the Poisson problem only. It gives good hints
+ * for mesh refinement, but the estimate is not to be trusted. For higher
+ * order trial spaces the integrals computed here tend to zero faster than the
+ * error itself, thus ruling out the values as error estimators.
  *
- *  The error estimator really only estimates the error for the generalized
- *  Poisson equation $-\nabla\cdot a(x) \nabla u = f$ with either Dirichlet
- *  boundary conditions or generalized Neumann boundary conditions involving
- *  the conormal derivative $a\frac{du}{dn} = g$.
+ * The error estimator really only estimates the error for the generalized
+ * Poisson equation $-\nabla\cdot a(x) \nabla u = f$ with either Dirichlet
+ * boundary conditions or generalized Neumann boundary conditions involving
+ * the conormal derivative $a\frac{du}{dn} = g$.
  *
- *  The error estimator returns a vector of estimated errors per cell which
- *  can be used to feed the <tt>Triangulation<dim>::refine_*</tt> functions. This
- *  vector contains elements of data type @p float, rather than @p double,
- *  since accuracy is not so important here, and since this can save rather
- *  a lot of memory, when using many cells.
+ * The error estimator returns a vector of estimated errors per cell which can
+ * be used to feed the <tt>Triangulation<dim>::refine_*</tt> functions. This
+ * vector contains elements of data type @p float, rather than @p double,
+ * since accuracy is not so important here, and since this can save rather a
+ * lot of memory, when using many cells.
  *
  *
- *  <h3>Implementation</h3>
+ * <h3>Implementation</h3>
  *
- *  In principle, the implementation of the error estimation is simple: let
- *  \f[
- *  \eta_K^2 = \frac h{24} \int_{\partial K} \left[a \frac{\partial u_h}{\partial n}\right]^2 do
- *  \f]
- *  be the error estimator for cell $K$. $[\cdot]$ denotes the jump of the
- *  argument at the face. In the paper of Ainsworth, $h$ is divided by $24$,
- *  but this factor is a bit esoteric, stemming from interpolation estimates
- *  and stability constants which may hold for the Poisson problem, but may
- *  not hold for more general situations. In the implementation, this factor
- *  is considered, but may lead to wrong results. You may scale the vector
- *  appropriately afterwards.
+ * In principle, the implementation of the error estimation is simple: let \f[
+ * \eta_K^2 = \frac h{24} \int_{\partial K} \left[a \frac{\partial
+ * u_h}{\partial n}\right]^2 do \f] be the error estimator for cell $K$.
+ * $[\cdot]$ denotes the jump of the argument at the face. In the paper of
+ * Ainsworth, $h$ is divided by $24$, but this factor is a bit esoteric,
+ * stemming from interpolation estimates and stability constants which may
+ * hold for the Poisson problem, but may not hold for more general situations.
+ * In the implementation, this factor is considered, but may lead to wrong
+ * results. You may scale the vector appropriately afterwards.
  *
- *  To perform the integration, use is made of the FEFaceValues and
- *  FESubfaceValues classes. The integration is performed by looping
- *  over all cells and integrating over faces that are not yet treated.
- *  This way we avoid integration on faces twice, once for each time we
- *  visit one of the adjacent cells. In a second loop over all cells, we
- *  sum up the contributions of the faces (which are the integrated
- *  square of the jumps) of each cell and take the square root.
+ * To perform the integration, use is made of the FEFaceValues and
+ * FESubfaceValues classes. The integration is performed by looping over all
+ * cells and integrating over faces that are not yet treated. This way we
+ * avoid integration on faces twice, once for each time we visit one of the
+ * adjacent cells. In a second loop over all cells, we sum up the
+ * contributions of the faces (which are the integrated square of the jumps)
+ * of each cell and take the square root.
  *
- *  The integration is done using a quadrature formula on the face.
- *  For linear trial functions (FEQ1), the QGauss2 or even the
- *  QMidpoint rule will suffice. For higher order elements, it is
- *  necessary to utilize higher order quadrature formulae as well.
+ * The integration is done using a quadrature formula on the face. For linear
+ * trial functions (FEQ1), the QGauss2 or even the QMidpoint rule will
+ * suffice. For higher order elements, it is necessary to utilize higher order
+ * quadrature formulae as well.
  *
- *  We store the contribution of each face in a @p map, as provided by the
- *  C++ standard library, with the iterator pointing to that face being the
- *  key into the map. In fact, we do not store the indicator per face, but
- *  only the integral listed above. When looping the second time over all
- *  cells, we have to sum up the contributions of the faces, multiply them
- *  with $\frac h{24}$ and take the square root. By doing the multiplication
- *  with $h$ in the second loop, we avoid problems to decide with which $h$
- *  to multiply, that of the cell on the one or that of the cell on the other
- *  side of the face.
+ * We store the contribution of each face in a @p map, as provided by the C++
+ * standard library, with the iterator pointing to that face being the key
+ * into the map. In fact, we do not store the indicator per face, but only the
+ * integral listed above. When looping the second time over all cells, we have
+ * to sum up the contributions of the faces, multiply them with $\frac h{24}$
+ * and take the square root. By doing the multiplication with $h$ in the
+ * second loop, we avoid problems to decide with which $h$ to multiply, that
+ * of the cell on the one or that of the cell on the other side of the face.
  *
- *  $h$ is taken to be the greatest length of the diagonals of the cell. For
- *  more or less uniform cells without deformed angles, this coincides with
- *  the diameter of the cell.
+ * $h$ is taken to be the greatest length of the diagonals of the cell. For
+ * more or less uniform cells without deformed angles, this coincides with the
+ * diameter of the cell.
  *
  *
- *  <h3>Vector-valued functions</h3>
+ * <h3>Vector-valued functions</h3>
  *
- *  If the finite element field for which the error is to be estimated
- *  is vector-valued, i.e. the finite element has more than one
- *  component, then all the above can be applied to all or only some
- *  components at the same time. The main function of this class takes
- *  a list of flags denoting the components for which components the
- *  error estimator is to be applied; by default, it is a list of only
- *  @p trues, meaning that all variables shall be treated.
+ * If the finite element field for which the error is to be estimated is
+ * vector-valued, i.e. the finite element has more than one component, then
+ * all the above can be applied to all or only some components at the same
+ * time. The main function of this class takes a list of flags denoting the
+ * components for which components the error estimator is to be applied; by
+ * default, it is a list of only @p trues, meaning that all variables shall be
+ * treated.
  *
- *  In case the different components of a field have different
- *  physical meaning (for example velocity and pressure in the Stokes
- *  equations), it would be senseless to use the same coefficient for
- *  all components. In that case, you can pass a function with as many
- *  components as there are components in the finite element field and
- *  each component of the error estimator will then be weighted by the
- *  respective component in this coefficient function. In the other
- *  case, when all components have the same meaning (for example the
- *  displacements in Lame's equations of elasticity), you can specify
- *  a scalar coefficient which will then be used for all components.
+ * In case the different components of a field have different physical meaning
+ * (for example velocity and pressure in the Stokes equations), it would be
+ * senseless to use the same coefficient for all components. In that case, you
+ * can pass a function with as many components as there are components in the
+ * finite element field and each component of the error estimator will then be
+ * weighted by the respective component in this coefficient function. In the
+ * other case, when all components have the same meaning (for example the
+ * displacements in Lame's equations of elasticity), you can specify a scalar
+ * coefficient which will then be used for all components.
  *
  *
- *  <h3>%Boundary values</h3>
+ * <h3>%Boundary values</h3>
  *
- *  If the face is at the boundary, i.e. there is no neighboring cell to which
- *  the jump in the gradiend could be computed, there are two possibilities:
- *  <ul>
- *  <li> The face belongs to a Dirichlet boundary. Then the face is not
- *    considered, which can be justified looking at a dual problem technique and
- *    should hold exactly if the boundary can be approximated exactly by the
- *    finite element used (i.e. it is a linear boundary for linear finite elements,
- *    quadratic for isoparametric quadratic elements, etc). For boundaries which
- *    can not be exactly approximated, one should consider the difference
- *    $z-z_h$ on the face, $z$ being a dual problem's solution which is zero at
- *    the true boundary and $z_h$ being an approximation, which in most cases
- *    will be zero on the numerical boundary. Since on the numerical boundary
- *    $z$ will not be zero in general, we would get another term here, but this
- *    one is neglected for practical reasons, in the hope that the error made
- *    here will tend to zero faster than the energy error we wish to estimate.
+ * If the face is at the boundary, i.e. there is no neighboring cell to which
+ * the jump in the gradiend could be computed, there are two possibilities:
+ * <ul>
+ * <li> The face belongs to a Dirichlet boundary. Then the face is not
+ * considered, which can be justified looking at a dual problem technique and
+ * should hold exactly if the boundary can be approximated exactly by the
+ * finite element used (i.e. it is a linear boundary for linear finite
+ * elements, quadratic for isoparametric quadratic elements, etc). For
+ * boundaries which can not be exactly approximated, one should consider the
+ * difference $z-z_h$ on the face, $z$ being a dual problem's solution which
+ * is zero at the true boundary and $z_h$ being an approximation, which in
+ * most cases will be zero on the numerical boundary. Since on the numerical
+ * boundary $z$ will not be zero in general, we would get another term here,
+ * but this one is neglected for practical reasons, in the hope that the error
+ * made here will tend to zero faster than the energy error we wish to
+ * estimate.
  *
- *    Though no integration is necessary, in the list of face contributions we
- *    store a zero for this face, which makes summing up the contributions of
- *    the different faces to the cells easier.
+ * Though no integration is necessary, in the list of face contributions we
+ * store a zero for this face, which makes summing up the contributions of the
+ * different faces to the cells easier.
  *
- *  <li> The face belongs to a Neumann boundary.  In this case, the
- *    contribution of the face $F\in\partial K$ looks like
- *    \f[ \int_F \left|g-a\frac{\partial u_h}{\partial n}\right|^2 ds \f]
- *    where $g$ is the Neumann boundary function. If the finite element is
- *    vector-valued, then obviously the function denoting the Neumann boundary
- *    conditions needs to be vector-valued as well.
+ * <li> The face belongs to a Neumann boundary.  In this case, the
+ * contribution of the face $F\in\partial K$ looks like \f[ \int_F
+ * \left|g-a\frac{\partial u_h}{\partial n}\right|^2 ds \f] where $g$ is the
+ * Neumann boundary function. If the finite element is vector-valued, then
+ * obviously the function denoting the Neumann boundary conditions needs to be
+ * vector-valued as well.
  *
- *  <li> No other boundary conditions are considered.
- *  </ul>
+ * <li> No other boundary conditions are considered.
+ * </ul>
  *
- *  In practice, if you have Robin boundary conditions or are too lazy to
- *  accurately describe Neumann values, then this is rarely an issue: if you
- *  don't say anything in the map about a particular part of the boundary then
- *  the Kelly indicator will simply assume that the solution is correct on
- *  that part of the boundary and not touch it. Of course, if you have a have
- *  a Neumann or Robin boundary, that isn't quite true, there is going to be a
- *  difference between the normal derivative of the numerical solution and the
- *  Neumann values these normal derivatives should equal. So if we simply
- *  ignore those parts of the boundary, we'll underestimate the error. In
- *  practice, this rarely appears to be a problem -- you may not refine the
- *  cell this time around but you'll probably refine it in the next refinement
- *  step and everything is good again. After all, for all problems but the
- *  Laplace equation, the Kelly indicator is only an indicator, not an
- *  estimator, and so the values it computes are not exact error
- *  representations anyway.
+ * In practice, if you have Robin boundary conditions or are too lazy to
+ * accurately describe Neumann values, then this is rarely an issue: if you
+ * don't say anything in the map about a particular part of the boundary then
+ * the Kelly indicator will simply assume that the solution is correct on that
+ * part of the boundary and not touch it. Of course, if you have a have a
+ * Neumann or Robin boundary, that isn't quite true, there is going to be a
+ * difference between the normal derivative of the numerical solution and the
+ * Neumann values these normal derivatives should equal. So if we simply
+ * ignore those parts of the boundary, we'll underestimate the error. In
+ * practice, this rarely appears to be a problem -- you may not refine the
+ * cell this time around but you'll probably refine it in the next refinement
+ * step and everything is good again. After all, for all problems but the
+ * Laplace equation, the Kelly indicator is only an indicator, not an
+ * estimator, and so the values it computes are not exact error
+ * representations anyway.
  *
  *
- *  <h3>Handling of hanging nodes</h3>
+ * <h3>Handling of hanging nodes</h3>
  *
- *  The integration along faces with hanging nodes is quite tricky, since one
- *  of the elements has to be shifted one level up or down. See the
- *  documentation for the FESubFaceValues class for more information about
- *  technical issues regarding this topic.
+ * The integration along faces with hanging nodes is quite tricky, since one
+ * of the elements has to be shifted one level up or down. See the
+ * documentation for the FESubFaceValues class for more information about
+ * technical issues regarding this topic.
  *
- *  In praxi, since we integrate over each face only once, we do this when we
- *  are on the coarser one of the two cells adjacent to a subface (a subface
- *  is defined to be the child of a face; seen from the coarse cell, it is a
- *  subface, while seen from the refined cell it is one of its faces). The
- *  reason is that finding neighborship information is a bit easier then, but
- *  that's all practical reasoning, nothing fundamental.
+ * In praxi, since we integrate over each face only once, we do this when we
+ * are on the coarser one of the two cells adjacent to a subface (a subface is
+ * defined to be the child of a face; seen from the coarse cell, it is a
+ * subface, while seen from the refined cell it is one of its faces). The
+ * reason is that finding neighborship information is a bit easier then, but
+ * that's all practical reasoning, nothing fundamental.
  *
- *  Since we integrate from the coarse side of the face, we have the mother
- *  face readily at hand and store the result of the integration over that
- *  mother face (being the sum of the integrals along the subfaces) in the
- *  abovementioned map of integrals as well. This consumes some memory more
- *  than needed, but makes the summing up of the face contributions to the
- *  cells easier, since then we have the information from all faces of all
- *  cells at hand and need not think about explicitly determining whether
- *  a face was refined or not. The same applies for boundary faces, see
- *  above.
+ * Since we integrate from the coarse side of the face, we have the mother
+ * face readily at hand and store the result of the integration over that
+ * mother face (being the sum of the integrals along the subfaces) in the
+ * abovementioned map of integrals as well. This consumes some memory more
+ * than needed, but makes the summing up of the face contributions to the
+ * cells easier, since then we have the information from all faces of all
+ * cells at hand and need not think about explicitly determining whether a
+ * face was refined or not. The same applies for boundary faces, see above.
  *
  *
- *  <h3>Multiple solution vectors</h3>
+ * <h3>Multiple solution vectors</h3>
  *
- *  In some cases, for example in time-dependent problems, one would
- *  like to compute the error estimates for several solution vectors
- *  on the same grid at once, with the same coefficients, boundary
- *  condition object, etc, e.g. for the solutions on several
- *  successive time steps. One could then call the functions of this
- *  class several times for each solution. However, the largest factor
- *  in the computation of the error estimates (in terms of computing
- *  time) is initialization of FEFaceValues and FESubFaceValues
- *  objects, and iterating through all faces and subfaces. If the
- *  solution vectors live on the same grid, this effort can be reduced
- *  significantly by treating all solution vectors at the same time,
- *  initializing the FEFaceValues objects only once per cell and for
- *  all solution vectors at once, and also only looping through the
- *  triangulation only once. For this reason, besides the @p estimate
- *  function in this class that takes a single input vector and
- *  returns a single output vector, there is also a function that
- *  accepts several in- and output vectors at the same time.
+ * In some cases, for example in time-dependent problems, one would like to
+ * compute the error estimates for several solution vectors on the same grid
+ * at once, with the same coefficients, boundary condition object, etc, e.g.
+ * for the solutions on several successive time steps. One could then call the
+ * functions of this class several times for each solution. However, the
+ * largest factor in the computation of the error estimates (in terms of
+ * computing time) is initialization of FEFaceValues and FESubFaceValues
+ * objects, and iterating through all faces and subfaces. If the solution
+ * vectors live on the same grid, this effort can be reduced significantly by
+ * treating all solution vectors at the same time, initializing the
+ * FEFaceValues objects only once per cell and for all solution vectors at
+ * once, and also only looping through the triangulation only once. For this
+ * reason, besides the @p estimate function in this class that takes a single
+ * input vector and returns a single output vector, there is also a function
+ * that accepts several in- and output vectors at the same time.
  *
- *  @ingroup numerics
- *  @author Wolfgang Bangerth, 1998, 1999, 2000, 2004, 2006; parallelization by Thomas Richter, 2000
+ * @ingroup numerics
+ * @author Wolfgang Bangerth, 1998, 1999, 2000, 2004, 2006; parallelization by
+ * Thomas Richter, 2000
  */
 template <int dim, int spacedim=dim>
 class KellyErrorEstimator
@@ -497,9 +490,9 @@ public:
    * parameters are as in the general case used for 2d and higher.
    *
    * The parameter n_threads is no longer used and will be ignored.
-   * Multithreading is not presently
-   * implemented for 1d, but we retain the respective parameter for
-   * compatibility with the function signature in the general case.
+   * Multithreading is not presently implemented for 1d, but we retain the
+   * respective parameter for compatibility with the function signature in the
+   * general case.
    */
   template <typename InputVector, class DH>
   static void estimate (const Mapping<1,spacedim>  &mapping,
index e008ee67608c1a91b863e374608527be655d3cc9..0c1b9dd6bc1900e815959d6c8d0b6b1225d4ae9d 100644 (file)
@@ -36,66 +36,56 @@ namespace Functions
 {
 
   /**
-   * This is an interpolation function for the given dof handler and
-   * the given solution vector. The points at which this function can
-   * be evaluated MUST be inside the domain of the dof handler, but
-   * except from this, no other requirement is given. This function is
-   * rather slow, as it needs to construct a quadrature object for the
-   * point (or set of points) where you want to evaluate your finite
-   * element function. In order to do so, it needs to find out where
-   * the points lie.
+   * This is an interpolation function for the given dof handler and the given
+   * solution vector. The points at which this function can be evaluated MUST
+   * be inside the domain of the dof handler, but except from this, no other
+   * requirement is given. This function is rather slow, as it needs to
+   * construct a quadrature object for the point (or set of points) where you
+   * want to evaluate your finite element function. In order to do so, it
+   * needs to find out where the points lie.
    *
-   * If you know in advance in which cell your points lie, you can
-   * accelerate things a bit, by calling set_active_cell before
-   * asking for values or gradients of the function. If you don't do
-   * this, and your points don't lie in the cell that is currently
-   * stored, the function GridTools::find_cell_around_point is called
-   * to find out where the point is. You can specify an optional
-   * mapping to use when looking for points in the grid. If you don't
-   * do so, this function uses a Q1 mapping.
+   * If you know in advance in which cell your points lie, you can accelerate
+   * things a bit, by calling set_active_cell before asking for values or
+   * gradients of the function. If you don't do this, and your points don't
+   * lie in the cell that is currently stored, the function
+   * GridTools::find_cell_around_point is called to find out where the point
+   * is. You can specify an optional mapping to use when looking for points in
+   * the grid. If you don't do so, this function uses a Q1 mapping.
    *
    * Once the FEFieldFunction knows where the points lie, it creates a
    * quadrature formula for those points, and calls
-   * FEValues::get_function_values or FEValues::get_function_grads with
-   * the given quadrature points.
+   * FEValues::get_function_values or FEValues::get_function_grads with the
+   * given quadrature points.
    *
-   * If you only need the quadrature points but not the values of the
-   * finite element function (you might want this for the adjoint
-   * interpolation), you can also use the function @p
-   * compute_point_locations alone.
+   * If you only need the quadrature points but not the values of the finite
+   * element function (you might want this for the adjoint interpolation), you
+   * can also use the function @p compute_point_locations alone.
    *
    * An example of how to use this function is the following:
    *
    * \code
    *
-   * // Generate two triangulations
-   * Triangulation<dim> tria_1;
+   * // Generate two triangulations Triangulation<dim> tria_1;
    * Triangulation<dim> tria_2;
    *
-   * // Read the triangulations from files, or build them up, or get
-   * // them from some place...  Assume that tria_2 is *entirely*
-   * // included in tria_1
-   * ...
+   * // Read the triangulations from files, or build them up, or get // them
+   * from some place...  Assume that tria_2 is *entirely* // included in
+   * tria_1 ...
    *
-   * // Associate a dofhandler and a solution to the first
-   * // triangulation
-   * DoFHandler<dim> dh1(tria_1);
-   * Vector<double> solution_1;
+   * // Associate a dofhandler and a solution to the first // triangulation
+   * DoFHandler<dim> dh1(tria_1); Vector<double> solution_1;
    *
-   * // Do the same with the second
-   * DoFHandler<dim> dh2;
-   * Vector<double> solution_2;
+   * // Do the same with the second DoFHandler<dim> dh2; Vector<double>
+   * solution_2;
    *
-   * // Setup the system, assemble matrices, solve problems and get the
-   * // nobel prize on the first domain...
-   * ...
+   * // Setup the system, assemble matrices, solve problems and get the //
+   * nobel prize on the first domain... ...
    *
-   * // Now project it to the second domain
-   * FEFieldFunction<dim> fe_function_1 (dh_1, solution_1);
-   * VectorTools::project(dh_2, constraints_2, quad, fe_function_1, solution_2);
+   * // Now project it to the second domain FEFieldFunction<dim> fe_function_1
+   * (dh_1, solution_1); VectorTools::project(dh_2, constraints_2, quad,
+   * fe_function_1, solution_2);
    *
-   * // Or interpolate it...
-   * Vector<double> solution_3;
+   * // Or interpolate it... Vector<double> solution_3;
    * VectorTools::interpolate(dh_2, fe_function_1, solution_3);
    *
    * \endcode
@@ -103,16 +93,15 @@ namespace Functions
    * The snippet of code above will work assuming that the second
    * triangulation is entirely included in the first one.
    *
-   * FEFieldFunction is designed to be an easy way to get the results of
-   * your computations across different, possibly non matching,
-   * grids. No knowledge of the location of the points is assumed in
-   * this class, which makes it rely entirely on the
-   * GridTools::find_active_cell_around_point utility for its
-   * job. However the class can be fed an "educated guess" of where the
+   * FEFieldFunction is designed to be an easy way to get the results of your
+   * computations across different, possibly non matching, grids. No knowledge
+   * of the location of the points is assumed in this class, which makes it
+   * rely entirely on the GridTools::find_active_cell_around_point utility for
+   * its job. However the class can be fed an "educated guess" of where the
    * points that will be computed actually are by using the
    * FEFieldFunction::set_active_cell method, so if you have a smart way to
-   * tell where your points are, you will save a lot of computational
-   * time by letting this class know.
+   * tell where your points are, you will save a lot of computational time by
+   * letting this class know.
    *
    *
    * <h3>Using FEFieldFunction with parallel::distributed::Triangulation</h3>
@@ -121,22 +110,21 @@ namespace Functions
    * and evaluating the solution at a particular point, not every processor
    * will own the cell at which the solution is evaluated. Rather, it may be
    * that the cell in which this point is found is in fact a ghost or
-   * artificial cell (see @ref GlossArtificialCell and
-   * @ref GlossGhostCell). If the cell is artificial, we have no access
-   * to the solution there and functions that evaluate the solution at
-   * such a point will trigger an exception of type
-   * FEFieldFunction::ExcPointNotAvailableHere. The same kind of exception
-   * will also be produced if the cell is a ghost cell: On such cells, one
-   * could in principle evaluate the solution, but it becomes easier if we
-   * do not allow to do so because then there is exactly one processor in
-   * a parallel distributed computation that can indeed evaluate the
-   * solution. Consequently, it is clear which processor is responsible
+   * artificial cell (see @ref GlossArtificialCell and @ref GlossGhostCell).
+   * If the cell is artificial, we have no access to the solution there and
+   * functions that evaluate the solution at such a point will trigger an
+   * exception of type FEFieldFunction::ExcPointNotAvailableHere. The same
+   * kind of exception will also be produced if the cell is a ghost cell: On
+   * such cells, one could in principle evaluate the solution, but it becomes
+   * easier if we do not allow to do so because then there is exactly one
+   * processor in a parallel distributed computation that can indeed evaluate
+   * the solution. Consequently, it is clear which processor is responsible
    * for producing output if the point evaluation is done as a postprocessing
    * step.
    *
-   * To deal with this situation, you will want to use code as follows
-   * when, for example, evaluating the solution at the origin (here using
-   * a parallel TrilinosWrappers vector to hold the solution):
+   * To deal with this situation, you will want to use code as follows when,
+   * for example, evaluating the solution at the origin (here using a parallel
+   * TrilinosWrappers vector to hold the solution):
    * @code
    *   Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers::MPI::Vector>
    *     solution_function (dof_handler, solution);
@@ -157,11 +145,12 @@ namespace Functions
    *     ...do something...;
    * @endcode
    *
-   * @note To C++, <code>Functions::FEFieldFunction<dim>::ExcPointNotAvailableHere</code>
-   * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers::MPI::Vector>::ExcPointNotAvailableHere</code>
-   * are distinct types. You need to make sure that the type of the exception you
-   * catch matches the type of the object that throws it, as shown in
-   * the example above.
+   * @note To C++,
+   * <code>Functions::FEFieldFunction<dim>::ExcPointNotAvailableHere</code>
+   * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers
+   * ::MPI::Vector>::ExcPointNotAvailableHere</code> are distinct types. You
+   * need to make sure that the type of the exception you catch matches the
+   * type of the object that throws it, as shown in the example above.
    *
    * @ingroup functions
    * @author Luca Heltai, 2006, Markus Buerg, 2012, Wolfgang Bangerth, 2013
@@ -173,109 +162,70 @@ namespace Functions
   {
   public:
     /**
-     * Construct a vector
-     * function. A smart pointers
-     * is stored to the dof
-     * handler, so you have to make
-     * sure that it make sense for
-     * the entire lifetime of this
-     * object. The number of
-     * components of this functions
-     * is equal to the number of
-     * components of the finite
-     * element object. If a mapping
-     * is specified, that is what
-     * is used to find out where
-     * the points lay. Otherwise
-     * the standard Q1 mapping is
-     * used.
+     * Construct a vector function. A smart pointers is stored to the dof
+     * handler, so you have to make sure that it make sense for the entire
+     * lifetime of this object. The number of components of this functions is
+     * equal to the number of components of the finite element object. If a
+     * mapping is specified, that is what is used to find out where the points
+     * lay. Otherwise the standard Q1 mapping is used.
      */
     FEFieldFunction (const DH           &dh,
                      const VECTOR       &data_vector,
                      const Mapping<dim> &mapping = StaticMappingQ1<dim>::mapping);
 
     /**
-     * Set the current cell. If you
-     * know in advance where your
-     * points lie, you can tell
-     * this object by calling this
-     * function. This will speed
-     * things up a little.
+     * Set the current cell. If you know in advance where your points lie, you
+     * can tell this object by calling this function. This will speed things
+     * up a little.
      */
     void set_active_cell (const typename DH::active_cell_iterator &newcell);
 
     /**
-     * Get one vector value at the
-     * given point. It is
-     * inefficient to use single
-     * points. If you need more
-     * than one at a time, use the
-     * vector_value_list()
-     * function. For efficiency
-     * reasons, it is better if all
-     * the points lie on the same
-     * cell. This is not mandatory,
-     * however it does speed things
-     * up.
+     * Get one vector value at the given point. It is inefficient to use
+     * single points. If you need more than one at a time, use the
+     * vector_value_list() function. For efficiency reasons, it is better if
+     * all the points lie on the same cell. This is not mandatory, however it
+     * does speed things up.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void vector_value (const Point<dim> &p,
                                Vector<double>   &values) const;
 
     /**
-     * Return the value of the
-     * function at the given
-     * point. Unless there is only
-     * one component (i.e. the
-     * function is scalar), you
-     * should state the component
-     * you want to have evaluated;
-     * it defaults to zero,
-     * i.e. the first component.
-     * It is inefficient to use
-     * single points. If you need
-     * more than one at a time, use
-     * the vector_value_list
-     * function. For efficiency
-     * reasons, it is better if all
-     * the points lie on the same
-     * cell. This is not mandatory,
-     * however it does speed things
-     * up.
+     * Return the value of the function at the given point. Unless there is
+     * only one component (i.e. the function is scalar), you should state the
+     * component you want to have evaluated; it defaults to zero, i.e. the
+     * first component. It is inefficient to use single points. If you need
+     * more than one at a time, use the vector_value_list function. For
+     * efficiency reasons, it is better if all the points lie on the same
+     * cell. This is not mandatory, however it does speed things up.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual double value (const Point< dim >     &p,
                           const unsigned int  component = 0)    const;
 
     /**
-     * Set @p values to the point
-     * values of the specified
-     * component of the function at
-     * the @p points. It is assumed
-     * that @p values already has
-     * the right size, i.e. the
-     * same size as the points
-     * array. This is rather
-     * efficient if all the points
-     * lie on the same cell. If
-     * this is not the case, things
-     * may slow down a bit.
+     * Set @p values to the point values of the specified component of the
+     * function at the @p points. It is assumed that @p values already has the
+     * right size, i.e. the same size as the points array. This is rather
+     * efficient if all the points lie on the same cell. If this is not the
+     * case, things may slow down a bit.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void value_list (const std::vector<Point< dim > >     &points,
                              std::vector< double > &values,
@@ -283,91 +233,64 @@ namespace Functions
 
 
     /**
-     * Set @p values to the point
-     * values of the function at
-     * the @p points. It is assumed
-     * that @p values already has
-     * the right size, i.e. the
-     * same size as the points
-     * array. This is rather
-     * efficient if all the points
-     * lie on the same cell. If
-     * this is not the case, things
-     * may slow down a bit.
+     * Set @p values to the point values of the function at the @p points. It
+     * is assumed that @p values already has the right size, i.e. the same
+     * size as the points array. This is rather efficient if all the points
+     * lie on the same cell. If this is not the case, things may slow down a
+     * bit.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void vector_value_list (const std::vector<Point< dim > >     &points,
                                     std::vector< Vector<double> > &values) const;
 
     /**
-     * Return the gradient of all
-     * components of the function
-     * at the given point.  It is
-     * inefficient to use single
-     * points. If you need more
-     * than one at a time, use the
-     * vector_value_list
-     * function. For efficiency
-     * reasons, it is better if all
-     * the points lie on the same
-     * cell. This is not mandatory,
-     * however it does speed things
-     * up.
+     * Return the gradient of all components of the function at the given
+     * point.  It is inefficient to use single points. If you need more than
+     * one at a time, use the vector_value_list function. For efficiency
+     * reasons, it is better if all the points lie on the same cell. This is
+     * not mandatory, however it does speed things up.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     vector_gradient (const Point< dim > &p,
                      std::vector< Tensor< 1, dim > > &gradients) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at the given point.
-     * It is inefficient to use
-     * single points. If you need
-     * more than one at a time, use
-     * the vector_value_list
-     * function. For efficiency
-     * reasons, it is better if all
-     * the points lie on the same
-     * cell. This is not mandatory,
-     * however it does speed things
-     * up.
+     * Return the gradient of the specified component of the function at the
+     * given point. It is inefficient to use single points. If you need more
+     * than one at a time, use the vector_value_list function. For efficiency
+     * reasons, it is better if all the points lie on the same cell. This is
+     * not mandatory, however it does speed things up.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual Tensor<1,dim> gradient(const Point< dim > &p,
                                    const unsigned int component = 0)const;
 
     /**
-     * Return the gradient of all
-     * components of the function
-     * at all the given points.
-     * This is rather efficient if
-     * all the points lie on the
-     * same cell. If this is not
-     * the case, things may slow
-     * down a bit.
+     * Return the gradient of all components of the function at all the given
+     * points. This is rather efficient if all the points lie on the same
+     * cell. If this is not the case, things may slow down a bit.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     vector_gradient_list (const std::vector< Point< dim > > &p,
@@ -375,20 +298,15 @@ namespace Functions
                           std::vector< Tensor< 1, dim > > > &gradients) const;
 
     /**
-     * Return the gradient of the
-     * specified component of the
-     * function at all the given
-     * points.  This is rather
-     * efficient if all the points
-     * lie on the same cell. If
-     * this is not the case, things
-     * may slow down a bit.
+     * Return the gradient of the specified component of the function at all
+     * the given points.  This is rather efficient if all the points lie on
+     * the same cell. If this is not the case, things may slow down a bit.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     gradient_list (const std::vector< Point< dim > > &p,
@@ -397,43 +315,40 @@ namespace Functions
 
 
     /**
-     * Compute the Laplacian of a
-     * given component at point <tt>p</tt>.
+     * Compute the Laplacian of a given component at point <tt>p</tt>.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual double
     laplacian (const Point<dim>   &p,
                const unsigned int  component = 0) const;
 
     /**
-     * Compute the Laplacian of all
-     * components at point <tt>p</tt> and
-     * store them in <tt>values</tt>.
+     * Compute the Laplacian of all components at point <tt>p</tt> and store
+     * them in <tt>values</tt>.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     vector_laplacian (const Point<dim>   &p,
                       Vector<double>     &values) const;
 
     /**
-     * Compute the Laplacian of one
-     * component at a set of points.
+     * Compute the Laplacian of one component at a set of points.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     laplacian_list (const std::vector<Point<dim> > &points,
@@ -441,43 +356,28 @@ namespace Functions
                     const unsigned int              component = 0) const;
 
     /**
-     * Compute the Laplacians of all
-     * components at a set of points.
+     * Compute the Laplacians of all components at a set of points.
      *
-     * @note When using this function on a parallel::distributed::Triangulation
-     * you may get an exception when trying to evaluate the solution at a
-     * point that does not lie in a locally owned cell (see
-     * @ref GlossLocallyOwnedCell). See the section in the general
-     * documentation of this class for more information.
+     * @note When using this function on a
+     * parallel::distributed::Triangulation you may get an exception when
+     * trying to evaluate the solution at a point that does not lie in a
+     * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+     * the general documentation of this class for more information.
      */
     virtual void
     vector_laplacian_list (const std::vector<Point<dim> > &points,
                            std::vector<Vector<double> >   &values) const;
 
     /**
-     * Create quadrature
-     * rules. This function groups
-     * the points into blocks that
-     * live in the same cell, and
-     * fills up three vectors: @p
-     * cells, @p qpoints and @p
-     * maps. The first is a list of
-     * the cells that contain the
-     * points, the second is a list
-     * of quadrature points
-     * matching each cell of the
-     * first list, and the third
-     * contains the index of the
-     * given quadrature points,
-     * i.e., @p points[maps[3][4]]
-     * ends up as the 5th
-     * quadrature point in the 4th
-     * cell. This is where
-     * optimization would
-     * help. This function returns
-     * the number of cells that
-     * contain the given set of
-     * points.
+     * Create quadrature rules. This function groups the points into blocks
+     * that live in the same cell, and fills up three vectors: @p cells, @p
+     * qpoints and @p maps. The first is a list of the cells that contain the
+     * points, the second is a list of quadrature points matching each cell of
+     * the first list, and the third contains the index of the given
+     * quadrature points, i.e., @p points[maps[3][4]] ends up as the 5th
+     * quadrature point in the 4th cell. This is where optimization would
+     * help. This function returns the number of cells that contain the given
+     * set of points.
      */
     unsigned int
     compute_point_locations(const std::vector<Point<dim> > &points,
@@ -504,14 +404,12 @@ namespace Functions
     SmartPointer<const DH,FEFieldFunction<dim, DH, VECTOR> > dh;
 
     /**
-     * A reference to the actual
-     * data vector.
+     * A reference to the actual data vector.
      */
     const VECTOR &data_vector;
 
     /**
-     * A reference to the mapping
-     * being used.
+     * A reference to the mapping being used.
      */
     const Mapping<dim> &mapping;
 
@@ -521,20 +419,15 @@ namespace Functions
     mutable cell_hint_t cell_hint;
 
     /**
-     * Store the number of
-     * components of this function.
+     * Store the number of components of this function.
      */
     const unsigned int n_components;
 
     /**
-    * Given a cell, return the
-    * reference coordinates of the
-    * given point within this cell
-    * if it indeed lies within the
-    * cell. Otherwise return an
-    * uninitialized
-    * boost::optional object.
-    */
+     * Given a cell, return the reference coordinates of the given point
+     * within this cell if it indeed lies within the cell. Otherwise return an
+     * uninitialized boost::optional object.
+     */
     boost::optional<Point<dim> >
     get_reference_coordinates (const typename DH::active_cell_iterator &cell,
                                const Point<dim>                        &point) const;
index a9716cfefa68fbc49361aa59083bc1023d501cad..98b71e19d5b61550ca3ed91cd3f4153ba23b07f4 100644 (file)
@@ -27,15 +27,15 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * This class provides some facilities to generate 2d and 3d histograms.
- * It is used by giving it one or several data sets and a rule how to
- * break the range of values therein into intervals (e.g. linear spacing
- * or logarithmic spacing of intervals). The values are then sorted into
- * the different intervals and the number of values in each interval is
- * stored for output later. In case only one data set was given, the
- * resulting histogram will be a 2d one, while it will be a 3d one if
- * more than one data set was given. For more than one data set, the same
- * intervals are used for each of them anyway, to make comparison easier.
+ * This class provides some facilities to generate 2d and 3d histograms. It is
+ * used by giving it one or several data sets and a rule how to break the
+ * range of values therein into intervals (e.g. linear spacing or logarithmic
+ * spacing of intervals). The values are then sorted into the different
+ * intervals and the number of values in each interval is stored for output
+ * later. In case only one data set was given, the resulting histogram will be
+ * a 2d one, while it will be a 3d one if more than one data set was given.
+ * For more than one data set, the same intervals are used for each of them
+ * anyway, to make comparison easier.
  *
  *
  * <h3>Ways to generate the intervals</h3>
@@ -43,20 +43,19 @@ DEAL_II_NAMESPACE_OPEN
  * At present, the following schemes for interval spacing are implemented:
  * <ul>
  * <li> Linear spacing: The intervals are distributed in constant steps
- *    between the minimum and maximum values of the data.
- * <li> Logaritmic spacing: The intervals are distributed in constant
- *    steps between the minimum and maximum values of the logs of the values.
- *    This scheme is only useful if the data has only positive values.
- *    Negative and zero values are sorted into the leftmost interval.
+ * between the minimum and maximum values of the data.
+ * <li> Logaritmic spacing: The intervals are distributed in constant steps
+ * between the minimum and maximum values of the logs of the values. This
+ * scheme is only useful if the data has only positive values. Negative and
+ * zero values are sorted into the leftmost interval.
  * </ul>
  *
- * To keep programs extendible, you can use the two functions
- * @p get_interval_spacing_names and @p parse_interval_spacing, which always
- * give you a complete list of spacing formats presently supported and are
- * able to generate the respective value of the @p enum. If you use them,
- * you can write your program in a way such that it only needs to be
- * recompiled to take effect of newly added formats, without changing your
- * code.
+ * To keep programs extendible, you can use the two functions @p
+ * get_interval_spacing_names and @p parse_interval_spacing, which always give
+ * you a complete list of spacing formats presently supported and are able to
+ * generate the respective value of the @p enum. If you use them, you can
+ * write your program in a way such that it only needs to be recompiled to
+ * take effect of newly added formats, without changing your code.
  *
  *
  * <h3>Output formats</h3>
@@ -71,8 +70,7 @@ class Histogram
 {
 public:
   /**
-   * Definition of several ways to arrange
-   * the spacing of intervals.
+   * Definition of several ways to arrange the spacing of intervals.
    */
   enum IntervalSpacing
   {
@@ -81,40 +79,27 @@ public:
 
 
   /**
-   * Take several lists of values, each on
-   * to produce one histogram that will
+   * Take several lists of values, each on to produce one histogram that will
    * then be arrange one behind each other.
    *
-   * Using several data sets at once allows
-   * to compare them more easily, since
-   * the intervals into which the data is
-   * sorted is the same for all data sets.
+   * Using several data sets at once allows to compare them more easily, since
+   * the intervals into which the data is sorted is the same for all data
+   * sets.
    *
-   * The histograms will be arranged such
-   * that the computed intervals of the
-   * <tt>values[i][j]</tt> form the x-range,
-   * and the number of values in each
-   * interval will be the y-range (for
-   * 2d plots) or the z-range (for 3d
-   * plots). For 3d plots, the @p y_values
-   * parameter is used to assign each
-   * data set a value in the y direction,
-   * which is the depth coordinate in the
-   * resulting plot. For 2d plots,
-   * the @p y_values are ignored.
+   * The histograms will be arranged such that the computed intervals of the
+   * <tt>values[i][j]</tt> form the x-range, and the number of values in each
+   * interval will be the y-range (for 2d plots) or the z-range (for 3d
+   * plots). For 3d plots, the @p y_values parameter is used to assign each
+   * data set a value in the y direction, which is the depth coordinate in the
+   * resulting plot. For 2d plots, the @p y_values are ignored.
    *
-   * If you give only one data set, i.e.
-   * <tt>values.size()==1</tt>, then the
-   * resulting histogram will be a 2d
-   * one.
+   * If you give only one data set, i.e. <tt>values.size()==1</tt>, then the
+   * resulting histogram will be a 2d one.
    *
-   * @p n_intervals denotes the number of
-   * intervals into which the data will be
-   * sorted; @p interval_spacing denotes
-   * the way the bounds of the intervals
-   * are computed. Refer to the general
-   * documentation for more information
-   * on this.
+   * @p n_intervals denotes the number of intervals into which the data will
+   * be sorted; @p interval_spacing denotes the way the bounds of the
+   * intervals are computed. Refer to the general documentation for more
+   * information on this.
    */
   template <typename number>
   void evaluate (const std::vector<Vector<number> > &values,
@@ -123,9 +108,8 @@ public:
                  const IntervalSpacing                        interval_spacing = linear);
 
   /**
-   * This function is only a wrapper
-   * to the above one in case you have
-   * only one data set.
+   * This function is only a wrapper to the above one in case you have only
+   * one data set.
    */
   template <typename number>
   void evaluate (const Vector<number>          &values,
@@ -133,34 +117,28 @@ public:
                  const IntervalSpacing          interval_spacing = linear);
 
   /**
-   * Write the histogram computed by
-   * the @p evaluate function to a
-   * stream in a format suitable to
-   * the GNUPLOT program. The function
-   * generates 2d or 3d histograms.
+   * Write the histogram computed by the @p evaluate function to a stream in a
+   * format suitable to the GNUPLOT program. The function generates 2d or 3d
+   * histograms.
    */
   void write_gnuplot (std::ostream &out) const;
 
   /**
-   * Return allowed names for the interval
-   * spacing as string. At present this
+   * Return allowed names for the interval spacing as string. At present this
    * is "linear|logarithmic".
    */
   static std::string get_interval_spacing_names ();
 
   /**
-   * Get a string containing one of the
-   * names returned by the above function
-   * and return the respective value of
-   * @p IntervalSpacing. Throw an error
-   * if the string is no valid one.
+   * Get a string containing one of the names returned by the above function
+   * and return the respective value of @p IntervalSpacing. Throw an error if
+   * the string is no valid one.
    */
   static IntervalSpacing parse_interval_spacing (const std::string &name);
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -193,23 +171,20 @@ public:
 
 private:
   /**
-   * Structure denoting one
-   * interval.
+   * Structure denoting one interval.
    */
   struct Interval
   {
     /**
-     * Constructor. Sets the
-     * bounds and sets the number of
-     * values in this interval to zero.
+     * Constructor. Sets the bounds and sets the number of values in this
+     * interval to zero.
      */
     Interval (const double left_point,
               const double right_point);
 
     /**
-     * Determine an estimate for the
-     * memory consumption (in bytes)
-     * of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
@@ -224,43 +199,33 @@ private:
     double       right_point;
 
     /**
-     * Number of values in this
-     * interval.
+     * Number of values in this interval.
      */
     unsigned int content;
   };
 
   /**
-   * "Less-than" operation which
-   * finds the minimal positive value
-   * by sorting zero and negative value
-   * to be larger than the largest positive
-   * number. Used to find the lower bound
-   * of the leftmost interval in the
-   * logarithmic case interval spacing
-   * scheme.
+   * "Less-than" operation which finds the minimal positive value by sorting
+   * zero and negative value to be larger than the largest positive number.
+   * Used to find the lower bound of the leftmost interval in the logarithmic
+   * case interval spacing scheme.
    *
-   * Return @p true, if (<tt>n1<n2</tt>,
-   * and (<tt>n1>0</tt> or <tt>n2<0</tt>)), or
-   * (n2<n1 and n1>0 and n2<=0). This
-   * in effect sorts all negativ
-   * numbers to be larger than the
-   * largest positive number.
+   * Return @p true, if (<tt>n1<n2</tt>, and (<tt>n1>0</tt> or
+   * <tt>n2<0</tt>)), or (n2<n1 and n1>0 and n2<=0). This in effect sorts all
+   * negativ numbers to be larger than the largest positive number.
    */
   template <typename number>
   static bool logarithmic_less (const number n1,
                                 const number n2);
 
   /**
-   * Vector holding one set of intervals
-   * for each data set given to the
-   * @p evaluate function.
+   * Vector holding one set of intervals for each data set given to the @p
+   * evaluate function.
    */
   std::vector<std::vector<Interval> > intervals;
 
   /**
-   * Values for the depth axis of 3d
-   * histograms. Stored in the @p evaluate
+   * Values for the depth axis of 3d histograms. Stored in the @p evaluate
    * function.
    */
   std::vector<double>            y_values;
index 42aad35a5a56ebdf4f595821cb051d261dd549d4..71afd6ae476ad12c51719310340b5c4e2a912ac0 100644 (file)
@@ -85,99 +85,91 @@ namespace TrilinosWrappers
 
 
 /**
- * This namespace provides functions that assemble certain standard matrices for a
- * given triangulation, using a given finite element, a given mapping and a
- * quadrature formula.
+ * This namespace provides functions that assemble certain standard matrices
+ * for a given triangulation, using a given finite element, a given mapping
+ * and a quadrature formula.
  *
  *
  * <h3>Conventions for all functions</h3>
  *
- * There exist two versions of each function. One with a Mapping
- * argument and one without. If a code uses a mapping different from
- * MappingQ1 the functions <em>with</em> mapping argument should
- * be used. Code that uses only MappingQ1 may also use the
- * functions <em>without</em> Mapping argument. Each of these
- * latter functions create a MappingQ1 object and just call the
- * respective functions with that object as mapping argument.
+ * There exist two versions of each function. One with a Mapping argument and
+ * one without. If a code uses a mapping different from MappingQ1 the
+ * functions <em>with</em> mapping argument should be used. Code that uses
+ * only MappingQ1 may also use the functions <em>without</em> Mapping
+ * argument. Each of these latter functions create a MappingQ1 object and just
+ * call the respective functions with that object as mapping argument.
  *
- * All functions take a sparse matrix object to hold the matrix to be
- * created. The functions assume that the matrix is initialized with a
- * sparsity pattern (SparsityPattern) corresponding to the given degree
- * of freedom handler, i.e. the sparsity structure is already as needed.
- * You can do this by calling the DoFTools::make_sparsity_pattern()
- * function.
+ * All functions take a sparse matrix object to hold the matrix to be created.
+ * The functions assume that the matrix is initialized with a sparsity pattern
+ * (SparsityPattern) corresponding to the given degree of freedom handler,
+ * i.e. the sparsity structure is already as needed. You can do this by
+ * calling the DoFTools::make_sparsity_pattern() function.
  *
  * Furthermore it is assumed that no relevant data is in the matrix. Some
  * entries will be overwritten and some others will contain invalid data if
  * the matrix wasn't empty before. Therefore you may want to clear the matrix
  * before assemblage.
  *
- * By default, all created matrices are `raw': they are not condensed,
- * i.e. hanging nodes are not eliminated. The reason is that you may
- * want to add several matrices and could then condense afterwards
- * only once, instead of for every matrix. To actually do computations
- * with these matrices, you have to condense the matrix using the
- * ConstraintMatrix::condense function; you also have to
- * condense the right hand side accordingly and distribute the
+ * By default, all created matrices are `raw': they are not condensed, i.e.
+ * hanging nodes are not eliminated. The reason is that you may want to add
+ * several matrices and could then condense afterwards only once, instead of
+ * for every matrix. To actually do computations with these matrices, you have
+ * to condense the matrix using the ConstraintMatrix::condense function; you
+ * also have to condense the right hand side accordingly and distribute the
  * solution afterwards. Alternatively, you can give an optional argument
  * ConstraintMatrix that writes cell matrix (and vector) entries with
  * distribute_local_to_global into the global matrix and vector. This way,
- * adding several matrices from different sources is more complicated and
- * you should make sure that you do not mix different ways of applying
- * constraints. Particular caution is necessary when the given
- * constraint matrix contains inhomogeneous constraints: In that case, the
- * matrix assembled this way must be the only matrix (or you need to
- * assemble the <b>same</b> right hand side for <b>every</b> matrix
- * you generate and add together).
+ * adding several matrices from different sources is more complicated and you
+ * should make sure that you do not mix different ways of applying
+ * constraints. Particular caution is necessary when the given constraint
+ * matrix contains inhomogeneous constraints: In that case, the matrix
+ * assembled this way must be the only matrix (or you need to assemble the
+ * <b>same</b> right hand side for <b>every</b> matrix you generate and add
+ * together).
  *
- * If you want to use boundary conditions with the matrices generated
- * by the functions of this class in addition to the ones in a possible
- * constraint matrix, you have to use a function like
- * <tt>ProblemBase<>::apply_dirichlet_bc</tt> to matrix and right hand
- * side.
+ * If you want to use boundary conditions with the matrices generated by the
+ * functions of this class in addition to the ones in a possible constraint
+ * matrix, you have to use a function like
+ * <tt>ProblemBase<>::apply_dirichlet_bc</tt> to matrix and right hand side.
  *
  *
  * <h3>Supported matrices</h3>
  *
  * At present there are functions to create the following matrices:
  * <ul>
- * <li> @p create_mass_matrix: create the matrix with entries
- *   $m_{ij} = \int_\Omega \phi_i(x) \phi_j(x) dx$ by numerical
- *   quadrature. Here, the $\phi_i$ are the basis functions of the
- *   finite element space given.
+ * <li> @p create_mass_matrix: create the matrix with entries $m_{ij} =
+ * \int_\Omega \phi_i(x) \phi_j(x) dx$ by numerical quadrature. Here, the
+ * $\phi_i$ are the basis functions of the finite element space given.
  *
- *   A coefficient may be given to evaluate
- *   $m_{ij} = \int_\Omega a(x) \phi_i(x) \phi_j(x) dx$ instead.
+ * A coefficient may be given to evaluate $m_{ij} = \int_\Omega a(x) \phi_i(x)
+ * \phi_j(x) dx$ instead.
  *
- * <li> @p create_laplace_matrix: create the matrix with entries
- *   $a_{ij} = \int_\Omega \nabla\phi_i(x) \nabla\phi_j(x) dx$ by
- *   numerical quadrature.
+ * <li> @p create_laplace_matrix: create the matrix with entries $a_{ij} =
+ * \int_\Omega \nabla\phi_i(x) \nabla\phi_j(x) dx$ by numerical quadrature.
  *
- *   Again, a coefficient may be given to evaluate
- *   $a_{ij} = \int_\Omega a(x) \nabla\phi_i(x) \nabla\phi_j(x) dx$ instead.
+ * Again, a coefficient may be given to evaluate $a_{ij} = \int_\Omega a(x)
+ * \nabla\phi_i(x) \nabla\phi_j(x) dx$ instead.
  * </ul>
  *
- * Make sure that the order of the Quadrature formula given to these
- * functions is sufficiently high to compute the matrices with the
- * required accuracy. For the choice of this quadrature rule you need
- * to take into account the polynomial degree of the FiniteElement
- * basis functions, the roughness of the coefficient @p a, as well as
- * the degree of the given @p Mapping (if any).
+ * Make sure that the order of the Quadrature formula given to these functions
+ * is sufficiently high to compute the matrices with the required accuracy.
+ * For the choice of this quadrature rule you need to take into account the
+ * polynomial degree of the FiniteElement basis functions, the roughness of
+ * the coefficient @p a, as well as the degree of the given @p Mapping (if
+ * any).
  *
- * Note, that for vector-valued elements the mass matrix and the
- * laplace matrix is implemented in such a way that each component
- * couples only with itself, i.e. there is no coupling of shape
- * functions belonging to different components. If the degrees of
- * freedom have been sorted according to their vector component (e.g.,
- * using DoFRenumbering::component_wise()), then the resulting
- * matrices will be block diagonal.
+ * Note, that for vector-valued elements the mass matrix and the laplace
+ * matrix is implemented in such a way that each component couples only with
+ * itself, i.e. there is no coupling of shape functions belonging to different
+ * components. If the degrees of freedom have been sorted according to their
+ * vector component (e.g., using DoFRenumbering::component_wise()), then the
+ * resulting matrices will be block diagonal.
  *
- * If the finite element for which the mass matrix or the Laplace
- * matrix is to be built has more than one component, the functions
- * accept a single coefficient as well as a vector valued coefficient
- * function. For the latter case, the number of components must
- * coincide with the number of components of the system finite
- * element.
+ * If the finite element for which the mass matrix or the Laplace matrix is to
+ * be built has more than one component, the functions accept a single
+ * coefficient as well as a vector valued coefficient function. For the latter
+ * case, the number of components must coincide with the number of components
+ * of the system finite element.
  *
  *
  * <h3>Matrices on the boundary</h3>
@@ -212,15 +204,13 @@ namespace TrilinosWrappers
  *
  * <h3>Right hand sides</h3>
  *
- * In many cases, you will not only want to build the matrix, but also
- * a right hand side, which will give a vector with
- * $f_i = \int_\Omega f(x) \phi_i(x) dx$. For this purpose, each function
- * exists in two versions, one only building the matrix and one also
- * building the right hand side vector. If you want to create a right
- * hand side vector without creating a matrix, you can use the
- * VectorTools::create_right_hand_side() function. The use of the
- * latter may be useful if you want to create many right hand side
- * vectors.
+ * In many cases, you will not only want to build the matrix, but also a right
+ * hand side, which will give a vector with $f_i = \int_\Omega f(x) \phi_i(x)
+ * dx$. For this purpose, each function exists in two versions, one only
+ * building the matrix and one also building the right hand side vector. If
+ * you want to create a right hand side vector without creating a matrix, you
+ * can use the VectorTools::create_right_hand_side() function. The use of the
+ * latter may be useful if you want to create many right hand side vectors.
  *
  * @ingroup numerics
  * @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
@@ -228,18 +218,18 @@ namespace TrilinosWrappers
 namespace MatrixCreator
 {
   /**
-   * Assemble the mass matrix. If no coefficient is given (i.e., if
-   * the pointer to a function object is zero as it is by default),
-   * the coefficient is taken as being constant and equal to one.
+   * Assemble the mass matrix. If no coefficient is given (i.e., if the
+   * pointer to a function object is zero as it is by default), the
+   * coefficient is taken as being constant and equal to one.
    *
    * If the library is configured to use multithreading, this function works
    * in parallel.
    *
-   * The optional argument @p constraints allows to apply constraints
-   * on the resulting matrix directly. Note, however, that this
-   * becomes difficult when you have inhomogeneous constraints and
-   * later want to add several such matrices, for example in time
-   * dependent settings such as the main loop of step-26.
+   * The optional argument @p constraints allows to apply constraints on the
+   * resulting matrix directly. Note, however, that this becomes difficult
+   * when you have inhomogeneous constraints and later want to add several
+   * such matrices, for example in time dependent settings such as the main
+   * loop of step-26.
    *
    * See the general doc of this class for more information.
    */
@@ -263,19 +253,18 @@ namespace MatrixCreator
                            const ConstraintMatrix   &constraints = ConstraintMatrix());
 
   /**
-   * Assemble the mass matrix and a right hand side vector. If no
-   * coefficient is given (i.e., if the pointer to a function object
-   * is zero as it is by default), the coefficient is taken as being
-   * constant and equal to one.
+   * Assemble the mass matrix and a right hand side vector. If no coefficient
+   * is given (i.e., if the pointer to a function object is zero as it is by
+   * default), the coefficient is taken as being constant and equal to one.
    *
    * If the library is configured to use multithreading, this function works
    * in parallel.
    *
    * The optional argument @p constraints allows to apply constraints on the
-   * resulting matrix directly. Note, however, that this
-   * becomes difficult when you have inhomogeneous constraints and
-   * later want to add several such matrices, for example in time
-   * dependent settings such as the main loop of step-26.
+   * resulting matrix directly. Note, however, that this becomes difficult
+   * when you have inhomogeneous constraints and later want to add several
+   * such matrices, for example in time dependent settings such as the main
+   * loop of step-26.
    *
    * See the general doc of this class for more information.
    */
@@ -465,18 +454,18 @@ namespace MatrixCreator
                                     std::vector<unsigned int> component_mapping = std::vector<unsigned int>());
 
   /**
-   * Assemble the Laplace matrix. If no coefficient is given (i.e., if
-   * the pointer to a function object is zero as it is by default),
-   * the coefficient is taken as being constant and equal to one.
+   * Assemble the Laplace matrix. If no coefficient is given (i.e., if the
+   * pointer to a function object is zero as it is by default), the
+   * coefficient is taken as being constant and equal to one.
    *
    * If the library is configured to use multithreading, this function works
    * in parallel.
    *
    * The optional argument @p constraints allows to apply constraints on the
-   * resulting matrix directly. Note, however, that this
-   * becomes difficult when you have inhomogeneous constraints and
-   * later want to add several such matrices, for example in time
-   * dependent settings such as the main loop of step-26.
+   * resulting matrix directly. Note, however, that this becomes difficult
+   * when you have inhomogeneous constraints and later want to add several
+   * such matrices, for example in time dependent settings such as the main
+   * loop of step-26.
    *
    * See the general doc of this class for more information.
    */
@@ -507,10 +496,10 @@ namespace MatrixCreator
    * in parallel.
    *
    * The optional argument @p constraints allows to apply constraints on the
-   * resulting matrix directly. Note, however, that this
-   * becomes difficult when you have inhomogeneous constraints and
-   * later want to add several such matrices, for example in time
-   * dependent settings such as the main loop of step-26.
+   * resulting matrix directly. Note, however, that this becomes difficult
+   * when you have inhomogeneous constraints and later want to add several
+   * such matrices, for example in time dependent settings such as the main
+   * loop of step-26.
    *
    * See the general doc of this class for more information.
    */
@@ -596,18 +585,17 @@ namespace MatrixCreator
 
 
 /**
- * Provide a collection of functions operating on matrices. These include
- * the application of boundary conditions to a linear system of equations
- * and others.
+ * Provide a collection of functions operating on matrices. These include the
+ * application of boundary conditions to a linear system of equations and
+ * others.
  *
  *
  * <h3>Boundary conditions</h3>
  *
- * The apply_boundary_values() function inserts boundary conditions
- * into a system of equations.  To actually do this you have to
- * specify a list of degree of freedom indices along with the values
- * these degrees of freedom shall assume. To see how to get such a
- * list, see the discussion of the
+ * The apply_boundary_values() function inserts boundary conditions into a
+ * system of equations.  To actually do this you have to specify a list of
+ * degree of freedom indices along with the values these degrees of freedom
+ * shall assume. To see how to get such a list, see the discussion of the
  * VectorTools::interpolate_boundary_values function.
  *
  * There are two ways to incorporate fixed degrees of freedom such as boundary
@@ -637,52 +625,47 @@ namespace MatrixCreator
  * particular structure.
  *
  * Finding which rows contain an entry in the column for which we are
- * presently performing a Gauss elimination step is either difficult
- * or very simple, depending on the circumstances. If the sparsity
- * pattern is symmetric (whether the matrix is symmetric is irrelevant
- * here), then we can infer the rows which have a nonzero entry in the
- * present column by looking at which columns in the present row are
- * nonempty. In this case, we only need to look into a fixed number of
- * rows and need not search all rows. On the other hand, if the
- * sparsity pattern is nonsymmetric, then we need to use an iterative
- * solver which can handle nonsymmetric matrices in any case, so there
- * may be no need to do the Gauss elimination anyway. In fact, this is
- * the way the function works: it takes a parameter
- * (@p eliminate_columns) that specifies whether the sparsity pattern
- * is symmetric; if so, then the column is eliminated and the right
- * hand side is also modified accordingly. If not, then only the row
- * is deleted and the column is not touched at all, and all right hand
- * side values apart from the one corresponding to the present row
- * remain unchanged.
- *
- * If the sparsity pattern for your matrix is non-symmetric, you must
- * set the value of this parameter to @p false in any case, since then
- * we can't eliminate the column without searching all rows, which
- * would be too expensive (if @p N be the number of rows, and @p m the
- * number of nonzero elements per row, then eliminating one column is
- * an <tt>O(N*log(m))</tt> operation, since searching in each row takes
- * <tt>log(m)</tt> operations). If your sparsity pattern is symmetric, but
- * your matrix is not, then you might specify @p false as well. If your
- * sparsity pattern and matrix are both symmetric, you might want to
- * specify @p true (the complexity of eliminating one row is then
- * <tt>O(m*log(m))</tt>, since we only have to search @p m rows for the
- * respective element of the column). Given the fact that @p m is
- * roughly constant, irrespective of the discretization, and that the
- * number of boundary nodes is <tt>sqrt(N)</tt> in 2d, the algorithm for
- * symmetric sparsity patterns is <tt>O(sqrt(N)*m*log(m))</tt>, while it
- * would be <tt>O(N*sqrt(N)*log(m))</tt> for the general case; the latter
- * is too expensive to be performed.
- *
- * It seems as if we had to make clear not to overwrite the lines of
- * other boundary nodes when doing the Gauss elimination
- * step. However, since we reset the right hand side when passing such
- * a node, it is not a problem to change the right hand side values of
- * other boundary nodes not yet processed. It would be a problem to
- * change those entries of nodes already processed, but since the
- * matrix entry of the present column on the row of an already
- * processed node is zero, the Gauss step does not change the right
- * hand side. We need therefore not take special care of other
- * boundary nodes.
+ * presently performing a Gauss elimination step is either difficult or very
+ * simple, depending on the circumstances. If the sparsity pattern is
+ * symmetric (whether the matrix is symmetric is irrelevant here), then we can
+ * infer the rows which have a nonzero entry in the present column by looking
+ * at which columns in the present row are nonempty. In this case, we only
+ * need to look into a fixed number of rows and need not search all rows. On
+ * the other hand, if the sparsity pattern is nonsymmetric, then we need to
+ * use an iterative solver which can handle nonsymmetric matrices in any case,
+ * so there may be no need to do the Gauss elimination anyway. In fact, this
+ * is the way the function works: it takes a parameter (@p eliminate_columns)
+ * that specifies whether the sparsity pattern is symmetric; if so, then the
+ * column is eliminated and the right hand side is also modified accordingly.
+ * If not, then only the row is deleted and the column is not touched at all,
+ * and all right hand side values apart from the one corresponding to the
+ * present row remain unchanged.
+ *
+ * If the sparsity pattern for your matrix is non-symmetric, you must set the
+ * value of this parameter to @p false in any case, since then we can't
+ * eliminate the column without searching all rows, which would be too
+ * expensive (if @p N be the number of rows, and @p m the number of nonzero
+ * elements per row, then eliminating one column is an <tt>O(N*log(m))</tt>
+ * operation, since searching in each row takes <tt>log(m)</tt> operations).
+ * If your sparsity pattern is symmetric, but your matrix is not, then you
+ * might specify @p false as well. If your sparsity pattern and matrix are
+ * both symmetric, you might want to specify @p true (the complexity of
+ * eliminating one row is then <tt>O(m*log(m))</tt>, since we only have to
+ * search @p m rows for the respective element of the column). Given the fact
+ * that @p m is roughly constant, irrespective of the discretization, and that
+ * the number of boundary nodes is <tt>sqrt(N)</tt> in 2d, the algorithm for
+ * symmetric sparsity patterns is <tt>O(sqrt(N)*m*log(m))</tt>, while it would
+ * be <tt>O(N*sqrt(N)*log(m))</tt> for the general case; the latter is too
+ * expensive to be performed.
+ *
+ * It seems as if we had to make clear not to overwrite the lines of other
+ * boundary nodes when doing the Gauss elimination step. However, since we
+ * reset the right hand side when passing such a node, it is not a problem to
+ * change the right hand side values of other boundary nodes not yet
+ * processed. It would be a problem to change those entries of nodes already
+ * processed, but since the matrix entry of the present column on the row of
+ * an already processed node is zero, the Gauss step does not change the right
+ * hand side. We need therefore not take special care of other boundary nodes.
  *
  * To make solving faster, we preset the solution vector with the right
  * boundary values (as to why this is necessary, see the discussion below in
@@ -700,58 +683,52 @@ namespace MatrixCreator
  * bit more stable. A refined algorithm would set the entry to the mean of the
  * other diagonal entries, but this seems to be too expensive.
  *
- * In some cases, it might be interesting to solve several times with
- * the same matrix, but for different right hand sides or boundary
- * values. However, since the modification for boundary values of the
- * right hand side vector depends on the original matrix, this is not
- * possible without storing the original matrix somewhere and applying
- * the @p apply_boundary_conditions function to a copy of it each
- * time we want to solve. In that case, you can use the
- * FilteredMatrix class in the @p LAC sublibrary. There you can
- * also find a formal (mathematical) description of the process of
- * modifying the matrix and right hand side vectors for boundary
- * values.
+ * In some cases, it might be interesting to solve several times with the same
+ * matrix, but for different right hand sides or boundary values. However,
+ * since the modification for boundary values of the right hand side vector
+ * depends on the original matrix, this is not possible without storing the
+ * original matrix somewhere and applying the @p apply_boundary_conditions
+ * function to a copy of it each time we want to solve. In that case, you can
+ * use the FilteredMatrix class in the @p LAC sublibrary. There you can also
+ * find a formal (mathematical) description of the process of modifying the
+ * matrix and right hand side vectors for boundary values.
  *
  *
  * <h3>Local elimination</h3>
  *
- * The second way of handling boundary values is to modify the local
- * matrix and vector contributions appropriately before transferring
- * them into the global sparse matrix and vector. This is what
- * local_apply_boundary_values() does. The advantage is that we save
- * the call to the apply_boundary_values function (which is expensive
- * because it has to work on sparse data structures). On the other
- * hand, the local_apply_boundary_values() function is called many
- * times, even if we only have a very small number of fixed boundary
- * nodes, and the main drawback is that this function doesn't work as
- * expected if there are hanging nodes that also need to be
- * treated. The reason that this function doesn't work is that it is
- * meant to be run before distribution into the global matrix,
- * i.e. before hanging nodes are distributed; since hanging nodes can
- * be constrained to a boundary node, the treatment of hanging nodes
- * can add entries again to rows and columns corresponding to boundary
- * values and that we have already vacated in the local elimination
- * step. To make things worse, in 3d constrained nodes can even lie on
- * the boundary. Thus, it is imperative that boundary node elimination
- * happens @em after hanging node elimination, but this can't be
- * achieved with local elimination of boundary nodes unless there are
- * no hanging node constraints at all.
- *
- * Local elimination has one additional drawback: we don't have access
- * to the solution vector, only to the local contributions to the
- * matrix and right hand side. The problem with this is subtle, but
- * can lead to very hard to find difficulties: when we eliminate a
- * degree of freedom, we delete the row and column of this unknown,
- * and set the diagonal entry to some positive value. To make the
- * problem more or less well-conditioned, we set this diagonal entry
- * to the absolute value of its prior value if that was non-zero, or
- * to the average magnitude of all other nonzero diagonal
- * elements. Then we set the right hand side value such that the
- * resulting solution entry has the right value as given by the
- * boundary values. Since we add these contributions up over all local
- * contributions, the diagonal entry and the respective value in the
- * right hand side are added up correspondingly, so that the entry in
- * the solution of the linear system is still valid.
+ * The second way of handling boundary values is to modify the local matrix
+ * and vector contributions appropriately before transferring them into the
+ * global sparse matrix and vector. This is what local_apply_boundary_values()
+ * does. The advantage is that we save the call to the apply_boundary_values
+ * function (which is expensive because it has to work on sparse data
+ * structures). On the other hand, the local_apply_boundary_values() function
+ * is called many times, even if we only have a very small number of fixed
+ * boundary nodes, and the main drawback is that this function doesn't work as
+ * expected if there are hanging nodes that also need to be treated. The
+ * reason that this function doesn't work is that it is meant to be run before
+ * distribution into the global matrix, i.e. before hanging nodes are
+ * distributed; since hanging nodes can be constrained to a boundary node, the
+ * treatment of hanging nodes can add entries again to rows and columns
+ * corresponding to boundary values and that we have already vacated in the
+ * local elimination step. To make things worse, in 3d constrained nodes can
+ * even lie on the boundary. Thus, it is imperative that boundary node
+ * elimination happens @em after hanging node elimination, but this can't be
+ * achieved with local elimination of boundary nodes unless there are no
+ * hanging node constraints at all.
+ *
+ * Local elimination has one additional drawback: we don't have access to the
+ * solution vector, only to the local contributions to the matrix and right
+ * hand side. The problem with this is subtle, but can lead to very hard to
+ * find difficulties: when we eliminate a degree of freedom, we delete the row
+ * and column of this unknown, and set the diagonal entry to some positive
+ * value. To make the problem more or less well-conditioned, we set this
+ * diagonal entry to the absolute value of its prior value if that was non-
+ * zero, or to the average magnitude of all other nonzero diagonal elements.
+ * Then we set the right hand side value such that the resulting solution
+ * entry has the right value as given by the boundary values. Since we add
+ * these contributions up over all local contributions, the diagonal entry and
+ * the respective value in the right hand side are added up correspondingly,
+ * so that the entry in the solution of the linear system is still valid.
  *
  * A problem arises, however, if the diagonal entries so chosen are not
  * appropriate for the linear system. Consider, for example, a mixed Laplace
@@ -762,36 +739,35 @@ namespace MatrixCreator
  * if we eliminate boundary values, we delete some rows and columns, but we
  * also introduce a few entries on the diagonal of the lower right block, so
  * that we get the system <tt>[[A' B'][C'^T X]]</tt>. The diagonal entries in
- * the matrix @p X will be of the same order of magnitude as those in @p
- * A. Now, if we solve this system in the Schur complement formulation, we
- * have to invert the matrix <tt>X-C'^TA'^{-1}B'</tt>. Deleting rows and
- * columns above makes sure that boundary nodes indeed have empty rows and
- * columns in the Schur complement as well, except for the entries in @p
- * X. However, the entries in @p X may be of significantly different orders of
- * magnitude than those in <tt>C'^TA'^{-1}B'</tt>! If this is the case, we may
- * run into trouble with iterative solvers. For example, assume that we start
- * with zero entries in the solution vector and that the entries in @p X are
- * several orders of magnitude too small; in this case, iterative solvers will
- * compute the residual vector in each step and form correction vectors, but
- * since the entries in @p X are so small, the residual contributions for
- * boundary nodes are really small, despite the fact that the boundary nodes
- * are still at values close to zero and not in accordance with the prescribed
- * boundary values. Since the residual is so small, the corrections the
- * iterative solver computes are very small, and in the end the solver will
- * indicate convergence to a small total residual with the boundary values
- * still being significantly wrong.
+ * the matrix @p X will be of the same order of magnitude as those in @p A.
+ * Now, if we solve this system in the Schur complement formulation, we have
+ * to invert the matrix <tt>X-C'^TA'^{-1}B'</tt>. Deleting rows and columns
+ * above makes sure that boundary nodes indeed have empty rows and columns in
+ * the Schur complement as well, except for the entries in @p X. However, the
+ * entries in @p X may be of significantly different orders of magnitude than
+ * those in <tt>C'^TA'^{-1}B'</tt>! If this is the case, we may run into
+ * trouble with iterative solvers. For example, assume that we start with zero
+ * entries in the solution vector and that the entries in @p X are several
+ * orders of magnitude too small; in this case, iterative solvers will compute
+ * the residual vector in each step and form correction vectors, but since the
+ * entries in @p X are so small, the residual contributions for boundary nodes
+ * are really small, despite the fact that the boundary nodes are still at
+ * values close to zero and not in accordance with the prescribed boundary
+ * values. Since the residual is so small, the corrections the iterative
+ * solver computes are very small, and in the end the solver will indicate
+ * convergence to a small total residual with the boundary values still being
+ * significantly wrong.
  *
  * We avoid this problem in the global elimination process described above by
- * 'priming' the solution vector with the correct values for boundary
- * nodes. However, we can't do this for the local elimination
- * process. Therefore, if you experience a problem like the one above, you
- * need to either increase the diagonal entries in @p X to a size that matches
- * those in the other part of the Schur complement, or, simpler, prime the
- * solution vector before you start the solver.
+ * 'priming' the solution vector with the correct values for boundary nodes.
+ * However, we can't do this for the local elimination process. Therefore, if
+ * you experience a problem like the one above, you need to either increase
+ * the diagonal entries in @p X to a size that matches those in the other part
+ * of the Schur complement, or, simpler, prime the solution vector before you
+ * start the solver.
  *
- * In conclusion, local elimination of boundary nodes only works if
- * there are no hanging nodes and even then doesn't always work fully
- * satisfactorily.
+ * In conclusion, local elimination of boundary nodes only works if there are
+ * no hanging nodes and even then doesn't always work fully satisfactorily.
  *
  * @ingroup numerics
  * @author Wolfgang Bangerth, 1998, 2000, 2004, 2005
@@ -799,20 +775,15 @@ namespace MatrixCreator
 namespace MatrixTools
 {
   /**
-   * Import namespace MatrixCreator for
-   * backward compatibility with older
-   * versions of deal.II in which these
-   * namespaces were classes and class
-   * MatrixTools was publicly derived from
-   * class MatrixCreator.
+   * Import namespace MatrixCreator for backward compatibility with older
+   * versions of deal.II in which these namespaces were classes and class
+   * MatrixTools was publicly derived from class MatrixCreator.
    */
   using namespace MatrixCreator;
 
   /**
-   * Apply Dirichlet boundary conditions
-   * to the system matrix and vectors
-   * as described in the general
-   * documentation.
+   * Apply Dirichlet boundary conditions to the system matrix and vectors as
+   * described in the general documentation.
    */
   template <typename number>
   void
@@ -823,13 +794,9 @@ namespace MatrixTools
                          const bool             eliminate_columns = true);
 
   /**
-   * Apply Dirichlet boundary
-   * conditions to the system
-   * matrix and vectors as
-   * described in the general
-   * documentation. This function
-   * works for block sparse
-   * matrices and block vectors
+   * Apply Dirichlet boundary conditions to the system matrix and vectors as
+   * described in the general documentation. This function works for block
+   * sparse matrices and block vectors
    */
   template <typename number>
   void
@@ -841,41 +808,24 @@ namespace MatrixTools
 
 #ifdef DEAL_II_WITH_PETSC
   /**
-   * Apply Dirichlet boundary conditions to
-   * the system matrix and vectors as
-   * described in the general
-   * documentation. This function works on
-   * the classes that are used to wrap
-   * PETSc objects.
+   * Apply Dirichlet boundary conditions to the system matrix and vectors as
+   * described in the general documentation. This function works on the
+   * classes that are used to wrap PETSc objects.
    *
-   * Note that this function is not very
-   * efficient: it needs to alternatingly
-   * read and write into the matrix, a
-   * situation that PETSc does not handle
-   * too well. In addition, we only get rid
-   * of rows corresponding to boundary
-   * nodes, but the corresponding case of
-   * deleting the respective columns
-   * (i.e. if @p eliminate_columns is @p
-   * true) is not presently implemented,
-   * and probably will never because it is
-   * too expensive without direct access to
-   * the PETSc data structures. (This leads
-   * to the situation where the action
-   * indicated by the default value of the
-   * last argument is actually not
-   * implemented; that argument has
-   * <code>true</code> as its default value
-   * to stay consistent with the other
-   * functions of same name in this class.)
-   * A third reason against this function
-   * is that it doesn't handle the case
-   * where the matrix is distributed across
-   * an MPI system.
+   * Note that this function is not very efficient: it needs to alternatingly
+   * read and write into the matrix, a situation that PETSc does not handle
+   * too well. In addition, we only get rid of rows corresponding to boundary
+   * nodes, but the corresponding case of deleting the respective columns
+   * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+   * and probably will never because it is too expensive without direct access
+   * to the PETSc data structures. (This leads to the situation where the
+   * action indicated by the default value of the last argument is actually
+   * not implemented; that argument has <code>true</code> as its default value
+   * to stay consistent with the other functions of same name in this class.)
+   * A third reason against this function is that it doesn't handle the case
+   * where the matrix is distributed across an MPI system.
    *
-   * This function is used in
-   * step-17 and
-   * step-18.
+   * This function is used in step-17 and step-18.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -885,8 +835,7 @@ namespace MatrixTools
                          const bool             eliminate_columns = true);
 
   /**
-   * Same function, but for parallel PETSc
-   * matrices.
+   * Same function, but for parallel PETSc matrices.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -896,29 +845,15 @@ namespace MatrixTools
                          const bool             eliminate_columns = true);
 
   /**
-   * Same function, but for
-   * parallel PETSc matrices. Note
-   * that this function only
-   * operates on the local range of
-   * the parallel matrix, i.e. it
-   * only eliminates rows
-   * corresponding to degrees of
-   * freedom for which the row is
-   * stored on the present
-   * processor. All other boundary
-   * nodes are ignored, and it
-   * doesn't matter whether they
-   * are present in the first
-   * argument to this function or
-   * not. A consequence of this,
-   * however, is that this function
-   * has to be called from all
-   * processors that participate in
-   * sharing the contents of the
-   * given matrices and vectors. It
-   * is also implied that the local
-   * range for all objects passed
-   * to this function is the same.
+   * Same function, but for parallel PETSc matrices. Note that this function
+   * only operates on the local range of the parallel matrix, i.e. it only
+   * eliminates rows corresponding to degrees of freedom for which the row is
+   * stored on the present processor. All other boundary nodes are ignored,
+   * and it doesn't matter whether they are present in the first argument to
+   * this function or not. A consequence of this, however, is that this
+   * function has to be called from all processors that participate in sharing
+   * the contents of the given matrices and vectors. It is also implied that
+   * the local range for all objects passed to this function is the same.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -941,42 +876,22 @@ namespace MatrixTools
 
 #ifdef DEAL_II_WITH_TRILINOS
   /**
-   * Apply Dirichlet boundary
-   * conditions to the system matrix
-   * and vectors as described in the
-   * general documentation. This
-   * function works on the classes
-   * that are used to wrap Trilinos
-   * objects.
+   * Apply Dirichlet boundary conditions to the system matrix and vectors as
+   * described in the general documentation. This function works on the
+   * classes that are used to wrap Trilinos objects.
    *
-   * Note that this function is not
-   * very efficient: it needs to
-   * alternatingly read and write
-   * into the matrix, a situation
-   * that Trilinos does not handle
-   * too well. In addition, we only
-   * get rid of rows corresponding to
-   * boundary nodes, but the
-   * corresponding case of deleting
-   * the respective columns (i.e. if
-   * @p eliminate_columns is @p true)
-   * is not presently implemented,
-   * and probably will never because
-   * it is too expensive without
-   * direct access to the Trilinos
-   * data structures. (This leads to
-   * the situation where the action
-   * indicated by the default value
-   * of the last argument is actually
-   * not implemented; that argument
-   * has <code>true</code> as its
-   * default value to stay consistent
-   * with the other functions of same
-   * name in this class.)  A third
-   * reason against this function is
-   * that it doesn't handle the case
-   * where the matrix is distributed
-   * across an MPI system.
+   * Note that this function is not very efficient: it needs to alternatingly
+   * read and write into the matrix, a situation that Trilinos does not handle
+   * too well. In addition, we only get rid of rows corresponding to boundary
+   * nodes, but the corresponding case of deleting the respective columns
+   * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+   * and probably will never because it is too expensive without direct access
+   * to the Trilinos data structures. (This leads to the situation where the
+   * action indicated by the default value of the last argument is actually
+   * not implemented; that argument has <code>true</code> as its default value
+   * to stay consistent with the other functions of same name in this class.)
+   * A third reason against this function is that it doesn't handle the case
+   * where the matrix is distributed across an MPI system.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -986,9 +901,8 @@ namespace MatrixTools
                          const bool             eliminate_columns = true);
 
   /**
-   * This function does the same as
-   * the one above, except now
-   * working on block structures.
+   * This function does the same as the one above, except now working on block
+   * structures.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -998,40 +912,21 @@ namespace MatrixTools
                          const bool                eliminate_columns = true);
 
   /**
-   * Apply Dirichlet boundary
-   * conditions to the system matrix
-   * and vectors as described in the
-   * general documentation. This
-   * function works on the classes
-   * that are used to wrap Trilinos
-   * objects.
+   * Apply Dirichlet boundary conditions to the system matrix and vectors as
+   * described in the general documentation. This function works on the
+   * classes that are used to wrap Trilinos objects.
    *
-   * Note that this function is not
-   * very efficient: it needs to
-   * alternatingly read and write
-   * into the matrix, a situation
-   * that Trilinos does not handle
-   * too well. In addition, we only
-   * get rid of rows corresponding to
-   * boundary nodes, but the
-   * corresponding case of deleting
-   * the respective columns (i.e. if
-   * @p eliminate_columns is @p true)
-   * is not presently implemented,
-   * and probably will never because
-   * it is too expensive without
-   * direct access to the Trilinos
-   * data structures. (This leads to
-   * the situation where the action
-   * indicated by the default value
-   * of the last argument is actually
-   * not implemented; that argument
-   * has <code>true</code> as its
-   * default value to stay consistent
-   * with the other functions of same
-   * name in this class.) This
-   * function does work on MPI vector
-   * types.
+   * Note that this function is not very efficient: it needs to alternatingly
+   * read and write into the matrix, a situation that Trilinos does not handle
+   * too well. In addition, we only get rid of rows corresponding to boundary
+   * nodes, but the corresponding case of deleting the respective columns
+   * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+   * and probably will never because it is too expensive without direct access
+   * to the Trilinos data structures. (This leads to the situation where the
+   * action indicated by the default value of the last argument is actually
+   * not implemented; that argument has <code>true</code> as its default value
+   * to stay consistent with the other functions of same name in this class.)
+   * This function does work on MPI vector types.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -1041,9 +936,8 @@ namespace MatrixTools
                          const bool             eliminate_columns = true);
 
   /**
-   * This function does the same as
-   * the one above, except now working
-   * on block structures.
+   * This function does the same as the one above, except now working on block
+   * structures.
    */
   void
   apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
@@ -1054,40 +948,20 @@ namespace MatrixTools
 #endif
 
   /**
-   * Rather than applying boundary
-   * values to the global matrix
-   * and vector after creating the
-   * global matrix, this function
-   * does so during assembly, by
-   * modifying the local matrix and
-   * vector contributions. If you
-   * call this function on all
-   * local contributions, the
-   * resulting matrix will have the
-   * same entries, and the final
-   * call to
-   * apply_boundary_values() on the
-   * global system will not be
-   * necessary.
+   * Rather than applying boundary values to the global matrix and vector
+   * after creating the global matrix, this function does so during assembly,
+   * by modifying the local matrix and vector contributions. If you call this
+   * function on all local contributions, the resulting matrix will have the
+   * same entries, and the final call to apply_boundary_values() on the global
+   * system will not be necessary.
    *
-   * Since this function does not
-   * have to work on the
-   * complicated data structures of
-   * sparse matrices, it is
-   * relatively cheap. It may
-   * therefore be a win if you have
-   * many fixed degrees of freedom
-   * (e.g. boundary nodes), or if
-   * access to the sparse matrix is
-   * expensive (e.g. for block
-   * sparse matrices, or for PETSc
-   * or trilinos
-   * matrices). However, it doesn't
-   * work as expected if there are
-   * also hanging nodes to be
-   * considered. More caveats are
-   * listed in the general
-   * documentation of this class.
+   * Since this function does not have to work on the complicated data
+   * structures of sparse matrices, it is relatively cheap. It may therefore
+   * be a win if you have many fixed degrees of freedom (e.g. boundary nodes),
+   * or if access to the sparse matrix is expensive (e.g. for block sparse
+   * matrices, or for PETSc or trilinos matrices). However, it doesn't work as
+   * expected if there are also hanging nodes to be considered. More caveats
+   * are listed in the general documentation of this class.
    */
   void
   local_apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
index 6dbfc0114714101e80172364b29d6a7cae072246..0f855a070b599a808231ff50338ed3e52332dd88 100644 (file)
@@ -57,9 +57,8 @@ namespace internal
   namespace PointValueHistory
   {
     /**
-     *  A class that stores the data needed
-     *  to reference the support points
-     *  closest to one requested point.
+     * A class that stores the data needed to reference the support points
+     * closest to one requested point.
      */
     template <int dim>
     class PointGeometryData
@@ -83,87 +82,90 @@ namespace internal
  * at ahead of time, as well as giving each solution vector that they want to
  * record a mnemonic name. Then, for each step the user calls one of the three
  * available "evaluate field" methods to store the data from each time step,
- * and the class extracts data for the requested
- * points to store it. Finally, once the computation is finished, the user can
- * request output files to be generated; these files are in Gnuplot format but
- * are basically just regular text and can easily be imported into other
- * programs well, for example into spreadsheets.
+ * and the class extracts data for the requested points to store it. Finally,
+ * once the computation is finished, the user can request output files to be
+ * generated; these files are in Gnuplot format but are basically just regular
+ * text and can easily be imported into other programs well, for example into
+ * spreadsheets.
  *
  * The user can store extra variables which do not relate to mesh location
- * specifying n_independent_variables. The class then expects
- * a std::vector of size n_independent_variables to be added during each step
- * using the method @p push_back_independent. This may be used for example for
- * recording external input, logging solver performance data such as time
- * taken to solve the step and solver steps before convergence, saving
- * norms calculated, or simply saving the time, number of time step, or number
- * of nonlinear iteration along with the data evaluated from the mesh.
+ * specifying n_independent_variables. The class then expects a std::vector of
+ * size n_independent_variables to be added during each step using the method
+ * @p push_back_independent. This may be used for example for recording
+ * external input, logging solver performance data such as time taken to solve
+ * the step and solver steps before convergence, saving norms calculated, or
+ * simply saving the time, number of time step, or number of nonlinear
+ * iteration along with the data evaluated from the mesh.
  *
  * The three "evaluate field" methods each have different strengths and
  * weaknesses making each suitable for different contexts:
  * <ol>
- * <li>Firstly, the @p evaluate_field version that does not take a @p DataPostprocessor object
- * selects the nearest support point (see @ref GlossSupport "this entry in the glossary")
- * to a given point to
- * extract data from. This makes the code that needs to be run at each time step very short,
- * since looping over the mesh to extract the needed dof_index can be done
- * just once at the start. However, this method is not suitable for
+ * <li>Firstly, the @p evaluate_field version that does not take a @p
+ * DataPostprocessor object selects the nearest support point (see @ref
+ * GlossSupport "this entry in the glossary") to a given point to extract data
+ * from. This makes the code that needs to be run at each time step very
+ * short, since looping over the mesh to extract the needed dof_index can be
+ * done just once at the start. However, this method is not suitable for
  * FiniteElement objects that do not assign dofs to actual mesh locations
- * (i.e. FEs without @ref GlossSupport "support points") or if adaptive mesh refinement is used.
- * The reason for the latter restriction is that the location of the closest
- * support point to a given point may change upon mesh refinement.
- * The class will throw an exception if any change to the triangulation is made
- * (Although the nearest support point could be re-computed upon mesh refinement,
- * the location of the support point will most likely change slightly, making the interpretation
- * of the data difficult, hence this is not implemented currently.)
+ * (i.e. FEs without @ref GlossSupport "support points") or if adaptive mesh
+ * refinement is used. The reason for the latter restriction is that the
+ * location of the closest support point to a given point may change upon mesh
+ * refinement. The class will throw an exception if any change to the
+ * triangulation is made (Although the nearest support point could be re-
+ * computed upon mesh refinement, the location of the support point will most
+ * likely change slightly, making the interpretation of the data difficult,
+ * hence this is not implemented currently.)
  *
  * <li> Secondly, @p evaluate_field_at_requested_location calls @p
  * VectorTools::point_value to compute values at the specific point requested.
- * This method is valid for any FE that is supported by @p VectorTools::point_value.
- * Specifically, this method can be called by codes using adaptive mesh refinement.
+ * This method is valid for any FE that is supported by @p
+ * VectorTools::point_value. Specifically, this method can be called by codes
+ * using adaptive mesh refinement.
  *
- * <li>Finally, the class offers a function @p evaluate_field that takes a
- * @p DataPostprocessor object. This method allows the deal.II
- * data postprocessor to be used to compute new quantities from the
- * solution on the fly. The values are located at the nearest quadrature
- * point to the requested point. If the mesh is refined between calls, this
- * point will change, so care must be taken when using this method in
- * code using adaptive refinement, but as the output will be meaningful (in
- * the sense that the quadrature point selected is guaranteed to remain in the
- * same vicinity, the class does not prevent the use of this method in adaptive
- * codes. The class provides warnings in the output files if the mesh has changed.
- * Note that one can reduce the error this procedure introduces by providing
- * a quadrature formula that has more points, at the expense of performing more
- * work since then the closest quadrature points is nearer to the point at which
- * the evaluation is really supposed to happen. (As a sidenote: Why not do the
- * evaluation at the requested point right away? The reason for this is that it
- * would require setting up a new quadrature point object on each cell that has
- * only a single point corresponding to the reference coordinates of the point you
- * really want; then initializing a FEValues object with it; then evaluating the
- * solution at this point; then handing the result to the DataPostprocessor object.
- * This sequence of things is expensive -- which is the reason why
- * VectorTools::point_value() is expensive. Using the same quadrature formula
- * on each cell on which we want to evaluate the solution and only having to
- * initialize a FEValue object once is a much cheaper alternative, albeit of
- * course at the expense of getting only an approximate result.)
+ * <li>Finally, the class offers a function @p evaluate_field that takes a @p
+ * DataPostprocessor object. This method allows the deal.II data postprocessor
+ * to be used to compute new quantities from the solution on the fly. The
+ * values are located at the nearest quadrature point to the requested point.
+ * If the mesh is refined between calls, this point will change, so care must
+ * be taken when using this method in code using adaptive refinement, but as
+ * the output will be meaningful (in the sense that the quadrature point
+ * selected is guaranteed to remain in the same vicinity, the class does not
+ * prevent the use of this method in adaptive codes. The class provides
+ * warnings in the output files if the mesh has changed. Note that one can
+ * reduce the error this procedure introduces by providing a quadrature
+ * formula that has more points, at the expense of performing more work since
+ * then the closest quadrature points is nearer to the point at which the
+ * evaluation is really supposed to happen. (As a sidenote: Why not do the
+ * evaluation at the requested point right away? The reason for this is that
+ * it would require setting up a new quadrature point object on each cell that
+ * has only a single point corresponding to the reference coordinates of the
+ * point you really want; then initializing a FEValues object with it; then
+ * evaluating the solution at this point; then handing the result to the
+ * DataPostprocessor object. This sequence of things is expensive -- which is
+ * the reason why VectorTools::point_value() is expensive. Using the same
+ * quadrature formula on each cell on which we want to evaluate the solution
+ * and only having to initialize a FEValue object once is a much cheaper
+ * alternative, albeit of course at the expense of getting only an approximate
+ * result.)
  * </ol>
  *
- * When recording a new mnemonic name, the user must supply a
- * component_mask (see @ref GlossComponentMask "this glossary entry")
- * to indicate the @ref GlossComponent "(vector) components"
- * to be extracted from the given input. If the user simply wants to extract
- * all the components, the mask need not be explicitly supplied to the @p
- * add_field_name method and the default value of the parameter is sufficient.
- * If the @p evaluate_field with a @p DataPostprocessor object is used, the
- * component_mask is interpreted as the mask of the @p DataPostprocessor
- * return vector. The size of this mask can be different to that of the FE
- * space, but must be provided when the @p add_field_name method is
- * called. One variant of the @p add_field_name method allows an unsigned int
- * input to construct a suitable mask, if all values from the @p
- * DataPostprocessor are desired.
+ * When recording a new mnemonic name, the user must supply a component_mask
+ * (see @ref GlossComponentMask "this glossary entry") to indicate the @ref
+ * GlossComponent "(vector) components" to be extracted from the given input.
+ * If the user simply wants to extract all the components, the mask need not
+ * be explicitly supplied to the @p add_field_name method and the default
+ * value of the parameter is sufficient. If the @p evaluate_field with a @p
+ * DataPostprocessor object is used, the component_mask is interpreted as the
+ * mask of the @p DataPostprocessor return vector. The size of this mask can
+ * be different to that of the FE space, but must be provided when the @p
+ * add_field_name method is called. One variant of the @p add_field_name
+ * method allows an unsigned int input to construct a suitable mask, if all
+ * values from the @p DataPostprocessor are desired.
  *
- * The class automatically generates names for the data stored based on the mnemonics
- * supplied. The methods @p add_component_names and @p add_independent_names allow
- * the user to provide lists of names to use instead if desired.
+ * The class automatically generates names for the data stored based on the
+ * mnemonics supplied. The methods @p add_component_names and @p
+ * add_independent_names allow the user to provide lists of names to use
+ * instead if desired.
  *
  * Following is a little code snippet that shows a common usage of this class:
  *
@@ -208,170 +210,116 @@ class PointValueHistory
 {
 public:
   /**
-   * Provide a stripped down instance of
-   * the class which does not support
-   * adding points or mesh data.  This may
-   * be used for example for recording
-   * external input or logging solver
-   * performance data.
+   * Provide a stripped down instance of the class which does not support
+   * adding points or mesh data.  This may be used for example for recording
+   * external input or logging solver performance data.
    */
   PointValueHistory (const unsigned int n_independent_variables = 0);
 
   /**
-   * Constructor linking the class to a
-   * specific @p DoFHandler. This
-   * class reads specific data from the @p
-   * DoFHandler and stores it internally
-   * for quick access (in particular dof
-   * indices of closest neighbors to
-   * requested points) the class is fairly
-   * intolerant to changes to the @p
-   * DoFHandler if data at support points
-   * is required. Mesh refinement and @p
-   * DoFRenumbering methods should be
-   * performed before the @p add_points
-   * method is called and adaptive grid
-   * refinement is only supported by some
-   * methods.
+   * Constructor linking the class to a specific @p DoFHandler. This class
+   * reads specific data from the @p DoFHandler and stores it internally for
+   * quick access (in particular dof indices of closest neighbors to requested
+   * points) the class is fairly intolerant to changes to the @p DoFHandler if
+   * data at support points is required. Mesh refinement and @p DoFRenumbering
+   * methods should be performed before the @p add_points method is called and
+   * adaptive grid refinement is only supported by some methods.
    *
-   * The user can store extra variables
-   * which do not relate to mesh location
-   * by specifying the number required
-   * using n_independent_variables and
-   * making calls to @p
-   * push_back_independent as needed.  This
-   * may be used for example for recording
-   * external input or logging solver
-   * performance data.
+   * The user can store extra variables which do not relate to mesh location
+   * by specifying the number required using n_independent_variables and
+   * making calls to @p push_back_independent as needed.  This may be used for
+   * example for recording external input or logging solver performance data.
    */
   PointValueHistory (const DoFHandler<dim> &dof_handler,
                      const unsigned int n_independent_variables = 0);
 
   /**
-   * Copy constructor. This constructor can
-   * be safely called with a @p
-   * PointValueHistory object that contains
-   * data, but this could be expensive and
-   * should be avoided.
+   * Copy constructor. This constructor can be safely called with a @p
+   * PointValueHistory object that contains data, but this could be expensive
+   * and should be avoided.
    */
   PointValueHistory (const PointValueHistory &point_value_history);
 
   /**
-   * Assignment operator. This
-   * assignment operator can be safely
-   * called once the class is closed and
-   * data added, but this is provided
-   * primarily to allow a @p
-   * PointValueHistory object declared in a
-   * class to be reinitialized later in the
-   * class. Using the assignment operator
-   * when the object contains data could be
-   * expensive.
+   * Assignment operator. This assignment operator can be safely called once
+   * the class is closed and data added, but this is provided primarily to
+   * allow a @p PointValueHistory object declared in a class to be
+   * reinitialized later in the class. Using the assignment operator when the
+   * object contains data could be expensive.
    */
   PointValueHistory &operator=(const PointValueHistory &point_value_history);
 
   /**
-     Deconstructor.
-  */
+   * Deconstructor.
+   */
   ~PointValueHistory ();
 
   /**
-   * Add a single point to the class. The
-   * support points (one per component) in
-   * the mesh that are closest to that
-   * point are found and their details stored
-   * for use when @p evaluate_field is
-   * called. If more than one point is
-   * required rather use the @p add_points
-   * method since this minimizes iterations
-   * over the mesh.
+   * Add a single point to the class. The support points (one per component)
+   * in the mesh that are closest to that point are found and their details
+   * stored for use when @p evaluate_field is called. If more than one point
+   * is required rather use the @p add_points method since this minimizes
+   * iterations over the mesh.
    */
   void add_point(const Point <dim> &location);
 
   /**
-   * Add multiple points to the class. The
-   * support points (one per component) in
-   * the mesh that are closest to that
-   * point is found and their details stored
-   * for use when @p evaluate_field is
-   * called. If more than one point is
-   * required, rather call this method as it
-   * is more efficient than the add_point
-   * method since it minimizes iterations
-   * over the mesh. The points are added to
-   * the internal database in the order
-   * they appear in the list and there is
-   * always a one to one correspondence
-   * between the requested point and the
-   * added point, even if a point is
-   * requested multiple times.
+   * Add multiple points to the class. The support points (one per component)
+   * in the mesh that are closest to that point is found and their details
+   * stored for use when @p evaluate_field is called. If more than one point
+   * is required, rather call this method as it is more efficient than the
+   * add_point method since it minimizes iterations over the mesh. The points
+   * are added to the internal database in the order they appear in the list
+   * and there is always a one to one correspondence between the requested
+   * point and the added point, even if a point is requested multiple times.
    */
   void add_points (const std::vector <Point <dim> > &locations);
 
 
 
   /**
-   * Put another mnemonic string (and hence
-   * @p VECTOR) into the class. This method
-   * adds storage space for variables equal
-   * to the number of true values in
-   * component_mask.
-   * This also adds extra entries for points
-   * that are already in the class, so
-   * @p add_field_name and @p add_points can
-   * be called in any order.
+   * Put another mnemonic string (and hence @p VECTOR) into the class. This
+   * method adds storage space for variables equal to the number of true
+   * values in component_mask. This also adds extra entries for points that
+   * are already in the class, so @p add_field_name and @p add_points can be
+   * called in any order.
    */
   void add_field_name(const std::string &vector_name,
                       const ComponentMask &component_mask = ComponentMask());
 
   /**
-   * Put another mnemonic string (and hence
-   * @p VECTOR) into the class. This method
-   * adds storage space for n_components
-   * variables.
-   * This also adds extra entries for points
-   * that are already in the class, so
-   * @p add_field_name and @p add_points can
-   * be called in any order.
-   * This method generates a std::vector
-   * 0, ..., n_components-1 and calls the
-   * previous function.
+   * Put another mnemonic string (and hence @p VECTOR) into the class. This
+   * method adds storage space for n_components variables. This also adds
+   * extra entries for points that are already in the class, so @p
+   * add_field_name and @p add_points can be called in any order. This method
+   * generates a std::vector 0, ..., n_components-1 and calls the previous
+   * function.
    */
   void add_field_name(const std::string &vector_name,
                       const unsigned int n_components);
 
   /**
-   * Provide optional names for each component
-   * of a field. These names will be used
-   * instead of names generated from the
-   * field name, if supplied.
+   * Provide optional names for each component of a field. These names will be
+   * used instead of names generated from the field name, if supplied.
    */
   void add_component_names(const std::string &vector_name,
                            const std::vector <std::string> &component_names);
 
   /**
-   * Provide optional names for the
-   * independent values. These names will
-   * be used instead of "Indep_...", if
-   * supplied.
+   * Provide optional names for the independent values. These names will be
+   * used instead of "Indep_...", if supplied.
    */
   void add_independent_names(const std::vector <std::string> &independent_names);
 
 
 
   /**
-   * Extract values at the stored points
-   * from the VECTOR supplied and add them
-   * to the new dataset in vector_name.
-   * The component mask supplied when the
-   * field was added is used to select
-   * components to extract.
-   * If a @p DoFHandler is used, one (and only
-   * one) evaluate_field method
-   * must be called for each dataset (time
-   * step, iteration, etc) for each
-   * vector_name, otherwise a @p
-   * ExcDataLostSync error can occur.
+   * Extract values at the stored points from the VECTOR supplied and add them
+   * to the new dataset in vector_name. The component mask supplied when the
+   * field was added is used to select components to extract. If a @p
+   * DoFHandler is used, one (and only one) evaluate_field method must be
+   * called for each dataset (time step, iteration, etc) for each vector_name,
+   * otherwise a @p ExcDataLostSync error can occur.
    */
   template <class VECTOR>
   void evaluate_field(const std::string &name,
@@ -379,32 +327,21 @@ public:
 
 
   /**
-   * Compute values using a @p DataPostprocessor object
-   * with the @p VECTOR supplied and add them
-   * to the new dataset in vector_name.
-   * The component_mask supplied when the
-   * field was added is used to select
-   * components to extract from the @p DataPostprocessor
-   * return vector.
-   * This method takes a vector of field names to
-   * process and is preferred if many fields use the
-   * same @p DataPostprocessor object as each cell
-   * is only located once.
-   * The quadrature object supplied is used for all
-   * components of a vector field.
-   * Although this method will not throw an exception
-   * if the mesh has changed. (No internal data structures
-   * are invalidated as the quadrature points are repicked
-   * each time the function is called.) Nevertheless
-   * the user must be aware that if the mesh changes the
-   * point selected will also vary slightly, making
-   * interpretation of the data more difficult.
-   * If a @p DoFHandler is used, one (and only
-   * one) evaluate_field method
-   * must be called for each dataset (time
-   * step, iteration, etc) for each
-   * vector_name, otherwise a @p
-   * ExcDataLostSync error can occur.
+   * Compute values using a @p DataPostprocessor object with the @p VECTOR
+   * supplied and add them to the new dataset in vector_name. The
+   * component_mask supplied when the field was added is used to select
+   * components to extract from the @p DataPostprocessor return vector. This
+   * method takes a vector of field names to process and is preferred if many
+   * fields use the same @p DataPostprocessor object as each cell is only
+   * located once. The quadrature object supplied is used for all components
+   * of a vector field. Although this method will not throw an exception if
+   * the mesh has changed. (No internal data structures are invalidated as the
+   * quadrature points are repicked each time the function is called.)
+   * Nevertheless the user must be aware that if the mesh changes the point
+   * selected will also vary slightly, making interpretation of the data more
+   * difficult. If a @p DoFHandler is used, one (and only one) evaluate_field
+   * method must be called for each dataset (time step, iteration, etc) for
+   * each vector_name, otherwise a @p ExcDataLostSync error can occur.
    */
   template <class VECTOR>
   void evaluate_field(const std::vector <std::string> &names,
@@ -413,11 +350,9 @@ public:
                       const Quadrature<dim> &quadrature);
 
   /**
-   * Construct a std::vector <std::string>
-   * containing only vector_name and
-   * call the above function. The above function
-   * is more efficient if multiple fields
-   * use the same @p DataPostprocessor object.
+   * Construct a std::vector <std::string> containing only vector_name and
+   * call the above function. The above function is more efficient if multiple
+   * fields use the same @p DataPostprocessor object.
    */
   template <class VECTOR>
   void evaluate_field(const std::string &name,
@@ -427,25 +362,16 @@ public:
 
 
   /**
-   * Extract values at the points actually
-   * requested from the VECTOR supplied and
-   * add them to the new dataset in vector_name.
-   * Unlike the other evaluate_field methods
-   * this method does not care if the dof_handler
-   * has been modified because it uses calls to
-   * @p VectorTools::point_value to extract there
-   * data. Therefore, if only this method is used,
-   * the class is fully compatible with
-   * adaptive refinement.
-   * The component_mask supplied when the
-   * field was added is used to select
-   * components to extract. If
-   * a @p DoFHandler is used, one (and only
-   * one) evaluate_field method
-   * must be called for each dataset (time
-   * step, iteration, etc) for each
-   * vector_name, otherwise a @p
-   * ExcDataLostSync error can occur.
+   * Extract values at the points actually requested from the VECTOR supplied
+   * and add them to the new dataset in vector_name. Unlike the other
+   * evaluate_field methods this method does not care if the dof_handler has
+   * been modified because it uses calls to @p VectorTools::point_value to
+   * extract there data. Therefore, if only this method is used, the class is
+   * fully compatible with adaptive refinement. The component_mask supplied
+   * when the field was added is used to select components to extract. If a @p
+   * DoFHandler is used, one (and only one) evaluate_field method must be
+   * called for each dataset (time step, iteration, etc) for each vector_name,
+   * otherwise a @p ExcDataLostSync error can occur.
    */
   template <class VECTOR>
   void evaluate_field_at_requested_location(const std::string &name,
@@ -453,62 +379,39 @@ public:
 
 
   /**
-   * Add the key for the current dataset to
-   * the dataset. Although calling this
-   * method first is sensible, the order in
-   * which this method, @p evaluate_field
-   * and @p push_back_independent is not
-   * important. It is however important
-   * that all the data for a give dataset
-   * is added to each dataset and that it
-   * is added before a new data set is
-   * started. This prevents a @p
-   * ExcDataLostSync.
+   * Add the key for the current dataset to the dataset. Although calling this
+   * method first is sensible, the order in which this method, @p
+   * evaluate_field and @p push_back_independent is not important. It is
+   * however important that all the data for a give dataset is added to each
+   * dataset and that it is added before a new data set is started. This
+   * prevents a @p ExcDataLostSync.
    */
   void start_new_dataset (const double key);
 
   /**
-   * If independent values have been set
-   * up, this method stores these
-   * values. This should only be called
-   * once per dataset, and if independent
-   * values are used it must be called for
-   * every dataset. A @p ExcDataLostSync
-   * exception can be thrown if this method
-   * is not called.
+   * If independent values have been set up, this method stores these values.
+   * This should only be called once per dataset, and if independent values
+   * are used it must be called for every dataset. A @p ExcDataLostSync
+   * exception can be thrown if this method is not called.
    */
   void push_back_independent (const std::vector <double> &independent_values);
 
 
   /**
-   * Write out a series of .gpl files named
-   * base_name + "-00.gpl", base_name +
-   * "-01.gpl" etc. The data file gives
-   * info about where the support points
-   * selected and interpreting the data.
-   * If @p n_indep != 0 an additional file
-   * base_name + "_indep.gpl" containing
-   * key and independent data. The file
-   * name agrees with the order the points
-   * were added to the class.
-   * The names of the data columns can
-   * be supplied using the functions
-   * @p add_component_names and
-   * @p add_independent_names.
-   * The support point information is only
-   * meaningful if the dof_handler has not
-   * been changed. Therefore, if adaptive
-   * mesh refinement has been used the
-   * support point data should not be used.
-   * The optional parameter
-   * postprocessor_locations is used to
-   * add the postprocessor locations to the
-   * output files. If this is desired, the
-   * data should be obtained from a call to
-   * get_postprocessor_locations while the
-   * dof_handler is usable. The default
-   * parameter is an empty vector of strings,
-   * and will suppress postprocessor
+   * Write out a series of .gpl files named base_name + "-00.gpl", base_name +
+   * "-01.gpl" etc. The data file gives info about where the support points
+   * selected and interpreting the data. If @p n_indep != 0 an additional file
+   * base_name + "_indep.gpl" containing key and independent data. The file
+   * name agrees with the order the points were added to the class. The names
+   * of the data columns can be supplied using the functions @p
+   * add_component_names and @p add_independent_names. The support point
+   * information is only meaningful if the dof_handler has not been changed.
+   * Therefore, if adaptive mesh refinement has been used the support point
+   * data should not be used. The optional parameter postprocessor_locations
+   * is used to add the postprocessor locations to the output files. If this
+   * is desired, the data should be obtained from a call to
+   * get_postprocessor_locations while the dof_handler is usable. The default
+   * parameter is an empty vector of strings, and will suppress postprocessor
    * locations output.
    */
   void write_gnuplot (const std::string &base_name,
@@ -516,18 +419,13 @@ public:
 
 
   /**
-   * Return a @p Vector with the indices of
-   * selected points flagged with a 1. This
-   * method is mainly for testing and
-   * verifying that the class is working
-   * correctly. By passing this vector to a
-   * DataOut object, the user can verify
-   * that the positions returned by @p
-   * PointValueHistory< dim >::get_points
-   * agree with the positions that @p
-   * DataOut interprets from the @p Vector
-   * returned. The code snippet below
-   * demonstrates how this could be done:
+   * Return a @p Vector with the indices of selected points flagged with a 1.
+   * This method is mainly for testing and verifying that the class is working
+   * correctly. By passing this vector to a DataOut object, the user can
+   * verify that the positions returned by @p PointValueHistory< dim
+   * >::get_points agree with the positions that @p DataOut interprets from
+   * the @p Vector returned. The code snippet below demonstrates how this
+   * could be done:
    * @code
    * // Make a DataOut object and attach the dof_handler
    * DataOut<dim> data_out;
@@ -549,27 +447,21 @@ public:
   /**
    * Depreciated:
    *
-   * This function only exists for backward
-   * compatibility as this is the interface
-   * provided by previous versions of the library.
-   * The function mark_support_locations replaces
-   * it and reflects the fact that the locations
-   * marked are actually the support points.
-  *
-  * @deprecated
+   * This function only exists for backward compatibility as this is the
+   * interface provided by previous versions of the library. The function
+   * mark_support_locations replaces it and reflects the fact that the
+   * locations marked are actually the support points.
+   *
+   * @deprecated
    */
   Vector<double> mark_locations() DEAL_II_DEPRECATED;
 
 
   /**
-   * Stores the actual location of each
-   * support point selected by the @p
-   * add_point(s) method.  This can be used
-   * to compare with the point requested,
-   * for example by using the @p
-   * Point<dim>::distance function. For
-   * convenience, location is resized to
-   * the correct number of points by the
+   * Stores the actual location of each support point selected by the @p
+   * add_point(s) method.  This can be used to compare with the point
+   * requested, for example by using the @p Point<dim>::distance function. For
+   * convenience, location is resized to the correct number of points by the
    * method.
    */
   void get_support_locations (std::vector <std::vector<Point <dim> > > &locations);
@@ -577,231 +469,175 @@ public:
   /**
    * Depreciated:
    *
-   * This function only exists for backward
-   * compatibility as this is the interface
-   * provided by previous versions of the library.
-   * The function get_support_locations replaces
-   * it and reflects the fact that the points
+   * This function only exists for backward compatibility as this is the
+   * interface provided by previous versions of the library. The function
+   * get_support_locations replaces it and reflects the fact that the points
    * returned are actually the support points.
    */
   void get_points (std::vector <std::vector<Point <dim> > > &locations);
 
   /**
-   * Stores the actual location of the
-   * points used by the data_postprocessor.
-   * This can be used to compare with the
-   * points requested, for example by using
-   * the @p Point<dim>::distance function.
-   * Unlike the support_locations, these
-   * locations are computed every time the
-   * evaluate_field method is called with a
-   * postprocessor. This method uses the
-   * same algorithm so can will find the
-   * same points.
-   * For convenience, location is resized
-   * to the correct number of points by the
-   * method.
+   * Stores the actual location of the points used by the data_postprocessor.
+   * This can be used to compare with the points requested, for example by
+   * using the @p Point<dim>::distance function. Unlike the support_locations,
+   * these locations are computed every time the evaluate_field method is
+   * called with a postprocessor. This method uses the same algorithm so can
+   * will find the same points. For convenience, location is resized to the
+   * correct number of points by the method.
    */
   void get_postprocessor_locations (const Quadrature<dim> &quadrature,
                                     std::vector<Point <dim> > &locations);
 
   /**
-   * Once datasets have been added to the
-   * class, requests to add additional
-   * points will make the data
-   * interpretation unclear. The boolean @p
-   * closed defines a state of the class
-   * and ensures this does not
-   * happen. Additional points or vectors
-   * can only be added while the class is
-   * not closed, and the class must be
-   * closed before datasets can be added or
-   * written to file. @p
-   * PointValueHistory::get_points and @p
-   * PointValueHistory::status do not
-   * require the class to be closed. If a
-   * method that requires a class to be
-   * open or close is called while in the
-   * wrong state a @p ExcInvalidState
+   * Once datasets have been added to the class, requests to add additional
+   * points will make the data interpretation unclear. The boolean @p closed
+   * defines a state of the class and ensures this does not happen. Additional
+   * points or vectors can only be added while the class is not closed, and
+   * the class must be closed before datasets can be added or written to file.
+   * @p PointValueHistory::get_points and @p PointValueHistory::status do not
+   * require the class to be closed. If a method that requires a class to be
+   * open or close is called while in the wrong state a @p ExcInvalidState
    * exception is thrown.
    */
   void close();
 
 
   /**
-   * Delete the lock this object has to the
-   * @p DoFHandler used the last time the
-   * class was created.  This method should
-   * not normally need to be called, but
-   * can be useful to ensure that the @p
-   * DoFHandler is released before it goes
-   * out of scope if the @p
-   * PointValueHistory class might live
-   * longer than it. Once this method has
-   * been called, the majority of methods
-   * will throw a @p ExcInvalidState
-   * exception, so if used this method
-   * should be the last call to the class.
+   * Delete the lock this object has to the @p DoFHandler used the last time
+   * the class was created.  This method should not normally need to be
+   * called, but can be useful to ensure that the @p DoFHandler is released
+   * before it goes out of scope if the @p PointValueHistory class might live
+   * longer than it. Once this method has been called, the majority of methods
+   * will throw a @p ExcInvalidState exception, so if used this method should
+   * be the last call to the class.
    */
   void clear();
 
   /**
-   * Print useful debugging information
-   * about the class, include details about
-   * which support points were selected for
-   * each point and sizes of the data
+   * Print useful debugging information about the class, include details about
+   * which support points were selected for each point and sizes of the data
    * stored.
    */
   void status(std::ostream &out);
 
 
   /**
-   * Check the internal data sizes to test
-   * for a loss of data sync. This is often
-   * used in @p Assert statements with the
-   * @p ExcDataLostSync exception. If @p strict
-   * is @p false this method returns
-   * @p true if all sizes are within 1 of
-   * each other (needed to allow data to be
-   * added), with @p strict = @p true they
-   * must be exactly equal.
+   * Check the internal data sizes to test for a loss of data sync. This is
+   * often used in @p Assert statements with the @p ExcDataLostSync exception.
+   * If @p strict is @p false this method returns @p true if all sizes are
+   * within 1 of each other (needed to allow data to be added), with @p strict
+   * = @p true they must be exactly equal.
    */
 
   bool deep_check (const bool strict);
 
   /**
-   * A call has been made to @p
-   * push_back_independent when no
-   * independent values were requested.
+   * A call has been made to @p push_back_independent when no independent
+   * values were requested.
    */
   DeclException0(ExcNoIndependent);
 
   /**
-   * This error is thrown to indicate that
-   * the data sets appear to be out of
-   * sync.  The class requires that the
-   * number of dataset keys is the same as
-   * the number of independent values sets
-   * and mesh linked value sets. The number
-   * of each of these is allowed to differ
-   * by one to allow new values to be added
-   * with out restricting the order the
-   * user choses to do so.  Special cases
-   * of no @p DoFHandler and no independent
-   * values should not trigger this error.
+   * This error is thrown to indicate that the data sets appear to be out of
+   * sync.  The class requires that the number of dataset keys is the same as
+   * the number of independent values sets and mesh linked value sets. The
+   * number of each of these is allowed to differ by one to allow new values
+   * to be added with out restricting the order the user choses to do so.
+   * Special cases of no @p DoFHandler and no independent values should not
+   * trigger this error.
    */
   DeclException0(ExcDataLostSync);
 
 
   /**
-   * A method which requires access to a @p
-   * DoFHandler to be meaningful has been
-   * called when @p have_dof_handler is
-   * false (most likely due to default
-   * constructor being called). Only
-   * independent variables may be logged
-   * with no DoFHandler.
+   * A method which requires access to a @p DoFHandler to be meaningful has
+   * been called when @p have_dof_handler is false (most likely due to default
+   * constructor being called). Only independent variables may be logged with
+   * no DoFHandler.
    */
   DeclException0(ExcDoFHandlerRequired);
 
   /**
-   * The triangulation indicated that mesh
-   * has been refined in some way. This suggests
-   * that the internal dof indices stored
-   * are no longer meaningful.
+   * The triangulation indicated that mesh has been refined in some way. This
+   * suggests that the internal dof indices stored are no longer meaningful.
    */
   DeclException0(ExcDoFHandlerChanged);
 
 private:
   /**
-   * Stores keys, values on the abscissa.
-   * This will often be time, but possibly
-   * time step, iteration etc.
+   * Stores keys, values on the abscissa. This will often be time, but
+   * possibly time step, iteration etc.
    */
   std::vector <double> dataset_key;
 
   /**
-   * Values that do not depend on grid
-   * location.
+   * Values that do not depend on grid location.
    */
   std::vector <std::vector <double> > independent_values;
 
   /**
-   * Saves a vector listing component
-   * names associated with a independent_values.
-   * This will be an empty vector
-   * if the user does not supplies names.
+   * Saves a vector listing component names associated with a
+   * independent_values. This will be an empty vector if the user does not
+   * supplies names.
    */
   std::vector<std::string> indep_names;
 
   /**
-   * Saves data for each mnemonic entry.
-   * data_store: mnemonic ->
-   * [point_0_components point_1_components
-   * ... point_n-1_components][key]
-   * This format facilitates scalar mnemonics
-   * in a vector space, because scalar mnemonics
-   * will only have one component per point.
-   * Vector components are strictly
-   * FE.n_components () long.
+   * Saves data for each mnemonic entry. data_store: mnemonic ->
+   * [point_0_components point_1_components ... point_n-1_components][key]
+   * This format facilitates scalar mnemonics in a vector space, because
+   * scalar mnemonics will only have one component per point. Vector
+   * components are strictly FE.n_components () long.
    */
   std::map <std::string, std::vector <std::vector <double> > > data_store;
 
   /**
-   * Saves a component mask
-   * for each mnemonic.
+   * Saves a component mask for each mnemonic.
    */
   std::map <std::string, ComponentMask> component_mask;
 
 
   /**
-   * Saves a vector listing component
-   * names associated with a mnemonic.
-   * This will be an empty vector
-   * if the user does not supplies names.
+   * Saves a vector listing component names associated with a mnemonic. This
+   * will be an empty vector if the user does not supplies names.
    */
   std::map <std::string, std::vector<std::string> > component_names_map;
 
   /**
-   * Saves the location and other mesh info
-   * about support points.
+   * Saves the location and other mesh info about support points.
    */
   std::vector <internal::PointValueHistory::PointGeometryData <dim> >
   point_geometry_data;
 
 
   /**
-   * Used to enforce @p closed state for some
-   * methods.
+   * Used to enforce @p closed state for some methods.
    */
   bool closed;
 
   /**
-   * Used to enforce @p !cleared state for
-   * some methods.
+   * Used to enforce @p !cleared state for some methods.
    */
   bool cleared;
 
 
   /**
-   * A smart pointer to the dof_handler
-   * supplied to the constructor. This can be
-   * released by calling @p clear().
+   * A smart pointer to the dof_handler supplied to the constructor. This can
+   * be released by calling @p clear().
    */
   SmartPointer<const DoFHandler<dim>,PointValueHistory<dim> > dof_handler;
 
 
   /**
-   * Variable to check if the triangulation
-   * has changed. If it has changed, certain
-   * data is out of date (especially the
+   * Variable to check if the triangulation has changed. If it has changed,
+   * certain data is out of date (especially the
    * PointGeometryData::solution_indices.
    */
   bool triangulation_changed;
 
   /**
-   * A boolean to record whether the class was
-   * initialized with a DoFHandler or not.
+   * A boolean to record whether the class was initialized with a DoFHandler
+   * or not.
    */
   bool have_dof_handler;
 
@@ -811,20 +647,17 @@ private:
   boost::signals2::connection tria_listener;
 
   /**
-   * Stores the number of independent
-   * variables requested.
+   * Stores the number of independent variables requested.
    */
   unsigned int n_indep;
 
 
   /**
-   *  A function that will be triggered
-   *  through signals whenever the
-   *  triangulation is modified.
+   * A function that will be triggered through signals whenever the
+   * triangulation is modified.
    *
-   *  It is currently used to check
-   *  if the triangulation has changed,
-   *  invalidating precomputed values.
+   * It is currently used to check if the triangulation has changed,
+   * invalidating precomputed values.
    */
   void tria_change_listener ();
 };
index b320fef323db3d9862faf8d95f4a273a1f0c6a56..b2cb8946d597c9cecaa0872f78f6a1ba1229f45a 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class implements the transfer of a discrete FE function
- * (e.g. a solution vector) from one mesh to another that is obtained
- * from the first by a single refinement and/or coarsening step. During
- * interpolation the vector is reinitialized to the new size and
- * filled with the interpolated values. This class is used in the
- * step-15, step-31, and step-33 tutorial programs. A version of this
- * class that works on parallel triangulations is available as
- * parallel::distributed::SolutionTransfer.
+ * This class implements the transfer of a discrete FE function (e.g. a
+ * solution vector) from one mesh to another that is obtained from the first
+ * by a single refinement and/or coarsening step. During interpolation the
+ * vector is reinitialized to the new size and filled with the interpolated
+ * values. This class is used in the step-15, step-31, and step-33 tutorial
+ * programs. A version of this class that works on parallel triangulations is
+ * available as parallel::distributed::SolutionTransfer.
  *
  * <h3>Usage</h3>
  *
  * This class implements the algorithms in two different ways:
-
  * <ul>
- * <li> If the grid will only be refined
- * (i.e. no cells are coarsened) then use @p SolutionTransfer as follows:
+ * <li> If the grid will only be refined (i.e. no cells are coarsened) then
+ * use @p SolutionTransfer as follows:
  * @code
  * SolutionTransfer<dim, double> soltrans(*dof_handler);
  *                                     // flag some cells for refinement, e.g.
@@ -77,21 +75,19 @@ DEAL_II_NAMESPACE_OPEN
  * soltrans.refine_interpolate(solution_old, solution);
  * @endcode
  *
- * Although the @p refine_interpolate functions are allowed to be
- * called multiple times, e.g. for interpolating several solution
- * vectors, there is following possibility of interpolating several
- * functions simultaneously.
+ * Although the @p refine_interpolate functions are allowed to be called
+ * multiple times, e.g. for interpolating several solution vectors, there is
+ * following possibility of interpolating several functions simultaneously.
  * @code
  * vector<Vector<double> > solutions_old(n_vectors, Vector<double> (n));
  * ...
  * vector<Vector<double> > solutions(n_vectors, Vector<double> (n));
  * soltrans.refine_interpolate(solutions_old, solutions);
  * @endcode
- * This is used in several of the tutorial programs, for example
- * step-31.
+ * This is used in several of the tutorial programs, for example step-31.
  *
- * <li> If the grid has cells that will be coarsened,
- * then use @p SolutionTransfer as follows:
+ * <li> If the grid has cells that will be coarsened, then use @p
+ * SolutionTransfer as follows:
  * @code
  * SolutionTransfer<dim, Vector<double> > soltrans(*dof_handler);
  *                                     // flag some cells for refinement
@@ -114,88 +110,85 @@ DEAL_II_NAMESPACE_OPEN
  * soltrans.interpolate(solution, interpolated_solution);
  * @endcode
  *
- * Multiple calls to the function
- * <tt>interpolate (const Vector<number> &in, Vector<number> &out)</tt>
- * are NOT allowed. Interpolating several functions can be performed in one step
- * by using
- * <tt>void interpolate (const vector<Vector<number> >&all_in, vector<Vector<number> >&all_out) const</tt>,
- * and using the respective @p prepare_for_coarsening_and_refinement function
- * taking several vectors as input before actually refining and coarsening the
- * triangulation (see there).
+ * Multiple calls to the function <tt>interpolate (const Vector<number> &in,
+ * Vector<number> &out)</tt> are NOT allowed. Interpolating several functions
+ * can be performed in one step by using <tt>void interpolate (const
+ * vector<Vector<number> >&all_in, vector<Vector<number> >&all_out)
+ * const</tt>, and using the respective @p
+ * prepare_for_coarsening_and_refinement function taking several vectors as
+ * input before actually refining and coarsening the triangulation (see
+ * there).
  * </ul>
  *
  * For deleting all stored data in @p SolutionTransfer and reinitializing it
  * use the <tt>clear()</tt> function.
  *
- * The template argument @p number denotes the data type of the vectors you want
- * to transfer.
+ * The template argument @p number denotes the data type of the vectors you
+ * want to transfer.
  *
  *
  * <h3>Implementation</h3>
  *
  * <ul>
  * <li> Solution transfer with only refinement. Assume that we have got a
- * solution vector on the current (original) grid.
- * Each entry of this vector belongs to one of the
- * DoFs of the discretization. If we now refine the grid then the calling of
- * DoFHandler::distribute_dofs() will change at least some of the
- * DoF indices. Hence we need to store the DoF indices of all active cells
- * before the refinement. A pointer for each active cell
- * is used to point to the vector of these DoF indices of that cell.
- * This is done by prepare_for_pure_refinement().
+ * solution vector on the current (original) grid. Each entry of this vector
+ * belongs to one of the DoFs of the discretization. If we now refine the grid
+ * then the calling of DoFHandler::distribute_dofs() will change at least some
+ * of the DoF indices. Hence we need to store the DoF indices of all active
+ * cells before the refinement. A pointer for each active cell is used to
+ * point to the vector of these DoF indices of that cell. This is done by
+ * prepare_for_pure_refinement().
  *
- * In the function <tt>refine_interpolate(in,out)</tt> and on each cell where the
- * pointer is set (i.e. the cells that were active in the original grid)
- * we can now access the local values of the solution vector @p in
- * on that cell by using the stored DoF indices. These local values are
- * interpolated and set into the vector @p out that is at the end the
- * discrete function @p in interpolated on the refined mesh.
+ * In the function <tt>refine_interpolate(in,out)</tt> and on each cell where
+ * the pointer is set (i.e. the cells that were active in the original grid)
+ * we can now access the local values of the solution vector @p in on that
+ * cell by using the stored DoF indices. These local values are interpolated
+ * and set into the vector @p out that is at the end the discrete function @p
+ * in interpolated on the refined mesh.
  *
- * The <tt>refine_interpolate(in,out)</tt> function can be called multiple times for
- * arbitrary many discrete functions (solution vectors) on the original grid.
+ * The <tt>refine_interpolate(in,out)</tt> function can be called multiple
+ * times for arbitrary many discrete functions (solution vectors) on the
+ * original grid.
  *
- * <li> Solution transfer with coarsening and refinement. After
- * calling Triangulation::prepare_coarsening_and_refinement the
- * coarsen flags of either all or none of the children of a
- * (father-)cell are set. While coarsening
- * (Triangulation::execute_coarsening_and_refinement)
- * the cells that are not needed any more will be deleted from the Triangulation.
+ * <li> Solution transfer with coarsening and refinement. After calling
+ * Triangulation::prepare_coarsening_and_refinement the coarsen flags of
+ * either all or none of the children of a (father-)cell are set. While
+ * coarsening (Triangulation::execute_coarsening_and_refinement) the cells
+ * that are not needed any more will be deleted from the Triangulation.
  *
  * For the interpolation from the (to be coarsenend) children to their father
- * the children cells are needed. Hence this interpolation
- * and the storing of the interpolated values of each of the discrete functions
- * that we want to interpolate needs to take place before these children cells
- * are coarsened (and deleted!!). Again a pointers for the relevant cells is
- * set to point to these values (see below).
- * Additionally the DoF indices of the cells
- * that will not be coarsened need to be stored according to the solution
- * transfer while pure refinement (cf there). All this is performed by
+ * the children cells are needed. Hence this interpolation and the storing of
+ * the interpolated values of each of the discrete functions that we want to
+ * interpolate needs to take place before these children cells are coarsened
+ * (and deleted!!). Again a pointers for the relevant cells is set to point to
+ * these values (see below). Additionally the DoF indices of the cells that
+ * will not be coarsened need to be stored according to the solution transfer
+ * while pure refinement (cf there). All this is performed by
  * <tt>prepare_for_coarsening_and_refinement(all_in)</tt> where the
- * <tt>vector<Vector<number> >vector all_in</tt> includes
- * all discrete functions to be interpolated onto the new grid.
+ * <tt>vector<Vector<number> >vector all_in</tt> includes all discrete
+ * functions to be interpolated onto the new grid.
  *
- * As we need two different kinds of pointers (<tt>vector<unsigned int> *</tt> for the Dof
- * indices and <tt>vector<Vector<number> > *</tt> for the interpolated DoF values)
- * we use the @p Pointerstruct that includes both of these pointers and
- * the pointer for each cell points to these @p Pointerstructs.
- * On each cell only one of the two different pointers is used at one time
- * hence we could use a
- * <tt>void * pointer</tt> as <tt>vector<unsigned int> *</tt> at one time and as
- * <tt>vector<Vector<number> > *</tt> at the other but using this @p Pointerstruct
- * in between makes the use of these pointers more safe and gives better
- * possibility to expand their usage.
+ * As we need two different kinds of pointers (<tt>vector<unsigned int> *</tt>
+ * for the Dof indices and <tt>vector<Vector<number> > *</tt> for the
+ * interpolated DoF values) we use the @p Pointerstruct that includes both of
+ * these pointers and the pointer for each cell points to these @p
+ * Pointerstructs. On each cell only one of the two different pointers is used
+ * at one time hence we could use a <tt>void * pointer</tt> as
+ * <tt>vector<unsigned int> *</tt> at one time and as
+ * <tt>vector<Vector<number> > *</tt> at the other but using this @p
+ * Pointerstruct in between makes the use of these pointers more safe and
+ * gives better possibility to expand their usage.
  *
- * In <tt>interpolate(all_in, all_out)</tt> the refined cells are treated according
- * to the solution transfer while pure refinement. Additionally, on each
- * cell that is coarsened (hence previously was a father cell),
- * the values of the discrete
- * functions in @p all_out are set to the stored local interpolated values
- * that are accessible due to the 'vector<Vector<number> > *' pointer in
- * @p Pointerstruct that is pointed to by the pointer of that cell.
- * It is clear that <tt>interpolate(all_in, all_out)</tt> only can be called with
- * the <tt>vector<Vector<number> > all_in</tt> that previously was the parameter
- * of the <tt>prepare_for_coarsening_and_refinement(all_in)</tt> function. Hence
- * <tt>interpolate(all_in, all_out)</tt> can (in contrast to
+ * In <tt>interpolate(all_in, all_out)</tt> the refined cells are treated
+ * according to the solution transfer while pure refinement. Additionally, on
+ * each cell that is coarsened (hence previously was a father cell), the
+ * values of the discrete functions in @p all_out are set to the stored local
+ * interpolated values that are accessible due to the 'vector<Vector<number> >
+ * *' pointer in @p Pointerstruct that is pointed to by the pointer of that
+ * cell. It is clear that <tt>interpolate(all_in, all_out)</tt> only can be
+ * called with the <tt>vector<Vector<number> > all_in</tt> that previously was
+ * the parameter of the <tt>prepare_for_coarsening_and_refinement(all_in)</tt>
+ * function. Hence <tt>interpolate(all_in, all_out)</tt> can (in contrast to
  * <tt>refine_interpolate(in, out)</tt>) only be called once.
  * </ul>
  *
@@ -244,29 +237,30 @@ DEAL_II_NAMESPACE_OPEN
  *
  * <h3>Implementation in the context of hp finite elements</h3>
  *
- * In the case of hp::DoFHandlers, nothing defines which of the finite elements
- * that are part of the hp::FECollection associated with the DoF handler, should
- * be considered on cells that are not active (i.e., that have children). This
- * is because degrees of freedom are only allocated for active cells and, in fact,
- * it is not allowed to set an active_fe_index on non-active cells using
- * DoFAccessor::set_active_fe_index().
+ * In the case of hp::DoFHandlers, nothing defines which of the finite
+ * elements that are part of the hp::FECollection associated with the DoF
+ * handler, should be considered on cells that are not active (i.e., that have
+ * children). This is because degrees of freedom are only allocated for active
+ * cells and, in fact, it is not allowed to set an active_fe_index on non-
+ * active cells using DoFAccessor::set_active_fe_index().
  *
- * It is, thus, not entirely natural what should happen if, for example, a few cells
- * are coarsened away. This class then implements the following algorithm:
- * - If a cell is refined, then the values of the solution vector(s) are saved before
- *   refinement on the to-be-refined cell and in the space associated with this
- *   cell. These values are then interpolated to the finite element spaces of the
- *   children post-refinement. This may lose information if, for example, the old
- *   cell used a Q2 space and the children use Q1 spaces, or the information may
- *   be prolonged if the mother cell used a Q1 space and the children are Q2s.
- * - If cells are to be coarsened, then the values from the child cells are
- *   interpolated to the mother cell using the largest of the child cell spaces.
- *   For example, if the children of a cell use Q1, Q2 and Q3 spaces, then the
- *   values from the children are interpolated into a Q3 space on the mother cell.
- *   After refinement, this Q3 function on the mother cell is then interpolated into
- *   the space the user has selected for this cell (which may be different from
- *   Q3, in this example, if the user has set the active_fe_index for a different
- *   space post-refinement and before calling hp::DoFHandler::distribute_dofs()).
+ * It is, thus, not entirely natural what should happen if, for example, a few
+ * cells are coarsened away. This class then implements the following
+ * algorithm: - If a cell is refined, then the values of the solution
+ * vector(s) are saved before refinement on the to-be-refined cell and in the
+ * space associated with this cell. These values are then interpolated to the
+ * finite element spaces of the children post-refinement. This may lose
+ * information if, for example, the old cell used a Q2 space and the children
+ * use Q1 spaces, or the information may be prolonged if the mother cell used
+ * a Q1 space and the children are Q2s. - If cells are to be coarsened, then
+ * the values from the child cells are interpolated to the mother cell using
+ * the largest of the child cell spaces. For example, if the children of a
+ * cell use Q1, Q2 and Q3 spaces, then the values from the children are
+ * interpolated into a Q3 space on the mother cell. After refinement, this Q3
+ * function on the mother cell is then interpolated into the space the user
+ * has selected for this cell (which may be different from Q3, in this
+ * example, if the user has set the active_fe_index for a different space
+ * post-refinement and before calling hp::DoFHandler::distribute_dofs()).
  *
  * @note In the context of hp refinement, if cells are coarsened or the
  * polynomial degree is lowered on some cells, then the old finite element
@@ -276,7 +270,8 @@ DEAL_II_NAMESPACE_OPEN
  * transfering the solution.
  *
  * @ingroup numerics
- * @author Ralf Hartmann, 1999, Oliver Kayser-Herold and Wolfgang Bangerth, 2006, Wolfgang Bangerth 2014
+ * @author Ralf Hartmann, 1999, Oliver Kayser-Herold and Wolfgang Bangerth,
+ * 2006, Wolfgang Bangerth 2014
  */
 template<int dim, typename VECTOR=Vector<double>, class DH=DoFHandler<dim> >
 class SolutionTransfer
@@ -284,8 +279,7 @@ class SolutionTransfer
 public:
 
   /**
-   * Constructor, takes the current DoFHandler
-   * as argument.
+   * Constructor, takes the current DoFHandler as argument.
    */
   SolutionTransfer(const DH &dof);
 
@@ -295,120 +289,84 @@ public:
   ~SolutionTransfer();
 
   /**
-   * Reinit this class to the state that
-   * it has
-   * directly after calling the Constructor
+   * Reinit this class to the state that it has directly after calling the
+   * Constructor
    */
   void clear();
 
   /**
-   * Prepares the @p SolutionTransfer for
-   * pure refinement. It
-   * stores the dof indices of each cell.
-   * After calling this function
-   * only calling the @p refine_interpolate
-   * functions is allowed.
+   * Prepares the @p SolutionTransfer for pure refinement. It stores the dof
+   * indices of each cell. After calling this function only calling the @p
+   * refine_interpolate functions is allowed.
    */
   void prepare_for_pure_refinement();
 
   /**
-   * Prepares the @p SolutionTransfer for
-   * coarsening and refinement. It
-   * stores the dof indices of each cell and
-   * stores the dof values of the vectors in
-   * @p all_in in each cell that'll be coarsened.
-   * @p all_in includes all vectors
-   * that are to be interpolated
-   * onto the new (refined and/or
+   * Prepares the @p SolutionTransfer for coarsening and refinement. It stores
+   * the dof indices of each cell and stores the dof values of the vectors in
+   * @p all_in in each cell that'll be coarsened. @p all_in includes all
+   * vectors that are to be interpolated onto the new (refined and/or
    * coarsenend) grid.
    */
   void prepare_for_coarsening_and_refinement (const std::vector<VECTOR> &all_in);
 
   /**
-   * Same as previous function
-   * but for only one discrete function
-   * to be interpolated.
+   * Same as previous function but for only one discrete function to be
+   * interpolated.
    */
   void prepare_for_coarsening_and_refinement (const VECTOR &in);
 
   /**
-   * This function
-   * interpolates the discrete function @p in,
-   * which is a vector on the grid before the
-   * refinement, to the function @p out
-   * which then is a vector on the refined grid.
-   * It assumes the vectors having the
-   * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
+   * This function interpolates the discrete function @p in, which is a vector
+   * on the grid before the refinement, to the function @p out which then is a
+   * vector on the refined grid. It assumes the vectors having the right sizes
+   * (i.e. <tt>in.size()==n_dofs_old</tt>,
    * <tt>out.size()==n_dofs_refined</tt>)
    *
-   * Calling this function is allowed only
-   * if @p prepare_for_pure_refinement is called
-   * and the refinement is
-   * executed before.
-   * Multiple calling of this function is
-   * allowed. e.g. for interpolating several
-   * functions.
+   * Calling this function is allowed only if @p prepare_for_pure_refinement
+   * is called and the refinement is executed before. Multiple calling of this
+   * function is allowed. e.g. for interpolating several functions.
    */
   void refine_interpolate (const VECTOR &in,
                            VECTOR &out) const;
 
   /**
-   * This function
-   * interpolates the discrete functions
-   * that are stored in @p all_in onto
-   * the refined and/or coarsenend grid.
-   * It assumes the vectors in @p all_in
-   * denote the same vectors
-   * as in @p all_in as parameter of
-   * <tt>prepare_for_refinement_and_coarsening(all_in)</tt>.
-   * However, there is no way of verifying
-   * this internally, so be careful here.
+   * This function interpolates the discrete functions that are stored in @p
+   * all_in onto the refined and/or coarsenend grid. It assumes the vectors in
+   * @p all_in denote the same vectors as in @p all_in as parameter of
+   * <tt>prepare_for_refinement_and_coarsening(all_in)</tt>. However, there is
+   * no way of verifying this internally, so be careful here.
    *
-   * Calling this function is
-   * allowed only if first
-   * Triangulation::prepare_coarsening_and_refinement,
-   * second
-   * @p SolutionTransfer::prepare_for_coarsening_and_refinement,
-   * an then third
-   * Triangulation::execute_coarsening_and_refinement
-   * are called before. Multiple
-   * calling of this function is
-   * NOT allowed. Interpolating
-   * several functions can be
-   * performed in one step.
+   * Calling this function is allowed only if first
+   * Triangulation::prepare_coarsening_and_refinement, second @p
+   * SolutionTransfer::prepare_for_coarsening_and_refinement, an then third
+   * Triangulation::execute_coarsening_and_refinement are called before.
+   * Multiple calling of this function is NOT allowed. Interpolating several
+   * functions can be performed in one step.
    *
-   * The number of output vectors
-   * is assumed to be the same as
-   * the number of input
-   * vectors. Also, the sizes of
-   * the output vectors are assumed
-   * to be of the right size
-   * (@p n_dofs_refined). Otherwise
-   * an assertion will be thrown.
+   * The number of output vectors is assumed to be the same as the number of
+   * input vectors. Also, the sizes of the output vectors are assumed to be of
+   * the right size (@p n_dofs_refined). Otherwise an assertion will be
+   * thrown.
    */
   void interpolate (const std::vector<VECTOR> &all_in,
                     std::vector<VECTOR>      &all_out) const;
 
   /**
-   * Same as the previous function.
-   * It interpolates only one function.
-   * It assumes the vectors having the
-   * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
-   * <tt>out.size()==n_dofs_refined</tt>)
+   * Same as the previous function. It interpolates only one function. It
+   * assumes the vectors having the right sizes (i.e.
+   * <tt>in.size()==n_dofs_old</tt>, <tt>out.size()==n_dofs_refined</tt>)
    *
-   * Multiple calling of this function is
-   * NOT allowed. Interpolating
-   * several functions can be performed
-   * in one step by using
-   * <tt>interpolate (all_in, all_out)</tt>
+   * Multiple calling of this function is NOT allowed. Interpolating several
+   * functions can be performed in one step by using <tt>interpolate (all_in,
+   * all_out)</tt>
    */
   void interpolate (const VECTOR &in,
                     VECTOR       &out) const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -450,27 +408,19 @@ public:
 private:
 
   /**
-   * Pointer to the degree of freedom handler
-   * to work with.
+   * Pointer to the degree of freedom handler to work with.
    */
   SmartPointer<const DH,SolutionTransfer<dim,VECTOR,DH> > dof_handler;
 
   /**
-   * Stores the number of DoFs before the
-   * refinement and/or coarsening.
+   * Stores the number of DoFs before the refinement and/or coarsening.
    */
   types::global_dof_index n_dofs_old;
 
   /**
-   * Declaration of
-   * @p PreparationState that
-   * denotes the three possible
-   * states of the
-   * @p SolutionTransfer: being
-   * prepared for 'pure
-   * refinement', prepared for
-   * 'coarsening and refinement' or
-   * not prepared.
+   * Declaration of @p PreparationState that denotes the three possible states
+   * of the @p SolutionTransfer: being prepared for 'pure refinement',
+   * prepared for 'coarsening and refinement' or not prepared.
    */
   enum PreparationState
   {
@@ -484,31 +434,21 @@ private:
 
 
   /**
-   * Is used for @p prepare_for_refining
-   * (of course also for
-   * @p repare_for_refining_and_coarsening)
-   * and stores all dof indices
-   * of the cells that'll be refined
+   * Is used for @p prepare_for_refining (of course also for @p
+   * repare_for_refining_and_coarsening) and stores all dof indices of the
+   * cells that'll be refined
    */
   std::vector<std::vector<types::global_dof_index> > indices_on_cell;
 
   /**
-   * All cell data (the dof indices and
-   * the dof values)
-   * should be accessible from each cell.
-   * As each cell has got only one
-   * @p user_pointer, multiple pointers to the
-   * data need to be packetized in a structure.
-   * Note that in our case on each cell
-   * either the
-   * <tt>vector<unsigned int> indices</tt> (if the cell
-   * will be refined) or the
-   * <tt>vector<double> dof_values</tt> (if the
-   * children of this cell will be deleted)
-   * is needed, hence one @p user_pointer should
-   * be sufficient, but to allow some error checks
-   * and to preserve the user from making
-   * user errors the @p user_pointer will be
+   * All cell data (the dof indices and the dof values) should be accessible
+   * from each cell. As each cell has got only one @p user_pointer, multiple
+   * pointers to the data need to be packetized in a structure. Note that in
+   * our case on each cell either the <tt>vector<unsigned int> indices</tt>
+   * (if the cell will be refined) or the <tt>vector<double> dof_values</tt>
+   * (if the children of this cell will be deleted) is needed, hence one @p
+   * user_pointer should be sufficient, but to allow some error checks and to
+   * preserve the user from making user errors the @p user_pointer will be
    * 'multiplied' by this structure.
    */
   struct Pointerstruct
@@ -533,22 +473,16 @@ private:
   };
 
   /**
-   * Map mapping from level and index of cell
-   * to the @p Pointerstructs (cf. there).
-   * This map makes it possible to keep all
-   * the information needed to transfer the
-   * solution inside this object rather than
-   * using user pointers of the Triangulation
-   * for this purpose.
+   * Map mapping from level and index of cell to the @p Pointerstructs (cf.
+   * there). This map makes it possible to keep all the information needed to
+   * transfer the solution inside this object rather than using user pointers
+   * of the Triangulation for this purpose.
    */
   std::map<std::pair<unsigned int, unsigned int>, Pointerstruct> cell_map;
 
   /**
-   * Is used for
-   * @p prepare_for_refining_and_coarsening
-   * The interpolated dof values
-   * of all cells that'll be coarsened
-   * will be stored in this vector.
+   * Is used for @p prepare_for_refining_and_coarsening The interpolated dof
+   * values of all cells that'll be coarsened will be stored in this vector.
    */
   std::vector<std::vector<Vector<typename VECTOR::value_type> > > dof_values_on_cell;
 };
index 980bed3fb3c5c713b6fa28f8299664e2215cacbd..8a6311f8fc73b75ed213811dc8e9d385f28790e2 100644 (file)
@@ -36,42 +36,42 @@ template <typename number> class Vector;
 template <int dim, int spacedim> class Triangulation;
 
 /**
- * This class provides an abstract interface to time dependent problems in that
- * it addresses some of the most annoying aspects of this class of problems:
- * data management. These problems frequently need large amounts of computer
- * ressources, most notably computing time, main memory and disk space.
- * Main memory reduction is often the most pressing need, methods to implement
- * it are almost always quite messy, though, quickly leading to code that
- * stores and reloads data at places scattered all over the program, and
- * which becomes unmaintainable sometimes. The present class tries to offer
- * more structured interface, albeit simple, which emerged in my mind after
+ * This class provides an abstract interface to time dependent problems in
+ * that it addresses some of the most annoying aspects of this class of
+ * problems: data management. These problems frequently need large amounts of
+ * computer ressources, most notably computing time, main memory and disk
+ * space. Main memory reduction is often the most pressing need, methods to
+ * implement it are almost always quite messy, though, quickly leading to code
+ * that stores and reloads data at places scattered all over the program, and
+ * which becomes unmaintainable sometimes. The present class tries to offer a
+ * more structured interface, albeit simple, which emerged in my mind after
  * messing with my wave equation simulation for several months.
  *
  * The design of this class is mostly tailored for the solution of time
- * dependent partial differential equations where the computational
- * meshes may differ between each two timesteps and where the computations
- * on each time step take a rather long time compared with the overhead
- * of this class. Since no reference to the class of problems is made within
- * this class, it is not restricted to PDEs, though, and it seems likely that
- * a solver for large ordinary matrix differential equations may successfully
- * use the same setup and therefore this class.
+ * dependent partial differential equations where the computational meshes may
+ * differ between each two timesteps and where the computations on each time
+ * step take a rather long time compared with the overhead of this class.
+ * Since no reference to the class of problems is made within this class, it
+ * is not restricted to PDEs, though, and it seems likely that a solver for
+ * large ordinary matrix differential equations may successfully use the same
+ * setup and therefore this class.
  *
  *
  * <h3>Overview</h3>
  *
- * The general structure of a time dependent problem solver using a timestepping
- * scheme is about the following: we have a collection of time step objects
- * on which we solve our problem subsequently. In order to do so, we need
- * knowledge of the data on zero or several previous timesteps (when using single
- * or multiple step methods, that is) and maybe also some data of time steps
- * ahead (for example the computational grid on these). Dependening on the
- * problem in question, a second loop over all timesteps may be done solving
- * a dual problem, where the loop may run forward (one dual problem for each
- * time step) or backward (using a global dual problem). Within one of these
- * loops or using a separate loop, error estimators may be computed and the
- * grids may be refined. Each of these loops are initiated by a call preparing
- * each timestep object for the next loop, before actually starting the loop
- * itself.
+ * The general structure of a time dependent problem solver using a
+ * timestepping scheme is about the following: we have a collection of time
+ * step objects on which we solve our problem subsequently. In order to do so,
+ * we need knowledge of the data on zero or several previous timesteps (when
+ * using single or multiple step methods, that is) and maybe also some data of
+ * time steps ahead (for example the computational grid on these). Dependening
+ * on the problem in question, a second loop over all timesteps may be done
+ * solving a dual problem, where the loop may run forward (one dual problem
+ * for each time step) or backward (using a global dual problem). Within one
+ * of these loops or using a separate loop, error estimators may be computed
+ * and the grids may be refined. Each of these loops are initiated by a call
+ * preparing each timestep object for the next loop, before actually starting
+ * the loop itself.
  *
  * We will denote a complete set of all these loops with the term "sweep".
  * Since this library is mostly about adaptive methods, it is likely that the
@@ -112,20 +112,20 @@ template <int dim, int spacedim> class Triangulation;
  * being needed for the solution of global dual problems, for example).
  *
  * Going from the global overview to a more local viewpoint, we note that when
- * a loop visits one timestep (e.g. to solve the primal or dual problem, or
- * to compute error information), we need information on this, one or more
+ * a loop visits one timestep (e.g. to solve the primal or dual problem, or to
+ * compute error information), we need information on this, one or more
  * previous time steps and zero or more timesteps in the future. However,
- * often it is not needed to know all information from these timesteps and
- * it is often a computational requirement to delete data at the first
- * possible time when it is no more needed. Likewise, data should be reloaded
- * at the latest time possible.
+ * often it is not needed to know all information from these timesteps and it
+ * is often a computational requirement to delete data at the first possible
+ * time when it is no more needed. Likewise, data should be reloaded at the
+ * latest time possible.
  *
  * In order to facilitate these principles, the concept of waking up and
  * letting sleep a time step object was developed. Assume we have a time
- * stepping scheme which needs to look ahead one time step and needs the
- * data of the last two time steps, the following pseudocode described
- * what the centeral loop function of this class will do when we move
- * from timestep @p n-1 to timestep @p n:
+ * stepping scheme which needs to look ahead one time step and needs the data
+ * of the last two time steps, the following pseudocode described what the
+ * centeral loop function of this class will do when we move from timestep @p
+ * n-1 to timestep @p n:
  * @verbatim
  *   wake up timestep n+1 with signal 1
  *   wake up timestep n with signal 0
@@ -136,24 +136,23 @@ template <int dim, int spacedim> class Triangulation;
  *
  *   move from n to n+1
  * @endverbatim
- * The signal number here denotes the distance of the timestep being sent
- * the signal to the timestep where computations are done on. The calls to
- * the @p wake_up and @p sleep functions with signal 0 could in principle
- * be absorbed into the function doing the computation; we use these
- * redundant signals, however, in order to separate computations and data
- * management from each other, allowing to put all stuff around grid
- * management, data reload and storage into one set of functions and
- * computations into another.
+ * The signal number here denotes the distance of the timestep being sent the
+ * signal to the timestep where computations are done on. The calls to the @p
+ * wake_up and @p sleep functions with signal 0 could in principle be absorbed
+ * into the function doing the computation; we use these redundant signals,
+ * however, in order to separate computations and data management from each
+ * other, allowing to put all stuff around grid management, data reload and
+ * storage into one set of functions and computations into another.
  *
- * In the example above, possible actions might be: timestep <tt>n+1</tt> rebuilds
- * the computational grid (there is a specialized class which can do this
- * for you); timestep @p n builds matrices sets solution vectors to the right
- * size, maybe using an initial guess; then it does the computations; then
- * it deletes the matrices since they are not needed by subsequent timesteps;
- * timestep @p n-1 deletes those data vectors which are only needed by one
- * timestep ahead; timestep @p n-2 deletes the remaining vectors and deletes
- * the computational grid, somewhere storing information how to rebuild it
- * eventually.
+ * In the example above, possible actions might be: timestep <tt>n+1</tt>
+ * rebuilds the computational grid (there is a specialized class which can do
+ * this for you); timestep @p n builds matrices sets solution vectors to the
+ * right size, maybe using an initial guess; then it does the computations;
+ * then it deletes the matrices since they are not needed by subsequent
+ * timesteps; timestep @p n-1 deletes those data vectors which are only needed
+ * by one timestep ahead; timestep @p n-2 deletes the remaining vectors and
+ * deletes the computational grid, somewhere storing information how to
+ * rebuild it eventually.
  *
  * From the given sketch above, it is clear that each time step object sees
  * the following sequence of events:
@@ -167,29 +166,28 @@ template <int dim, int spacedim> class Triangulation;
  * @endverbatim
  * This pattern is repeated for each loop in each sweep.
  *
- * For the different loops within each sweep, the numbers of timesteps
- * to look ahead (i.e. the maximum signal number to the @p wake_up function)
- * and the look-behind (i.e. the maximum signal number to the @p sleep
- * function) can be chosen separately. For example, it is usually only
- * needed to look one time step behind when computing error estimation
- * (in some cases, it may vene be possible to not look ahead or back
- * at all, in which case only signals zero will be sent), while one
- * needs a look back of at least one for a timestepping method.
+ * For the different loops within each sweep, the numbers of timesteps to look
+ * ahead (i.e. the maximum signal number to the @p wake_up function) and the
+ * look-behind (i.e. the maximum signal number to the @p sleep function) can
+ * be chosen separately. For example, it is usually only needed to look one
+ * time step behind when computing error estimation (in some cases, it may
+ * vene be possible to not look ahead or back at all, in which case only
+ * signals zero will be sent), while one needs a look back of at least one for
+ * a timestepping method.
  *
- * Finally, a note on the direction of look-ahead and look-back is in
- * place: look-ahead always refers to the direction the loop is running
- * in, i.e. for loops running forward, @p wake_up is called for timestep
- * objects with a greater time value than the one previously computed on,
- * while @p sleep is called for timesteps with a lower time. If the loop
- * runs in the opposite direction, e.g. when solving a global dual
- * problem, this order is reversed.
+ * Finally, a note on the direction of look-ahead and look-back is in place:
+ * look-ahead always refers to the direction the loop is running in, i.e. for
+ * loops running forward, @p wake_up is called for timestep objects with a
+ * greater time value than the one previously computed on, while @p sleep is
+ * called for timesteps with a lower time. If the loop runs in the opposite
+ * direction, e.g. when solving a global dual problem, this order is reversed.
  *
  *
  * <h3>Implementation</h3>
  *
- * The main loop of a program using this class will usually look like
- * the following one, taken modified from an application program that
- * isn't distributed as part of the library:
+ * The main loop of a program using this class will usually look like the
+ * following one, taken modified from an application program that isn't
+ * distributed as part of the library:
  * @code
  *   template <int dim>
  *   void TimeDependent_Wave<dim>::run_sweep (const unsigned int sweep_no)
@@ -221,11 +219,11 @@ template <int dim, int spacedim> class Triangulation;
  *   };
  * @endcode
  * Here, @p timestep_manager is an object of type TimeDependent_Wave(), which
- * is a class derived from TimeDependent. @p start_sweep,
- * @p solve_primal_problem, @p solve_dual_problem, @p postprocess and @p end_sweep
- * are functions inherited from this class. They all do a loop over all
- * timesteps within this object and call the respective function on each of
- * these objects. For example, here are two of the functions as they are
+ * is a class derived from TimeDependent. @p start_sweep, @p
+ * solve_primal_problem, @p solve_dual_problem, @p postprocess and @p
+ * end_sweep are functions inherited from this class. They all do a loop over
+ * all timesteps within this object and call the respective function on each
+ * of these objects. For example, here are two of the functions as they are
  * implemented by the library:
  * @code
  *   void TimeDependent::start_sweep (const unsigned int s)
@@ -259,26 +257,26 @@ template <int dim, int spacedim> class Triangulation;
  *              forward);
  *   };
  * @endcode
- * The latter function shows rather clear how most of the loops are
- * invoked (@p solve_primal_problem, @p solve_dual_problem, @p postprocess,
- * @p refine_grids and @p write_statistics all have this form, where the
- * latter two give functions of the derived timestep class, rather than
- * from the base class). The function TimeStepBase::init_for_primal_problem
- * and the respective ones for the other operations defined by that class
- * are only used to store the type of operation which the loop presently
- * performed will do.
+ * The latter function shows rather clear how most of the loops are invoked
+ * (@p solve_primal_problem, @p solve_dual_problem, @p postprocess, @p
+ * refine_grids and @p write_statistics all have this form, where the latter
+ * two give functions of the derived timestep class, rather than from the base
+ * class). The function TimeStepBase::init_for_primal_problem and the
+ * respective ones for the other operations defined by that class are only
+ * used to store the type of operation which the loop presently performed will
+ * do.
  *
- * As can be seen, most of the work is done by the @p do_loop function of
- * this class, which takes the addresses of two functions which are used
- * to initialize all timestep objects for the loop and to actually perform
- * some action. The next parameter gives some information on the look-ahead
- * and look-back and the last one denotes in which direction the loop is
- * to be run.
+ * As can be seen, most of the work is done by the @p do_loop function of this
+ * class, which takes the addresses of two functions which are used to
+ * initialize all timestep objects for the loop and to actually perform some
+ * action. The next parameter gives some information on the look-ahead and
+ * look-back and the last one denotes in which direction the loop is to be
+ * run.
  *
- * Using function pointers through the @p mem_fun functions provided by
- * the <tt>C++</tt> standard library, it is possible to do neat tricks, like
- * the following, also taken from the wave program, in this case from
- * the function @p refine_grids:
+ * Using function pointers through the @p mem_fun functions provided by the
+ * <tt>C++</tt> standard library, it is possible to do neat tricks, like the
+ * following, also taken from the wave program, in this case from the function
+ * @p refine_grids:
  * @code
  *   ...
  *   compute the thresholds for refinement
@@ -291,18 +289,18 @@ template <int dim, int spacedim> class Triangulation;
  *            TimeDependent::TimeSteppingData (0,1),
  *            TimeDependent::forward);
  * @endcode
- * TimeStepBase_Wave::refine_grid is a function taking an argument, unlike
- * all the other functions used above within the loops. However, in this special
+ * TimeStepBase_Wave::refine_grid is a function taking an argument, unlike all
+ * the other functions used above within the loops. However, in this special
  * case the parameter was the same for all timesteps and known before the loop
  * was started, so we fixed it and made a function object which to the outside
  * world does not take parameters.
  *
  * Since it is the central function of this class, we finally present a
- * stripped down version of the @p do_loop method, which is shown in order
- * to provide a better understanding of the internals of this class. For
- * brevity we have omitted the parts that deal with backward running loops
- * as well as the checks whether wake-up and sleep operations act on timesteps
- * outside <tt>0..n_timesteps-1</tt>.
+ * stripped down version of the @p do_loop method, which is shown in order to
+ * provide a better understanding of the internals of this class. For brevity
+ * we have omitted the parts that deal with backward running loops as well as
+ * the checks whether wake-up and sleep operations act on timesteps outside
+ * <tt>0..n_timesteps-1</tt>.
  * @code
  *   template <typename InitFunctionObject, typename LoopFunctionObject>
  *   void TimeDependent::do_loop (InitFunctionObject      init_function,
@@ -354,83 +352,58 @@ class TimeDependent
 {
 public:
   /**
-   * Structure holding the two basic
-   * entities that control a loop over
-   * all time steps: how many time steps
-   * ahead of the present one we shall
-   * start waking up timestep objects
-   * and how many timesteps behind
-   * we shall call their @p sleep
-   * method.
+   * Structure holding the two basic entities that control a loop over all
+   * time steps: how many time steps ahead of the present one we shall start
+   * waking up timestep objects and how many timesteps behind we shall call
+   * their @p sleep method.
    */
   struct TimeSteppingData
   {
     /**
-     * Constructor; see the different
-     * fields for a description of the
-     * meaning of the parameters.
+     * Constructor; see the different fields for a description of the meaning
+     * of the parameters.
      */
     TimeSteppingData (const unsigned int look_ahead,
                       const unsigned int look_back);
 
     /**
-     * This denotes the number of timesteps
-     * the timestepping algorithm needs to
-     * look ahead. Usually, this number
-     * will be zero, since algorithms
-     * looking ahead can't act as
-     * timestepping schemes since they
-     * can't compute their data from knowledge
-     * of the past only and are therefore
+     * This denotes the number of timesteps the timestepping algorithm needs
+     * to look ahead. Usually, this number will be zero, since algorithms
+     * looking ahead can't act as timestepping schemes since they can't
+     * compute their data from knowledge of the past only and are therefore
      * global in time.
      *
-     * However, it may be necessary to look
-     * ahead in other circumstances, when
-     * not wanting to access the data of the
-     * next time step(s), but for example
-     * to know the next grid, the solution
-     * of a dual problem on the next
-     * time level, etc.
+     * However, it may be necessary to look ahead in other circumstances, when
+     * not wanting to access the data of the next time step(s), but for
+     * example to know the next grid, the solution of a dual problem on the
+     * next time level, etc.
      *
-     * Note that for a dual problem walking
-     * back in time, "looking ahead" means
-     * looking towards smaller time values.
+     * Note that for a dual problem walking back in time, "looking ahead"
+     * means looking towards smaller time values.
      *
-     * The value of this number determines,
-     * how many time steps ahead the
-     * time step manager start to call
-     * the @p wake_up function for each
-     * time step.
+     * The value of this number determines, how many time steps ahead the time
+     * step manager start to call the @p wake_up function for each time step.
      */
     const unsigned int look_ahead;
 
     /**
-     * This is the opposite variable to the
-     * above one. It denotes the number of
-     * time steps behind the present one
-     * for which we need to keep all data
-     * in order to do the computations on
-     * the present time level.
+     * This is the opposite variable to the above one. It denotes the number
+     * of time steps behind the present one for which we need to keep all data
+     * in order to do the computations on the present time level.
      *
-     * For one step schemes (e.g. the
-     * Euler schemes, or the Crank-Nicolson
+     * For one step schemes (e.g. the Euler schemes, or the Crank-Nicolson
      * scheme), this value will be one.
      *
-     * The value of this number
-     * determines, how many time
-     * steps after having done
-     * computations on a tim level
-     * the time step manager will
-     * call the @p sleep function for
-     * each time step.
+     * The value of this number determines, how many time steps after having
+     * done computations on a tim level the time step manager will call the @p
+     * sleep function for each time step.
      */
     const unsigned int look_back;
   };
 
   /**
-   * Enum offering the different directions
-   * in which a loop executed by
-   * @p do_loop may be run.
+   * Enum offering the different directions in which a loop executed by @p
+   * do_loop may be run.
    */
   enum Direction
   {
@@ -446,56 +419,39 @@ public:
 
 
   /**
-   * Destructor. This will delete the
-   * objects pointed to by the pointers
-   * given to the <tt>insert_*</tt> and
-   * @p add_timestep functions, i.e.
-   * it will delete the objects doing
-   * the computations on each time step.
+   * Destructor. This will delete the objects pointed to by the pointers given
+   * to the <tt>insert_*</tt> and @p add_timestep functions, i.e. it will
+   * delete the objects doing the computations on each time step.
    */
   virtual ~TimeDependent ();
 
   /**
-   * Add a timestep at any position. The
-   * position is a pointer to an existing
-   * time step object, or a null pointer
-   * denoting the end of the timestep
-   * sequence. If @p position is non-null,
-   * the new time step will be inserted
+   * Add a timestep at any position. The position is a pointer to an existing
+   * time step object, or a null pointer denoting the end of the timestep
+   * sequence. If @p position is non-null, the new time step will be inserted
    * before the respective element.
    *
-   * Note that by giving an object
-   * to this function, the
-   * TimeDependent object assumes
-   * ownership of the object; it will
-   * therefore also take care of
+   * Note that by giving an object to this function, the TimeDependent object
+   * assumes ownership of the object; it will therefore also take care of
    * deletion of the objects its manages.
    *
-   * There is another function,
-   * @p add_timestep, which inserts a
-   * time step at the end of the list.
+   * There is another function, @p add_timestep, which inserts a time step at
+   * the end of the list.
    *
-   * Note that this function does not
-   * change the timestep numbers stored
-   * within the other timestep objects,
-   * nor does it set the timestep number
-   * of this new timestep. This is only
-   * done upon calling the @p start_sweep
-   * function. In not changing the timestep
-   * numbers, it is simpler to operate
-   * on a space-time triangulation since
-   * one can always use the timestep numbers
-   * that were used in the previous sweep.
+   * Note that this function does not change the timestep numbers stored
+   * within the other timestep objects, nor does it set the timestep number of
+   * this new timestep. This is only done upon calling the @p start_sweep
+   * function. In not changing the timestep numbers, it is simpler to operate
+   * on a space-time triangulation since one can always use the timestep
+   * numbers that were used in the previous sweep.
    */
   void insert_timestep (const TimeStepBase *position,
                         TimeStepBase       *new_timestep);
 
   /**
-   * Just like @p insert_timestep, but
-   * insert at the end.
+   * Just like @p insert_timestep, but insert at the end.
    *
-   * This mechanism usually will result
-   * in a set-up loop like this
+   * This mechanism usually will result in a set-up loop like this
    * @code
    * for (i=0; i<N; ++i)
    *   manager.add_timestep(new MyTimeStep());
@@ -504,109 +460,74 @@ public:
   void add_timestep (TimeStepBase *new_timestep);
 
   /**
-   * Delete a timestep. This is only
-   * necessary to call, if you want to
-   * delete it between two sweeps; at
-   * the end of the lifetime of this object,
-   * care is taken automatically of
-   * deletion of the time step objects.
-   * Deletion of the object by the
-   * destructor is done through this
-   * function also.
+   * Delete a timestep. This is only necessary to call, if you want to delete
+   * it between two sweeps; at the end of the lifetime of this object, care is
+   * taken automatically of deletion of the time step objects. Deletion of the
+   * object by the destructor is done through this function also.
    *
-   * Note that this function does
-   * not change the timestep
-   * numbers stored within the
-   * other timestep objects. This
-   * is only done upon calling the
-   * @p start_sweep function. In not
-   * changing the timestep numbers,
-   * it is simpler to operate on a
-   * space-time triangulation since
-   * one can always use the
-   * timestep numbers that were
-   * used in the previous sweep.
+   * Note that this function does not change the timestep numbers stored
+   * within the other timestep objects. This is only done upon calling the @p
+   * start_sweep function. In not changing the timestep numbers, it is simpler
+   * to operate on a space-time triangulation since one can always use the
+   * timestep numbers that were used in the previous sweep.
    */
   void delete_timestep (const unsigned int position);
 
   /**
-   * Solve the primal problem; uses the
-   * functions @p init_for_primal_problem
-   * and @p solve_primal_problem of the
-   * TimeStepBase class through the
-   * @p do_loop function of this class.
+   * Solve the primal problem; uses the functions @p init_for_primal_problem
+   * and @p solve_primal_problem of the TimeStepBase class through the @p
+   * do_loop function of this class.
    *
-   * Look ahead and look back are
-   * determined by the @p timestepping_data_primal
-   * object given to the constructor.
+   * Look ahead and look back are determined by the @p
+   * timestepping_data_primal object given to the constructor.
    */
   void solve_primal_problem ();
 
   /**
-   * Solve the dual problem; uses the
-   * functions @p init_for_dual_problem
-   * and @p solve_dual_problem of the
-   * TimeStepBase class through the
-   * @p do_loop function of this class.
+   * Solve the dual problem; uses the functions @p init_for_dual_problem and
+   * @p solve_dual_problem of the TimeStepBase class through the @p do_loop
+   * function of this class.
    *
-   * Look ahead and look back are
-   * determined by the @p timestepping_data_dual
+   * Look ahead and look back are determined by the @p timestepping_data_dual
    * object given to the constructor.
    */
   void solve_dual_problem ();
 
   /**
-   * Do a postprocessing round; uses the
-   * functions @p init_for_postprocessing
-   * and @p postprocess of the
-   * TimeStepBase class through the
-   * @p do_loop function of this class.
+   * Do a postprocessing round; uses the functions @p init_for_postprocessing
+   * and @p postprocess of the TimeStepBase class through the @p do_loop
+   * function of this class.
    *
-   * Look ahead and look back are
-   * determined by the @p timestepping_data_postprocess
-   * object given to the constructor.
+   * Look ahead and look back are determined by the @p
+   * timestepping_data_postprocess object given to the constructor.
    */
   void postprocess ();
 
   /**
-   * Do a loop over all timesteps, call the
-   * @p init_function at the beginning and
-   * the @p loop_function of each time step.
-   * The @p timestepping_data determine how
-   * many timesteps in front and behind
-   * the present one the @p wake_up and
-   * @p sleep functions are called.
+   * Do a loop over all timesteps, call the @p init_function at the beginning
+   * and the @p loop_function of each time step. The @p timestepping_data
+   * determine how many timesteps in front and behind the present one the @p
+   * wake_up and @p sleep functions are called.
    *
-   * To see how this function work, note that
-   * the function @p solve_primal_problem only
-   * consists of a call to
-   * <tt>do_loop (mem_fun(&TimeStepBase::init_for_primal_problem),
-   *    mem_fun(&TimeStepBase::solve_primal_problem),
-   *    timestepping_data_primal, forward);</tt>.
+   * To see how this function work, note that the function @p
+   * solve_primal_problem only consists of a call to <tt>do_loop
+   * (mem_fun(&TimeStepBase::init_for_primal_problem),
+   * mem_fun(&TimeStepBase::solve_primal_problem), timestepping_data_primal,
+   * forward);</tt>.
    *
-   * Note also, that the given class from which
-   * the two functions are taken needs not
-   * necessarily be TimeStepBase, but it
-   * could also be a derived class, that is
-   * @p static_castable from a TimeStepBase.
-   * The function may be a virtual function
-   * (even a pure one) of that class, which
-   * should help if the actual class where it
-   * is implemented is one which is derived
-   * through virtual base classes and thus
-   * unreachable by @p static_cast from the
-   * TimeStepBase class.
+   * Note also, that the given class from which the two functions are taken
+   * needs not necessarily be TimeStepBase, but it could also be a derived
+   * class, that is @p static_castable from a TimeStepBase. The function may
+   * be a virtual function (even a pure one) of that class, which should help
+   * if the actual class where it is implemented is one which is derived
+   * through virtual base classes and thus unreachable by @p static_cast from
+   * the TimeStepBase class.
    *
-   * Instead of using the above form, you can
-   * equally well use
-   * <tt>bind2nd(mem_fun1(&X::unary_function), arg)</tt>
-   * which lets the @p do_loop
-   * function call the given function with
-   * the specified parameter. Note that you
-   * need to bind the second parameter since
-   * the first one implicitly contains
-   * the object which the function is to
-   * be called for.
+   * Instead of using the above form, you can equally well use
+   * <tt>bind2nd(mem_fun1(&X::unary_function), arg)</tt> which lets the @p
+   * do_loop function call the given function with the specified parameter.
+   * Note that you need to bind the second parameter since the first one
+   * implicitly contains the object which the function is to be called for.
    */
   template <typename InitFunctionObject, typename LoopFunctionObject>
   void do_loop (InitFunctionObject      init_function,
@@ -616,73 +537,48 @@ public:
 
 
   /**
-   * Initialize the objects for the next
-   * sweep. This function specifically does
-   * the following: assign each time
-   * level the number it presently has
-   * within the array (which may change,
-   * if time levels are inserted or
-   * deleted) and transmit the number of
-   * the present sweep to these objects.
+   * Initialize the objects for the next sweep. This function specifically
+   * does the following: assign each time level the number it presently has
+   * within the array (which may change, if time levels are inserted or
+   * deleted) and transmit the number of the present sweep to these objects.
    *
-   * It also calls the @p start_sweep
-   * function of each time step object,
-   * after the numbers above are set.
+   * It also calls the @p start_sweep function of each time step object, after
+   * the numbers above are set.
    *
-   * This function is virtual, so you
-   * may overload it. You should, however
-   * not forget to call this function as
-   * well from your overwritten version,
-   * at best at the beginning of your
-   * function since this is some kind of
-   * "constructor-like" function, which
-   * should be called bottom-up.
+   * This function is virtual, so you may overload it. You should, however not
+   * forget to call this function as well from your overwritten version, at
+   * best at the beginning of your function since this is some kind of
+   * "constructor-like" function, which should be called bottom-up.
    *
-   * The default implementation of this
-   * function calls @p start_sweep on all
+   * The default implementation of this function calls @p start_sweep on all
    * time step objects.
    */
   virtual void start_sweep (const unsigned int sweep_no);
 
   /**
-   * Analogon to the above
-   * function, calling @p end_sweep
-   * of each time step object. The
-   * same applies with respect to
-   * the @p virtualness of this
-   * function as for the previous
-   * one.
+   * Analogon to the above function, calling @p end_sweep of each time step
+   * object. The same applies with respect to the @p virtualness of this
+   * function as for the previous one.
    *
-   * @note This function does not
-   * guarantee that @p end_sweep is
-   * called for successive time
-   * steps successively, rather the order of
-   * time step objects for which the
-   * function is called is
-   * arbitrary. You should
-   * therefore not assume that that
-   * function has been called for
-   * previous time steps
-   * already. If in multithread
-   * mode, the @p end_sweep function
-   * of several time steps may be
-   * called at once, so you should
-   * use synchronization
-   * mechanisms if your program
-   * requires so.
+   * @note This function does not guarantee that @p end_sweep is called for
+   * successive time steps successively, rather the order of time step objects
+   * for which the function is called is arbitrary. You should therefore not
+   * assume that that function has been called for previous time steps
+   * already. If in multithread mode, the @p end_sweep function of several
+   * time steps may be called at once, so you should use synchronization
+   * mechanisms if your program requires so.
    */
   virtual void end_sweep ();
 
   /**
-   * @deprecated Use the function without an argument.
-   * @arg n_threads This argument is ignored.
+   * @deprecated Use the function without an argument. @arg n_threads This
+   * argument is ignored.
    */
   virtual void end_sweep (const unsigned int n_threads) DEAL_II_DEPRECATED;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    */
   std::size_t memory_consumption () const;
 
@@ -693,52 +589,41 @@ public:
 
 protected:
   /**
-   * Vector holding pointers to the time
-   * level objects. This is the main data
-   * this object operates on. Note that
-   * this object takes possession of the
-   * objects pointed to by the pointers
-   * in this collection.
+   * Vector holding pointers to the time level objects. This is the main data
+   * this object operates on. Note that this object takes possession of the
+   * objects pointed to by the pointers in this collection.
    */
   std::vector<SmartPointer<TimeStepBase,TimeDependent> > timesteps;
 
   /**
-   * Number of the present sweep. This is
-   * reset by the @p start_sweep function
+   * Number of the present sweep. This is reset by the @p start_sweep function
    * called at the outset of each sweep.
    */
   unsigned int sweep_no;
 
   /**
-   * Some flags telling the
-   * @p solve_primal_problem function what to
-   * do. See the documentation of this struct
-   * for more information.
+   * Some flags telling the @p solve_primal_problem function what to do. See
+   * the documentation of this struct for more information.
    */
   const TimeSteppingData timestepping_data_primal;
 
   /**
-   * Some flags telling the
-   * @p solve_dual_problem function what to
-   * do. See the documentation of this struct
-   * for more information.
+   * Some flags telling the @p solve_dual_problem function what to do. See the
+   * documentation of this struct for more information.
    */
   const TimeSteppingData timestepping_data_dual;
 
   /**
-   * Some flags telling the
-   * @p postprocess function what to
-   * do. See the documentation of this struct
-   * for more information.
+   * Some flags telling the @p postprocess function what to do. See the
+   * documentation of this struct for more information.
    */
   const TimeSteppingData timestepping_data_postprocess;
 
 private:
 
   /**
-   * Do the work of <tt>end_sweep()</tt>
-   * for some timesteps only. This
-   * is useful in multithread mode.
+   * Do the work of <tt>end_sweep()</tt> for some timesteps only. This is
+   * useful in multithread mode.
    */
   void end_sweep (const unsigned int begin_timestep,
                   const unsigned int end_timestep);
@@ -749,9 +634,9 @@ private:
 /**
  * Base class for a time step in time dependent problems. This class provides
  * barely more than the basic framework, defining the necessary virtual
- * functions (namely @p sleep and @p wake_up), the interface to previous
- * and following grids, and some functions to be called before a new loop
- * over all time steps is started.
+ * functions (namely @p sleep and @p wake_up), the interface to previous and
+ * following grids, and some functions to be called before a new loop over all
+ * time steps is started.
  *
  * @author Wolfgang Bangerth, 1999
  */
@@ -759,8 +644,7 @@ class TimeStepBase : public Subscriptor
 {
 public:
   /**
-   * Enum denoting the type of problem
-   * which will have to be solved next.
+   * Enum denoting the type of problem which will have to be solved next.
    */
   enum SolutionState
   {
@@ -770,238 +654,157 @@ public:
   };
 
   /**
-   * Constructor. Does nothing here apart
-   * from setting the time.
+   * Constructor. Does nothing here apart from setting the time.
    */
   TimeStepBase (const double time);
 
   /**
-   * Destructor. At present, this does
-   * nothing.
+   * Destructor. At present, this does nothing.
    */
   virtual ~TimeStepBase ();
 
   /**
-   * Reconstruct all the data that is
-   * needed for this time level to work.
-   * This function serves to reget all
-   * the variables and data structures
-   * to work again after they have been
-   * send to sleep some time before, or
-   * at the first time we visit this time
-   * level. In particular, it is used
-   * to reconstruct the triangulation,
-   * degree of freedom handlers, to reload
-   * data vectors in case they have been
-   * stored to disk, etc.
+   * Reconstruct all the data that is needed for this time level to work. This
+   * function serves to reget all the variables and data structures to work
+   * again after they have been send to sleep some time before, or at the
+   * first time we visit this time level. In particular, it is used to
+   * reconstruct the triangulation, degree of freedom handlers, to reload data
+   * vectors in case they have been stored to disk, etc.
    *
-   * The actual implementation of
-   * this function does nothing.
+   * The actual implementation of this function does nothing.
    *
-   * Since this is an important task, you
-   * should call this function from your
-   * own function, should you choose to
-   * overload it in your own class (which
-   * likely is the case), preferably at
-   * the beginning so that your function
-   * can take effect of the triangulation
-   * already existing.
+   * Since this is an important task, you should call this function from your
+   * own function, should you choose to overload it in your own class (which
+   * likely is the case), preferably at the beginning so that your function
+   * can take effect of the triangulation already existing.
    */
   virtual void wake_up (const unsigned int);
 
   /**
-   * This is the opposite function
-   * to @p wake_up. It is used to
-   * delete data or save it to disk
-   * after they are no more needed
-   * for the present sweep. Typical
-   * kinds of data for this are
-   * data vectors, degree of
-   * freedom handlers,
-   * triangulation objects,
-   * etc. which occupy large
-   * amounts of memory and may
-   * therefore be externalized.
+   * This is the opposite function to @p wake_up. It is used to delete data or
+   * save it to disk after they are no more needed for the present sweep.
+   * Typical kinds of data for this are data vectors, degree of freedom
+   * handlers, triangulation objects, etc. which occupy large amounts of
+   * memory and may therefore be externalized.
    *
-   * By default, this function does
-   * nothing.
+   * By default, this function does nothing.
    */
   virtual void sleep (const unsigned int);
 
   /**
-   * This function is called each time
-   * before a new sweep is started. You
-   * may want to set up some fields needed
-   * in the course of the computations,
-   * and so on. You should take good care,
-   * however, not to install large objects,
-   * which should be deferred until the
-   * @p wake_up function is called.
+   * This function is called each time before a new sweep is started. You may
+   * want to set up some fields needed in the course of the computations, and
+   * so on. You should take good care, however, not to install large objects,
+   * which should be deferred until the @p wake_up function is called.
    *
-   * A typical action of this function
-   * would be sorting out names of
-   * temporary files needed in the
-   * process of solving, etc.
+   * A typical action of this function would be sorting out names of temporary
+   * files needed in the process of solving, etc.
    *
-   * At the time this function is called,
-   * the values of @p timestep_no, @p sweep_no
-   * and the pointer to the previous and
-   * next time step object already have
-   * their correct value.
+   * At the time this function is called, the values of @p timestep_no, @p
+   * sweep_no and the pointer to the previous and next time step object
+   * already have their correct value.
    *
-   * The default implementation of this
-   * function does nothing.
+   * The default implementation of this function does nothing.
    */
   virtual void start_sweep ();
 
   /**
-   * This is the analogon to the above
-   * function, but it is called at the
-   * end of a sweep. You will usually want
-   * to do clean-ups in this function,
-   * such as deleting temporary files
-   * and the like.
+   * This is the analogon to the above function, but it is called at the end
+   * of a sweep. You will usually want to do clean-ups in this function, such
+   * as deleting temporary files and the like.
    */
   virtual void end_sweep ();
 
   /**
-   * Before the primal problem is
-   * solved on each time level, this
-   * function is called (i.e. before the
-   * solution takes place on the first
-   * time level). By default, this function
-   * sets the @p next_action variable of
-   * this class. You may overload this
-   * function, but you should call this
-   * function within your own one.
+   * Before the primal problem is solved on each time level, this function is
+   * called (i.e. before the solution takes place on the first time level). By
+   * default, this function sets the @p next_action variable of this class.
+   * You may overload this function, but you should call this function within
+   * your own one.
    */
   virtual void init_for_primal_problem ();
 
   /**
-   * Same as above, but called before
-   * a round of dual problem solves.
+   * Same as above, but called before a round of dual problem solves.
    */
   virtual void init_for_dual_problem ();
 
   /**
-   * Same as above, but called before
-   * a round of postprocessing steps.
+   * Same as above, but called before a round of postprocessing steps.
    */
   virtual void init_for_postprocessing ();
 
   /**
-   * This function is called by the
-   * manager object when solving the
-   * primal problem on this time level
-   * is needed. It is called after
-   * the @p wake_up function was
-   * called and before the @p sleep
-   * function will be called. There
-   * is no default implementation for
-   * obvious reasons, so you have
-   * to overload this function.
+   * This function is called by the manager object when solving the primal
+   * problem on this time level is needed. It is called after the @p wake_up
+   * function was called and before the @p sleep function will be called.
+   * There is no default implementation for obvious reasons, so you have to
+   * overload this function.
    */
   virtual void solve_primal_problem () = 0;
 
   /**
-   * This function is called by the
-   * manager object when solving the
-   * dual problem on this time level
-   * is needed. It is called after
-   * the @p wake_up function was
-   * called and before the @p sleep
-   * function will be called. There
-   * is a default implementation
-   * doing plain nothing since some
-   * problems may not need solving a
-   * dual problem. However, it
-   * will abort the program when
-   * being called anyway, since then you
-   * should really overload the function.
+   * This function is called by the manager object when solving the dual
+   * problem on this time level is needed. It is called after the @p wake_up
+   * function was called and before the @p sleep function will be called.
+   * There is a default implementation doing plain nothing since some problems
+   * may not need solving a dual problem. However, it will abort the program
+   * when being called anyway, since then you should really overload the
+   * function.
    */
   virtual void solve_dual_problem ();
 
   /**
-   * This function is called by the
-   * manager object when postprocessing
-   * this time level
-   * is needed. It is called after
-   * the @p wake_up function was
-   * called and before the @p sleep
-   * function will be called. There
-   * is a default implementation
-   * doing plain nothing since some
-   * problems may not need doing a
-   * postprocess step, e.g. if everything
-   * was already done when solving the
-   * primal problem. However, it
-   * will abort the program when
-   * being called anyway, since then you
-   * should really overload the function.
+   * This function is called by the manager object when postprocessing this
+   * time level is needed. It is called after the @p wake_up function was
+   * called and before the @p sleep function will be called. There is a
+   * default implementation doing plain nothing since some problems may not
+   * need doing a postprocess step, e.g. if everything was already done when
+   * solving the primal problem. However, it will abort the program when being
+   * called anyway, since then you should really overload the function.
    */
   virtual void postprocess_timestep ();
 
   /**
-   * Return the time value of this time
-   * step.
+   * Return the time value of this time step.
    */
   double get_time () const;
 
   /**
-   * Return the number of this time
-   * step. Note that this number may vary
-   * between different sweeps, if timesteps
-   * are added or deleted.
+   * Return the number of this time step. Note that this number may vary
+   * between different sweeps, if timesteps are added or deleted.
    */
   unsigned int get_timestep_no () const;
 
   /**
-   * Compute the time difference to the
-   * last time step. If this timestep is
-   * the first one, this function will
-   * result in an exception. Though this
-   * behaviour seems a bit drastic, it
-   * is appropriate in most cases since
-   * if there is no previous time step
-   * you will need special treatment
-   * anyway and this way no invalid
-   * value is returned which could lead
-   * to wrong but unnoticed results of
-   * your computation. (The only sensible
-   * value to return in that case would
-   * not be zero, since valid computation
-   * can be done with that, but would
-   * be a denormalized value such as @p NaN.
-   * However, there is not much difference
-   * in finding that the results of a
-   * computation are all denormalized values
-   * or in getting an exception; in the
-   * latter case you at least get the exact
-   * place where your problem lies.)
+   * Compute the time difference to the last time step. If this timestep is
+   * the first one, this function will result in an exception. Though this
+   * behaviour seems a bit drastic, it is appropriate in most cases since if
+   * there is no previous time step you will need special treatment anyway and
+   * this way no invalid value is returned which could lead to wrong but
+   * unnoticed results of your computation. (The only sensible value to return
+   * in that case would not be zero, since valid computation can be done with
+   * that, but would be a denormalized value such as @p NaN. However, there is
+   * not much difference in finding that the results of a computation are all
+   * denormalized values or in getting an exception; in the latter case you at
+   * least get the exact place where your problem lies.)
    */
   double get_backward_timestep () const;
 
   /**
-   * Return the time difference to the next
-   * time step. With regard to the case
-   * that there is no next time step,
-   * the same applies as for the function
+   * Return the time difference to the next time step. With regard to the case
+   * that there is no next time step, the same applies as for the function
    * above.
    */
   double get_forward_timestep () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * You will want to overload
-   * this function in derived
-   * classes to compute the
-   * amount memory used by the
-   * derived class, and add the
-   * result of this function to
-   * your result.
+   * You will want to overload this function in derived classes to compute the
+   * amount memory used by the derived class, and add the result of this
+   * function to your result.
    */
   virtual std::size_t memory_consumption () const;
 
@@ -1012,32 +815,25 @@ public:
 
 protected:
   /**
-   * Pointer to the previous time step object
-   * in the list.
+   * Pointer to the previous time step object in the list.
    */
   const TimeStepBase *previous_timestep;
 
   /**
-   * Pointer to the next time step object
-   * in the list.
+   * Pointer to the next time step object in the list.
    */
   const TimeStepBase *next_timestep;
 
   /**
-   * Number of the sweep we are presently
-   * in. This number is reset by the time
-   * level manager before a sweep is
-   * started.
+   * Number of the sweep we are presently in. This number is reset by the time
+   * level manager before a sweep is started.
    */
   unsigned int sweep_no;
 
   /**
-   * Number of the time step, counted from
-   * zero onwards. This number is reset at
-   * the start of each sweep by the time
-   * level manager, since some time steps
-   * may have been inserted or deleted
-   * after the previous sweep.
+   * Number of the time step, counted from zero onwards. This number is reset
+   * at the start of each sweep by the time level manager, since some time
+   * steps may have been inserted or deleted after the previous sweep.
    */
   unsigned int timestep_no;
 
@@ -1047,80 +843,59 @@ protected:
   const double time;
 
   /**
-   * Variable storing whether the
-   * solution of a primal or a dual
-   * problem is actual, or any of
-   * the other actions
-   * specified. This variable is
-   * set by the <tt>init_for_*</tt>
-   * functions.
+   * Variable storing whether the solution of a primal or a dual problem is
+   * actual, or any of the other actions specified. This variable is set by
+   * the <tt>init_for_*</tt> functions.
    */
   unsigned int next_action;
 
 private:
   /**
-   * Reset the pointer to the previous time
-   * step; shall only be called by the
+   * Reset the pointer to the previous time step; shall only be called by the
    * time level manager object.
    *
-   * This function is called at the set-up
-   * of the manager object and whenever
+   * This function is called at the set-up of the manager object and whenever
    * a timestep is inserted or deleted.
    */
   void set_previous_timestep (const TimeStepBase *previous);
 
   /**
-   * Reset the pointer to the next time
-   * step; shall only be called by the
-   * time level manager object.
+   * Reset the pointer to the next time step; shall only be called by the time
+   * level manager object.
    *
-   * This function is called at the set-up
-   * of the manager object and whenever
+   * This function is called at the set-up of the manager object and whenever
    * a timestep is inserted or deleted.
    */
   void set_next_timestep (const TimeStepBase *next);
 
   /**
-   * Set the number this time step
-   * has in the list of timesteps.
-   * This function is called by the
-   * time step management object at
-   * the beginning of each sweep, to
-   * update information which may have
-   * changed due to addition or deleltion
-   * of time levels.
+   * Set the number this time step has in the list of timesteps. This function
+   * is called by the time step management object at the beginning of each
+   * sweep, to update information which may have changed due to addition or
+   * deleltion of time levels.
    */
   void set_timestep_no (const unsigned int step_no);
 
   /**
-   * Set the number of the sweep we are
-   * presently in. This function is
-   * called by the time level management
-   * object at start-up time of each
-   * sweep.
+   * Set the number of the sweep we are presently in. This function is called
+   * by the time level management object at start-up time of each sweep.
    */
   void set_sweep_no (const unsigned int sweep_no);
 
 
   /**
-   * Copy constructor. I can see no reason
-   * why someone might want to use it, so
-   * I don't provide it. Since this class
-   * has pointer members, making it private
-   * prevents the compiler to provide it's
-   * own, incorrect one if anyone chose to
-   * copy such an object.
+   * Copy constructor. I can see no reason why someone might want to use it,
+   * so I don't provide it. Since this class has pointer members, making it
+   * private prevents the compiler to provide it's own, incorrect one if
+   * anyone chose to copy such an object.
    */
   TimeStepBase (const TimeStepBase &);
 
   /**
-   * Copy operator. I can see no reason
-   * why someone might want to use it, so
-   * I don't provide it. Since this class
-   * has pointer members, making it private
-   * prevents the compiler to provide it's
-   * own, incorrect one if anyone chose to
-   * copy such an object.
+   * Copy operator. I can see no reason why someone might want to use it, so I
+   * don't provide it. Since this class has pointer members, making it private
+   * prevents the compiler to provide it's own, incorrect one if anyone chose
+   * to copy such an object.
    */
   TimeStepBase &operator = (const TimeStepBase &);
 
@@ -1132,18 +907,18 @@ private:
 
 
 /**
- * Namespace in which some classes are declared that encapsulate flags
- * for the TimeStepBase_Tria() class. These used to be local data
- * types of that class, but some compilers choked on some aspects, so
- * we put them into a namespace of their own.
+ * Namespace in which some classes are declared that encapsulate flags for the
+ * TimeStepBase_Tria() class. These used to be local data types of that class,
+ * but some compilers choked on some aspects, so we put them into a namespace
+ * of their own.
  *
  * @author Wolfgang Bangerth, 2001
  */
 namespace TimeStepBase_Tria_Flags
 {
   /**
-   * This structure is used to tell the TimeStepBase_Tria() class how grids should
-   * be handled. It has flags defining the moments where grids shall be
+   * This structure is used to tell the TimeStepBase_Tria() class how grids
+   * should be handled. It has flags defining the moments where grids shall be
    * re-made and when they may be deleted. Also, one variable states whether
    * grids should be kept in memory or should be deleted between to uses to
    * save memory.
@@ -1152,69 +927,43 @@ namespace TimeStepBase_Tria_Flags
   struct Flags
   {
     /**
-     * Default constructor; yields
-     * an exception, so is not
-     * really usable.
+     * Default constructor; yields an exception, so is not really usable.
      */
     Flags ();
 
     /**
-     * Constructor; see the different
-     * fields for a description of the
-     * meaning of the parameters.
+     * Constructor; see the different fields for a description of the meaning
+     * of the parameters.
      */
     Flags (const bool         delete_and_rebuild_tria,
            const unsigned int wakeup_level_to_build_grid,
            const unsigned int sleep_level_to_delete_grid);
 
     /**
-     * This flag determines whether
-     * the @p sleep and
-     * @p wake_up functions shall
-     * delete and rebuild the
-     * triangulation.  While for
-     * small problems, this is not
-     * necessary, for large
-     * problems it is indispensable
-     * to save memory.  The reason
-     * for this is that there may
-     * be several hundred time
-     * levels in memory, each with
-     * its own triangulation, which
-     * may require large amounts if
-     * there are many cells on
-     * each. Having a total of
-     * 100.000.000 cells on all
-     * time levels taken together
-     * is not uncommon, which makes
-     * this flag understandable.
+     * This flag determines whether the @p sleep and @p wake_up functions
+     * shall delete and rebuild the triangulation.  While for small problems,
+     * this is not necessary, for large problems it is indispensable to save
+     * memory.  The reason for this is that there may be several hundred time
+     * levels in memory, each with its own triangulation, which may require
+     * large amounts if there are many cells on each. Having a total of
+     * 100.000.000 cells on all time levels taken together is not uncommon,
+     * which makes this flag understandable.
      */
     const bool delete_and_rebuild_tria;
 
     /**
-     * This number denotes the
-     * parameter to the @p wake_up
-     * function at which it shall
-     * rebuild the grid. Obviously,
-     * it shall be less than or
-     * equal to the @p look_ahead
-     * number passed to the time
-     * step management object; if
-     * it is equal, then the grid
-     * is rebuilt the first time
-     * the @p wake_up function is
-     * called. If
-     * @p delete_and_rebuild_tria
-     * is @p false, this number
-     * has no meaning.
+     * This number denotes the parameter to the @p wake_up function at which
+     * it shall rebuild the grid. Obviously, it shall be less than or equal to
+     * the @p look_ahead number passed to the time step management object; if
+     * it is equal, then the grid is rebuilt the first time the @p wake_up
+     * function is called. If @p delete_and_rebuild_tria is @p false, this
+     * number has no meaning.
      */
     const unsigned int wakeup_level_to_build_grid;
 
     /**
-     * This is the opposite flag to
-     * the one above: it determines
-     * at which call to * @p sleep
-     * the grid shall be deleted.
+     * This is the opposite flag to the one above: it determines at which call
+     * to * @p sleep the grid shall be deleted.
      */
     const unsigned int sleep_level_to_delete_grid;
 
@@ -1229,149 +978,142 @@ namespace TimeStepBase_Tria_Flags
 
 
   /**
-   * This structure is used to tell the TimeStepBase_Tria() class how grids should
-   * be refined. Before we explain all the different variables, fist some terminology:
+   * This structure is used to tell the TimeStepBase_Tria() class how grids
+   * should be refined. Before we explain all the different variables, fist
+   * some terminology:
    * <ul>
    * <li> Correction: after having flagged some cells of the triangulation for
-   *   following some given criterion, we may want to change the number of flagged
-   *   cells on this grid according to another criterion that the number of cells
-   *   may be only a certain fraction more or less then the number of cells on
-   *   the previous grid. This change of refinement flags will be called
-   *   "correction" in the sequel.
-   * <li> Adaption: in order to make the change between one grid and the next not
-   *   to large, we may want to flag some additional cells on one of the two
-   *   grids such that there are not too grave differences. This process will
-   *   be called "adaption".
+   * following some given criterion, we may want to change the number of
+   * flagged cells on this grid according to another criterion that the number
+   * of cells may be only a certain fraction more or less then the number of
+   * cells on the previous grid. This change of refinement flags will be
+   * called "correction" in the sequel.
+   * <li> Adaption: in order to make the change between one grid and the next
+   * not to large, we may want to flag some additional cells on one of the two
+   * grids such that there are not too grave differences. This process will be
+   * called "adaption".
    * </ul>
    *
    *
    * <h3>Description of flags</h3>
    *
    * <ul>
-   * <li> @p max_refinement_level: Cut the refinement of cells at a given level.
-   *   This flag does not influence the flagging of cells, so not more cells
-   *   on the coarser levels are flagged than usual. Rather, the flags are all
-   *   set, but when it comes to the actual refinement, the maximum refinement
-   *   level is truncated.
+   * <li> @p max_refinement_level: Cut the refinement of cells at a given
+   * level. This flag does not influence the flagging of cells, so not more
+   * cells on the coarser levels are flagged than usual. Rather, the flags are
+   * all set, but when it comes to the actual refinement, the maximum
+   * refinement level is truncated.
    *
-   *   This option is only really useful when you want to compare global
-   *   refinement with adaptive refinement when you don't want the latter
-   *   to refine more than the global refinement.
+   * This option is only really useful when you want to compare global
+   * refinement with adaptive refinement when you don't want the latter to
+   * refine more than the global refinement.
    *
-   * <li> @p first_sweep_with_correction: When using cell number correction
-   *   as defined above, it may be worth while to start with this only in
-   *   later sweeps, not already in the first one. If this variable is
-   *   zero, then start with the first sweep, else with a higher one. The
-   *   rationale for only starting later is that we do not want to block the
-   *   development of grids at the beginning and only impose restrictions in
-   *   the sweeps where we start to be interested in the actual results of
-   *   the computations.
+   * <li> @p first_sweep_with_correction: When using cell number correction as
+   * defined above, it may be worth while to start with this only in later
+   * sweeps, not already in the first one. If this variable is zero, then
+   * start with the first sweep, else with a higher one. The rationale for
+   * only starting later is that we do not want to block the development of
+   * grids at the beginning and only impose restrictions in the sweeps where
+   * we start to be interested in the actual results of the computations.
    *
-   * <li> @p min_cells_for_correction: If we want a more free process of
-   *   grid development, we may want to impose less rules for grids with few
-   *   cells also. This variable sets a lower bound for the cell number of
-   *   grids where corrections are to be performed.
+   * <li> @p min_cells_for_correction: If we want a more free process of grid
+   * development, we may want to impose less rules for grids with few cells
+   * also. This variable sets a lower bound for the cell number of grids where
+   * corrections are to be performed.
    *
    * <li> @p cell_number_corridor_top: Fraction of the number of cells by
-   *   which the number of cells of one grid may be higher than that on the
-   *   previous grid. Common values are 10 per cent (i.e. 0.1). The naming
-   *   of the variable results from the goal to define a target corridor
-   *   for the number of cells after refinement has taken place.
+   * which the number of cells of one grid may be higher than that on the
+   * previous grid. Common values are 10 per cent (i.e. 0.1). The naming of
+   * the variable results from the goal to define a target corridor for the
+   * number of cells after refinement has taken place.
    *
    * <li> @p cell_number_corridor_bottom: Fraction of the number of cells by
-   *   which the number of cells of one grid may be lower than that on the
-   *   previous grid. Common values are 5 per cent (i.e. 0.05). Usually this
-   *   number will be smaller than @p cell_number_corridor_top since an
-   *   increase of the number of cells is not harmful (though it increases
-   *   the numerical amount of work needed to solve the problem) while a
-   *   sharp decrease may reduce the accuracy of the final result even if
-   *   the time steps computed before the decrease were computed to high
-   *   accuracy.
+   * which the number of cells of one grid may be lower than that on the
+   * previous grid. Common values are 5 per cent (i.e. 0.05). Usually this
+   * number will be smaller than @p cell_number_corridor_top since an increase
+   * of the number of cells is not harmful (though it increases the numerical
+   * amount of work needed to solve the problem) while a sharp decrease may
+   * reduce the accuracy of the final result even if the time steps computed
+   * before the decrease were computed to high accuracy.
    *
-   *   Note however, that if you compute the dual problem as well, then the time
-   *   direction is reversed, so the two values defining the cell number
-   *   corridor should be about equal.
+   * Note however, that if you compute the dual problem as well, then the time
+   * direction is reversed, so the two values defining the cell number
+   * corridor should be about equal.
    *
-   * <li> @p correction_relaxations: This is a list of pairs of number with the
-   *   following meaning: just as for @p min_cells_for_correction, it may be
-   *   worth while to reduce the requirements upon grids if the have few cells.
-   *   The present variable stores a list of cell numbers along with some values
-   *   which tell us that the cell number corridor should be enlarged by a
-   *   certain factor. For example, if this list was <tt>((100 5) (200 3) (500 2))</tt>,
-   *   this would mean that for grids with a cell number below 100, the
-   *   <tt>cell_number_corridor_*</tt> variables are to be multiplied by 5 before they
-   *   are applied, for cell numbers below 200 they are to be multiplied by 3,
-   *   and so on.
+   * <li> @p correction_relaxations: This is a list of pairs of number with
+   * the following meaning: just as for @p min_cells_for_correction, it may be
+   * worth while to reduce the requirements upon grids if the have few cells.
+   * The present variable stores a list of cell numbers along with some values
+   * which tell us that the cell number corridor should be enlarged by a
+   * certain factor. For example, if this list was <tt>((100 5) (200 3) (500
+   * 2))</tt>, this would mean that for grids with a cell number below 100,
+   * the <tt>cell_number_corridor_*</tt> variables are to be multiplied by 5
+   * before they are applied, for cell numbers below 200 they are to be
+   * multiplied by 3, and so on.
    *
-   *   @p correction_relaxations is actually a vector of such list. Each entry
-   *   in this vector denotes the relaxation rules for one sweep. The last
-   *   entry defines the relaxation rules for all following sweeps. This
-   *   scheme is adopted to allow for stricter corrections in later sweeps
-   *   while the relaxations may be more generous in the first sweeps.
+   * @p correction_relaxations is actually a vector of such list. Each entry
+   * in this vector denotes the relaxation rules for one sweep. The last entry
+   * defines the relaxation rules for all following sweeps. This scheme is
+   * adopted to allow for stricter corrections in later sweeps while the
+   * relaxations may be more generous in the first sweeps.
    *
-   *   There is a static variable @p default_correction_relaxations which you
-   *   can use as a default value. It is an empty list and thus defines no
-   *   relaxations.
+   * There is a static variable @p default_correction_relaxations which you
+   * can use as a default value. It is an empty list and thus defines no
+   * relaxations.
    *
    * <li> @p cell_number_correction_steps: Usually, if you want the number of
-   *   cells to be corrected, the target corridor for the cell number is computed
-   *   and some additional cells are flagged or flags are removed. But since
-   *   the cell number resulting after flagging and deflagging can not be
-   *   easily computed, it will usually not be within the corridor. We therefore
-   *   need to iteratively get to our goal. Usually, three or four iterations are
-   *   needed, but using this variable, you can reduce the allowed number of
-   *   iterations; breaking the loop after two iterations yields good results
-   *   regularly. Setting the variable to zero will result in no correction
-   *   steps at all.
+   * cells to be corrected, the target corridor for the cell number is
+   * computed and some additional cells are flagged or flags are removed. But
+   * since the cell number resulting after flagging and deflagging can not be
+   * easily computed, it will usually not be within the corridor. We therefore
+   * need to iteratively get to our goal. Usually, three or four iterations
+   * are needed, but using this variable, you can reduce the allowed number of
+   * iterations; breaking the loop after two iterations yields good results
+   * regularly. Setting the variable to zero will result in no correction
+   * steps at all.
    *
    * <li> @p mirror_flags_to_previous_grid: If a cell on the present grid is
-   *   flagged for refinement, also flag the corresponding cell on the previous
-   *   grid. This is useful if, for example, error indicators are computed for
-   *   space-time cells, but are stored for the second grid only. Now, since the
-   *   first grid has the same contributions to the indicators as the second, it
-   *   may be useful to flag both if necessary. This is done if the present
-   *   variable is set.
+   * flagged for refinement, also flag the corresponding cell on the previous
+   * grid. This is useful if, for example, error indicators are computed for
+   * space-time cells, but are stored for the second grid only. Now, since the
+   * first grid has the same contributions to the indicators as the second, it
+   * may be useful to flag both if necessary. This is done if the present
+   * variable is set.
    *
-   * <li> @p adapt_grids: adapt the present grid to the previous one in the sense
-   *   defined above. What is actually done here is the following: if going from
-   *   the previous to the present grid would result in double refinement or
-   *   double coarsening of some cells, then we try to flag these cells for
-   *   refinement or coarsening such as to avoid the double step. Obviously, more
-   *   than double refinement of coarsening is also caught.
+   * <li> @p adapt_grids: adapt the present grid to the previous one in the
+   * sense defined above. What is actually done here is the following: if
+   * going from the previous to the present grid would result in double
+   * refinement or double coarsening of some cells, then we try to flag these
+   * cells for refinement or coarsening such as to avoid the double step.
+   * Obviously, more than double refinement of coarsening is also caught.
    *
-   *   Grid adaption can try to avoid such changes between two grids, but it can
-   *   never promise that they don't occur. This is because the next grid may
-   *   change the present one, but then again there may be jumps in refinement
-   *   level between the present and the previous one; this could only be avoided
-   *   by looping iteratively through all grids, back and forth, until nothing
-   *   changes anymore, which is obviously impossible if there are many time steps
-   *   with very large grids.
+   * Grid adaption can try to avoid such changes between two grids, but it can
+   * never promise that they don't occur. This is because the next grid may
+   * change the present one, but then again there may be jumps in refinement
+   * level between the present and the previous one; this could only be
+   * avoided by looping iteratively through all grids, back and forth, until
+   * nothing changes anymore, which is obviously impossible if there are many
+   * time steps with very large grids.
    * </ul>
    */
   template <int dim>
   struct RefinementFlags
   {
     /**
-     * Typedef of a data type
-     * describing some relaxations
-     * of the correction process.
-     * See the general description
-     * of this class for more
+     * Typedef of a data type describing some relaxations of the correction
+     * process. See the general description of this class for more
      * information.
      */
     typedef std::vector<std::vector<std::pair<unsigned int, double> > >   CorrectionRelaxations;
 
     /**
-     * Default values for the relaxations:
-     * no relaxations.
+     * Default values for the relaxations: no relaxations.
      */
     static CorrectionRelaxations default_correction_relaxations;
 
     /**
-     * Constructor. The default
-     * values are chosen such that
-     * almost no restriction on the
-     * mesh refinement is imposed.
+     * Constructor. The default values are chosen such that almost no
+     * restriction on the mesh refinement is imposed.
      */
     RefinementFlags (const unsigned int max_refinement_level         = 0,
                      const unsigned int first_sweep_with_correction  = 0,
@@ -1384,50 +1126,33 @@ namespace TimeStepBase_Tria_Flags
                      const bool adapt_grids                          = false);
 
     /**
-     * Maximum level of a cell in
-     * the triangulation of a time
-     * level. If it is set to zero,
-     * then no limit is imposed on
-     * the number of refinements a
-     * coarse grid cell may
-     * undergo. Usually, this field
-     * is used, if for some reason
-     * you want to limit refinement
-     * in an adaptive process, for
-     * example to avoid overly
-     * large numbers of cells or to
-     * compare with grids which
-     * have a certain number of
-     * refinements.
+     * Maximum level of a cell in the triangulation of a time level. If it is
+     * set to zero, then no limit is imposed on the number of refinements a
+     * coarse grid cell may undergo. Usually, this field is used, if for some
+     * reason you want to limit refinement in an adaptive process, for example
+     * to avoid overly large numbers of cells or to compare with grids which
+     * have a certain number of refinements.
      */
     const unsigned int  max_refinement_level;
 
     /**
-     * First sweep to perform cell
-     * number correction steps on;
-     * for sweeps before, cells are
-     * only flagged and no
-     * number-correction to
-     * previous grids is performed.
+     * First sweep to perform cell number correction steps on; for sweeps
+     * before, cells are only flagged and no number-correction to previous
+     * grids is performed.
      */
     const unsigned int  first_sweep_with_correction;
 
 
     /**
-     * Apply cell number correction
-     * with the previous time level
-     * only if there are more than
-     * this number of cells.
+     * Apply cell number correction with the previous time level only if there
+     * are more than this number of cells.
      */
     const unsigned int  min_cells_for_correction;
 
     /**
-     * Fraction by which the number
-     * of cells on a time level may
-     * differ from the number on
-     * the previous time level
-     * (first: top deviation,
-     * second: bottom deviation).
+     * Fraction by which the number of cells on a time level may differ from
+     * the number on the previous time level (first: top deviation, second:
+     * bottom deviation).
      */
     const double        cell_number_corridor_top;
 
@@ -1437,59 +1162,37 @@ namespace TimeStepBase_Tria_Flags
     const double        cell_number_corridor_bottom;
 
     /**
-     * List of relaxations to the
-     * correction step.
+     * List of relaxations to the correction step.
      */
     const std::vector<std::vector<std::pair<unsigned int,double> > > correction_relaxations;
 
     /**
-     * Number of iterations to be
-     * performed to adjust the
-     * number of cells on a time
-     * level to those on the
-     * previous one. Zero means: do
-     * no such iteration.
+     * Number of iterations to be performed to adjust the number of cells on a
+     * time level to those on the previous one. Zero means: do no such
+     * iteration.
      */
     const unsigned int  cell_number_correction_steps;
 
     /**
-     * Flag all cells which are
-     * flagged on this timestep for
-     * refinement on the previous
-     * one also. This is useful in
-     * case the error indicator was
-     * computed by integration over
-     * time-space cells, but are
-     * now associated to a grid on
-     * a discrete time level. Since
-     * the error contribution comes
-     * from both grids, however, it
-     * is appropriate to refine
-     * both grids.
+     * Flag all cells which are flagged on this timestep for refinement on the
+     * previous one also. This is useful in case the error indicator was
+     * computed by integration over time-space cells, but are now associated
+     * to a grid on a discrete time level. Since the error contribution comes
+     * from both grids, however, it is appropriate to refine both grids.
      *
-     * Since the previous grid does
-     * not mirror the flags to the
-     * one before it, this does not
-     * lead to an almost infinite
-     * growth of cell numbers. You
-     * should use this flag with
-     * cell number correction
-     * switched on only, however.
+     * Since the previous grid does not mirror the flags to the one before it,
+     * this does not lead to an almost infinite growth of cell numbers. You
+     * should use this flag with cell number correction switched on only,
+     * however.
      *
-     * Mirroring is done after cell
-     * number correction is done,
-     * but before grid adaption, so
-     * the cell number on this grid
-     * is not noticeably influenced
-     * by the cells flagged
-     * additionally on the previous
-     * grid.
+     * Mirroring is done after cell number correction is done, but before grid
+     * adaption, so the cell number on this grid is not noticeably influenced
+     * by the cells flagged additionally on the previous grid.
      */
     const bool          mirror_flags_to_previous_grid;
 
     /**
-     * Adapt this grid to the
-     * previous one.
+     * Adapt this grid to the previous one.
      */
     const bool          adapt_grids;
 
@@ -1506,8 +1209,8 @@ namespace TimeStepBase_Tria_Flags
   /**
    * Structure given to the actual refinement function, telling it which
    * thresholds to take for coarsening and refinement. The actual refinement
-   * criteria are loaded by calling the virtual function
-   * @p get_tria_refinement_criteria.
+   * criteria are loaded by calling the virtual function @p
+   * get_tria_refinement_criteria.
    */
   template <int dim>
   struct RefinementData
@@ -1519,22 +1222,15 @@ namespace TimeStepBase_Tria_Flags
                     const double         coarsening_threshold=0);
 
     /**
-     * Threshold for refinement:
-     * cells having a larger value
-     * will be refined (at least in
-     * the first round; subsequent
-     * steps of the refinement
-     * process may flag other cells
-     * as well or remove the flag
-     * from cells with a criterion
-     * higher than this threshold).
+     * Threshold for refinement: cells having a larger value will be refined
+     * (at least in the first round; subsequent steps of the refinement
+     * process may flag other cells as well or remove the flag from cells with
+     * a criterion higher than this threshold).
      */
     const double         refinement_threshold;
 
     /**
-     * Same threshold for
-     * coarsening: cells with a
-     * smaller threshold will be
+     * Same threshold for coarsening: cells with a smaller threshold will be
      * coarsened if possible.
      */
     const double         coarsening_threshold;
@@ -1552,30 +1248,31 @@ namespace TimeStepBase_Tria_Flags
 
 
 /**
- * Specialisation of TimeStepBase which addresses some aspects of grid handling.
- * In particular, this class is thought to make handling of grids available that
- * are adaptively refined on each time step separately or with a loose coupling
- * between time steps. It also takes care of deleting and rebuilding grids when
- * memory resources are a point, through the @p sleep and @p wake_up functions
- * declared in the base class.
+ * Specialisation of TimeStepBase which addresses some aspects of grid
+ * handling. In particular, this class is thought to make handling of grids
+ * available that are adaptively refined on each time step separately or with
+ * a loose coupling between time steps. It also takes care of deleting and
+ * rebuilding grids when memory resources are a point, through the @p sleep
+ * and @p wake_up functions declared in the base class.
  *
- * In addition to that, it offers functions which do some rather hairy refinement
- * rules for time dependent problems, trying to avoid too much change in the grids
- * between subsequent time levels, while also trying to retain the freedom of
- * refining each grid separately. There are lots of flags and numbers controlling
- * this function, which might drastically change the behaviour of the function -- see
- * the description of the flags for further information.
+ * In addition to that, it offers functions which do some rather hairy
+ * refinement rules for time dependent problems, trying to avoid too much
+ * change in the grids between subsequent time levels, while also trying to
+ * retain the freedom of refining each grid separately. There are lots of
+ * flags and numbers controlling this function, which might drastically change
+ * the behaviour of the function -- see the description of the flags for
+ * further information.
  *
- * @author Wolfgang Bangerth, 1999; large parts taken from the wave program, by Wolfgang Bangerth 1998
+ * @author Wolfgang Bangerth, 1999; large parts taken from the wave program,
+ * by Wolfgang Bangerth 1998
  */
 template <int dim>
 class TimeStepBase_Tria : public TimeStepBase
 {
 public:
   /**
-   * Typedef the data types of the
-   * TimeStepBase_Tria_Flags()
-   * namespace into local scope.
+   * Typedef the data types of the TimeStepBase_Tria_Flags() namespace into
+   * local scope.
    */
   typedef typename TimeStepBase_Tria_Flags::Flags<dim>           Flags;
   typedef typename TimeStepBase_Tria_Flags::RefinementFlags<dim> RefinementFlags;
@@ -1583,8 +1280,7 @@ public:
 
 
   /**
-   * Extension of the enum in the base
-   * class denoting the next action to be
+   * Extension of the enum in the base class denoting the next action to be
    * done.
    */
   enum SolutionState
@@ -1594,41 +1290,26 @@ public:
 
 
   /**
-   * Default constructor. Does nothing but
-   * throws an exception. We need to have
-   * such a constructor in order to satisfy
-   * the needs of derived classes, which
-   * take this class as a virtual base class
-   * and don't need to call this constructor
-   * of they are not terminal classes. The
-   * compiler would like to know a
-   * constructor to call anyway since it
-   * can't know that the class is not
-   * terminal.
+   * Default constructor. Does nothing but throws an exception. We need to
+   * have such a constructor in order to satisfy the needs of derived classes,
+   * which take this class as a virtual base class and don't need to call this
+   * constructor of they are not terminal classes. The compiler would like to
+   * know a constructor to call anyway since it can't know that the class is
+   * not terminal.
    */
   TimeStepBase_Tria ();
 
   /**
-   * Constructor. Takes a coarse
-   * grid from which the grids on this
-   * time level will be derived and
-   * some flags steering the behaviour
-   * of this object.
+   * Constructor. Takes a coarse grid from which the grids on this time level
+   * will be derived and some flags steering the behaviour of this object.
    *
-   * The ownership of the coarse grid
-   * stays with the creator of this
-   * object. However, it is locked
-   * from destruction to guarantee
-   * the lifetime of the coarse grid
-   * is longer than it is needed by
-   * this object.
+   * The ownership of the coarse grid stays with the creator of this object.
+   * However, it is locked from destruction to guarantee the lifetime of the
+   * coarse grid is longer than it is needed by this object.
    *
-   * You need to give the general flags
-   * structure to this function since it
-   * is needed anyway; the refinement
-   * flags can be omitted if you do
-   * not intend to call the refinement
-   * function of this class.
+   * You need to give the general flags structure to this function since it is
+   * needed anyway; the refinement flags can be omitted if you do not intend
+   * to call the refinement function of this class.
    */
   TimeStepBase_Tria (const double              time,
                      const Triangulation<dim, dim> &coarse_grid,
@@ -1636,144 +1317,93 @@ public:
                      const RefinementFlags    &refinement_flags = RefinementFlags());
 
   /**
-   * Destructor. At present, this does
-   * not more than releasing the lock on
-   * the coarse grid triangulation given
-   * to the constructor.
+   * Destructor. At present, this does not more than releasing the lock on the
+   * coarse grid triangulation given to the constructor.
    */
   virtual ~TimeStepBase_Tria ();
 
   /**
-   * Reconstruct all the data that is
-   * needed for this time level to work.
-   * This function serves to reget all
-   * the variables and data structures
-   * to work again after they have been
-   * send to sleep some time before, or
-   * at the first time we visit this time
-   * level. In particular, it is used
-   * to reconstruct the triangulation,
-   * degree of freedom handlers, to reload
-   * data vectors in case they have been
-   * stored to disk, etc. By default,
-   * this function rebuilds the triangulation
-   * if the respective flag has been set to
-   * destroy it in the @p sleep function.
-   * It does so also the first time we
-   * hit this function and @p wakeup_level
-   * equals <tt>flags.wakeup_level_to_build_grid</tt>,
-   * independently of the value of the
-   * mentioned flag. (Actually, it does so
-   * whenever the triangulation pointer
-   * equals the Null pointer and the
-   * value of @p wakeup_level is right.)
+   * Reconstruct all the data that is needed for this time level to work. This
+   * function serves to reget all the variables and data structures to work
+   * again after they have been send to sleep some time before, or at the
+   * first time we visit this time level. In particular, it is used to
+   * reconstruct the triangulation, degree of freedom handlers, to reload data
+   * vectors in case they have been stored to disk, etc. By default, this
+   * function rebuilds the triangulation if the respective flag has been set
+   * to destroy it in the @p sleep function. It does so also the first time we
+   * hit this function and @p wakeup_level equals
+   * <tt>flags.wakeup_level_to_build_grid</tt>, independently of the value of
+   * the mentioned flag. (Actually, it does so whenever the triangulation
+   * pointer equals the Null pointer and the value of @p wakeup_level is
+   * right.)
    *
-   * Since this is an important task, you
-   * should call this function from your
-   * own function, should you choose to
-   * overload it in your own class (which
-   * likely is the case), preferably at
-   * the beginning so that your function
-   * can take effect of the triangulation
-   * already existing.
+   * Since this is an important task, you should call this function from your
+   * own function, should you choose to overload it in your own class (which
+   * likely is the case), preferably at the beginning so that your function
+   * can take effect of the triangulation already existing.
    */
   virtual void wake_up (const unsigned int wakeup_level);
 
   /**
-   * This is the opposite function
-   * to @p wake_up. It is used to
-   * delete data or save it to disk
-   * after they are no more needed
-   * for the present sweep. Typical
-   * kinds of data for this are
-   * data vectors, degree of
-   * freedom handlers,
-   * triangulation objects,
-   * etc. which occupy large
-   * amounts of memory and may
-   * therefore be externalized.
+   * This is the opposite function to @p wake_up. It is used to delete data or
+   * save it to disk after they are no more needed for the present sweep.
+   * Typical kinds of data for this are data vectors, degree of freedom
+   * handlers, triangulation objects, etc. which occupy large amounts of
+   * memory and may therefore be externalized.
    *
-   * By default, if the user specified so
-   * in the flags for this object, the
-   * triangulation is deleted and the
-   * refinement history saved such that
-   * the respective @p wake_up function can
-   * rebuild it. You should therefore call
-   * this function from your overloaded
-   * version, preferably at the end so
-   * that your function can use the
-   * triangulation as long as ou need it.
+   * By default, if the user specified so in the flags for this object, the
+   * triangulation is deleted and the refinement history saved such that the
+   * respective @p wake_up function can rebuild it. You should therefore call
+   * this function from your overloaded version, preferably at the end so that
+   * your function can use the triangulation as long as ou need it.
    */
   virtual void sleep (const unsigned int);
 
   /**
-   * Do the refinement according to the
-   * flags passed to the constructor of this
-   * object and the data passed to this
-   * function. For a description of the
-   * working of this function refer to the
-   * general documentation of this class.
+   * Do the refinement according to the flags passed to the constructor of
+   * this object and the data passed to this function. For a description of
+   * the working of this function refer to the general documentation of this
+   * class.
    *
-   * In fact, this function does not
-   * actually refine or coarsen the
-   * triangulation, but only sets the
-   * respective flags. This is done because
-   * usually you will not need the grid
-   * immediately afterwards but only
-   * in the next sweep, so it suffices
-   * to store the flags and rebuild it
-   * the next time we need it. Also, it
-   * may be that the next time step
-   * would like to add or delete some
-   * flags, so we have to wait anyway
-   * with the use of this grid.
+   * In fact, this function does not actually refine or coarsen the
+   * triangulation, but only sets the respective flags. This is done because
+   * usually you will not need the grid immediately afterwards but only in the
+   * next sweep, so it suffices to store the flags and rebuild it the next
+   * time we need it. Also, it may be that the next time step would like to
+   * add or delete some flags, so we have to wait anyway with the use of this
+   * grid.
    */
   void refine_grid (const RefinementData data);
 
   /**
-   * Respective init function for the
-   * refinement loop; does nothing in
-   * the default implementation, apart from
-   * setting @p next_action to
-   * @p grid_refinement but can
-   * be overloaded.
+   * Respective init function for the refinement loop; does nothing in the
+   * default implementation, apart from setting @p next_action to @p
+   * grid_refinement but can be overloaded.
    */
   virtual void init_for_refinement ();
 
   /**
-   * Virtual function that should fill
-   * the vector with the refinement
-   * criteria for the present triangulation.
-   * It is used within the @p refine_grid
-   * function to get the criteria for
-   * the present time step, since they
-   * can't be passed through its
-   * argument when using the loop of
-   * the time step management object.
+   * Virtual function that should fill the vector with the refinement criteria
+   * for the present triangulation. It is used within the @p refine_grid
+   * function to get the criteria for the present time step, since they can't
+   * be passed through its argument when using the loop of the time step
+   * management object.
    */
   virtual void get_tria_refinement_criteria (Vector<float> &criteria) const = 0;
 
   /**
-   * The refinement
-   * flags of the triangulation are stored
-   * in a local variable thus allowing
-   * a restoration. The coarsening flags
-   * are also stored.
+   * The refinement flags of the triangulation are stored in a local variable
+   * thus allowing a restoration. The coarsening flags are also stored.
    */
   void save_refine_flags ();
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object.
    *
-   * You will want to overload
-   * this function in derived
-   * classes to compute the
-   * amount memory used by the
-   * derived class, and add the
-   * result of this function to
-   * your result.
+   * You will want to overload this function in derived classes to compute the
+   * amount memory used by the derived class, and add the result of this
+   * function to your result.
    */
   virtual std::size_t memory_consumption () const;
 
@@ -1785,55 +1415,38 @@ public:
 protected:
 
   /**
-   * Triangulation used at this
-   * time level. Since this is
-   * something that every time
-   * stepping scheme needs to have,
-   * we can safely put it into the
-   * base class. Note that the
-   * triangulation is frequently
-   * deleted and rebuilt by the
-   * functions @p sleep and
-   * @p wake_up to save memory, if
-   * such a behaviour is specified
-   * in the @p flags structure.
+   * Triangulation used at this time level. Since this is something that every
+   * time stepping scheme needs to have, we can safely put it into the base
+   * class. Note that the triangulation is frequently deleted and rebuilt by
+   * the functions @p sleep and @p wake_up to save memory, if such a behaviour
+   * is specified in the @p flags structure.
    */
   SmartPointer<Triangulation<dim, dim>,TimeStepBase_Tria<dim> > tria;
 
   /**
-   * Pointer to a grid which is to
-   * be used as the coarse grid for
-   * this time level.  This pointer
-   * is set through the
-   * constructor; ownership remains
-   * with the owner of this
-   * management object.
+   * Pointer to a grid which is to be used as the coarse grid for this time
+   * level.  This pointer is set through the constructor; ownership remains
+   * with the owner of this management object.
    */
   SmartPointer<const Triangulation<dim, dim>,TimeStepBase_Tria<dim> > coarse_grid;
 
   /**
-   * Some flags about how this time level
-   * shall behave. See the documentation
-   * of this struct to find out more about
-   * that.
+   * Some flags about how this time level shall behave. See the documentation
+   * of this struct to find out more about that.
    */
   const Flags flags;
 
   /**
-   * Flags controlling the refinement
-   * process; see the documentation of the
-   * respective structure for more
-   * information.
+   * Flags controlling the refinement process; see the documentation of the
+   * respective structure for more information.
    */
   const RefinementFlags refinement_flags;
 
 private:
   /**
-   * Vectors holding the refinement and
-   * coarsening flags of the different
-   * sweeps on this time level. The
-   * vectors therefore hold the history
-   * of the grid.
+   * Vectors holding the refinement and coarsening flags of the different
+   * sweeps on this time level. The vectors therefore hold the history of the
+   * grid.
    */
   std::vector<std::vector<bool> >   refine_flags;
 
@@ -1843,10 +1456,8 @@ private:
   std::vector<std::vector<bool> >   coarsen_flags;
 
   /**
-   * Restore the grid according to the saved
-   * data. For this, the coarse grid is
-   * copied and the grid is stepwise
-   * rebuilt using the saved flags.
+   * Restore the grid according to the saved data. For this, the coarse grid
+   * is copied and the grid is stepwise rebuilt using the saved flags.
    */
   void restore_grid ();
 };
index feb076e25c1ddf7054e5f3a2ae4252d6a9cf3c98..327ee2f285505497c375e9a92005336a5d01984d 100644 (file)
@@ -1233,9 +1233,7 @@ namespace VectorTools
    * revolves around the question what the normal vector is. Consider the
    * following situation:
    *
-   * <p ALIGN="center">
-   * @image html no_normal_flux_1.png
-   * </p>
+   * <p ALIGN="center"> @image html no_normal_flux_1.png </p>
    *
    * Here, we have two cells that use a bilinear mapping (i.e. MappingQ1).
    * Consequently, for each of the cells, the normal vector is perpendicular
@@ -1262,9 +1260,7 @@ namespace VectorTools
    *
    * Unfortunately, this is not quite enough. Consider the situation here:
    *
-   * <p ALIGN="center">
-   * @image html no_normal_flux_2.png
-   * </p>
+   * <p ALIGN="center"> @image html no_normal_flux_2.png </p>
    *
    * If again the top and right edges approximate a curved boundary, and the
    * left boundary a separate boundary (for example straight) so that the
@@ -1287,9 +1283,7 @@ namespace VectorTools
    * we have considered above, is discretized with the following mesh, then we
    * get into trouble:
    *
-   * <p ALIGN="center">
-   * @image html no_normal_flux_3.png
-   * </p>
+   * <p ALIGN="center"> @image html no_normal_flux_3.png </p>
    *
    * Here, the algorithm assumes that the boundary does not have a corner at
    * the point where faces $F1$ and $F2$ join because at that point there are
@@ -1313,9 +1307,7 @@ namespace VectorTools
    * The situation is more complicated in 3d. Consider the following case
    * where we want to compute the constraints at the marked vertex:
    *
-   * <p ALIGN="center">
-   * @image html no_normal_flux_4.png
-   * </p>
+   * <p ALIGN="center"> @image html no_normal_flux_4.png </p>
    *
    * Here, we get four different normal vectors, one from each of the four
    * faces that meet at the vertex. Even though they may form a complete set
@@ -1354,10 +1346,8 @@ namespace VectorTools
    * on a circle and on a sphere to which the constraints computed by this
    * function have been applied:
    *
-   * <p ALIGN="center">
-   * @image html no_normal_flux_5.png
-   * @image html no_normal_flux_6.png
-   * </p>
+   * <p ALIGN="center"> @image html no_normal_flux_5.png @image html
+   * no_normal_flux_6.png </p>
    *
    * The vectors fields are not physically reasonable but the tangentiality
    * constraint is clearly enforced. The fact that the vector fields are zero
@@ -1658,8 +1648,8 @@ namespace VectorTools
    * @param[in] fe_function A vector with nodal values representing the
    * numerical approximation $u_h$. This vector needs to correspond to the
    * finite element space represented by @p dof.
-   * @param[in] exact_solution The exact solution that is used to compute
-   * the error.
+   * @param[in] exact_solution The exact solution that is used to compute the
+   * error.
    * @param[out] difference The vector of values $d_K$ computed as above.
    * @param[in] q The quadrature formula used to approximate the integral
    * shown above. Note that some quadrature formulas are more useful than
index 35b525e2b1a11947278f8767d7d022c8a7ba4d48..3ecba373b02a03f6c93f1965f96377d66bb2da31 100644 (file)
@@ -482,9 +482,9 @@ namespace VectorTools
   namespace internal
   {
     /**
-     * Interpolate zero boundary values. We don't need to worry about a mapping
-     * here because the function we evaluate for the DoFs is zero in the mapped
-     * locations as well as in the original, unmapped locations
+     * Interpolate zero boundary values. We don't need to worry about a
+     * mapping here because the function we evaluate for the DoFs is zero in
+     * the mapped locations as well as in the original, unmapped locations
      */
     template <class DH>
     void
@@ -694,8 +694,8 @@ namespace VectorTools
 
 
     /**
-     * Return whether the boundary values try to constrain a degree of
-     * freedom that is already constrained to something else
+     * Return whether the boundary values try to constrain a degree of freedom
+     * that is already constrained to something else
      */
     bool constraints_and_b_v_are_compatible (const ConstraintMatrix   &constraints,
                                              std::map<types::global_dof_index,double> &boundary_values)
@@ -2412,10 +2412,8 @@ namespace VectorTools
   namespace internal
   {
     /**
-     * A structure that stores the dim DoF
-     * indices that correspond to a
-     * vector-valued quantity at a single
-     * support point.
+     * A structure that stores the dim DoF indices that correspond to a
+     * vector-valued quantity at a single support point.
      */
     template <int dim>
     struct VectorDoFTuple
@@ -2467,18 +2465,13 @@ namespace VectorTools
 
 
     /**
-     * Add the constraint
-     * $\vec n \cdot \vec u = inhom$
-     * to the list of constraints.
+     * Add the constraint $\vec n \cdot \vec u = inhom$ to the list of
+     * constraints.
      *
-     * Here, $\vec u$ is represented
-     * by the set of given DoF
-     * indices, and $\vec n$ by the
-     * vector specified as the second
-     * argument.
+     * Here, $\vec u$ is represented by the set of given DoF indices, and
+     * $\vec n$ by the vector specified as the second argument.
      *
-     * The function does not add constraints
-     * if a degree of freedom is already
+     * The function does not add constraints if a degree of freedom is already
      * constrained in the constraints object.
      */
     template <int dim>
@@ -2692,20 +2685,14 @@ namespace VectorTools
 
 
     /**
-     * Add the constraint $(\vec u-\vec u_\Gamma) \|
-     * \vec t$ to the list of
-     * constraints. In 2d, this is a
-     * single constraint, in 3d these
-     * are two constraints
+     * Add the constraint $(\vec u-\vec u_\Gamma) \| \vec t$ to the list of
+     * constraints. In 2d, this is a single constraint, in 3d these are two
+     * constraints
      *
-     * Here, $\vec u$ is represented
-     * by the set of given DoF
-     * indices, and $\vec t$ by the
-     * vector specified as the second
-     * argument.
+     * Here, $\vec u$ is represented by the set of given DoF indices, and
+     * $\vec t$ by the vector specified as the second argument.
      *
-     * The function does not add constraints
-     * if a degree of freedom is already
+     * The function does not add constraints if a degree of freedom is already
      * constrained in the constraints object.
      */
     template <int dim>
@@ -2764,11 +2751,8 @@ namespace VectorTools
 
 
     /**
-     * Given a vector, compute a set
-     * of dim-1 vectors that are
-     * orthogonal to the first one
-     * and mutually orthonormal as
-     * well.
+     * Given a vector, compute a set of dim-1 vectors that are orthogonal to
+     * the first one and mutually orthonormal as well.
      */
     template <int dim>
     void
index 9d0af6833ce206607977988b6b043e767caf74d2..e1633b11a009864f96a5f4bd5a86d94a7f250b5c 100644 (file)
@@ -38,25 +38,23 @@ DEAL_II_NAMESPACE_OPEN
 namespace OpenCASCADE
 {
   /**
-   * A Boundary object based on OpenCASCADE TopoDS_Shape where where
-   * new points are first computed by averaging the surrounding points
-   * in the same way as FlatManifold does, and are then projected in the
-   * normal direction using OpenCASCADE utilities.
+   * A Boundary object based on OpenCASCADE TopoDS_Shape where where new
+   * points are first computed by averaging the surrounding points in the same
+   * way as FlatManifold does, and are then projected in the normal direction
+   * using OpenCASCADE utilities.
    *
-   * This class makes no assumptions on the shape you pass to it, and
-   * the topological dimension of the Manifold is inferred from the
-   * TopoDS_Shape itself. In debug mode there is a sanity check to
-   * make sure that the surrounding points (the ones used in
-   * project_to_manifold()) actually live on the Manifold, i.e.,
-   * calling OpenCASCADE::closest_point() on those points leaves them
-   * untouched. If this is not the case, an ExcPointNotOnManifold is
-   * thrown.
+   * This class makes no assumptions on the shape you pass to it, and the
+   * topological dimension of the Manifold is inferred from the TopoDS_Shape
+   * itself. In debug mode there is a sanity check to make sure that the
+   * surrounding points (the ones used in project_to_manifold()) actually live
+   * on the Manifold, i.e., calling OpenCASCADE::closest_point() on those
+   * points leaves them untouched. If this is not the case, an
+   * ExcPointNotOnManifold is thrown.
    *
-   * This could happen, for example, if you are trying to use a shape
-   * of type TopoDS_Edge when projecting on a face. In this case, the
-   * vertices of the face would be collapsed to the edge, and your
-   * surrounding points would not be lying on the given shape, raising
-   * an exception.
+   * This could happen, for example, if you are trying to use a shape of type
+   * TopoDS_Edge when projecting on a face. In this case, the vertices of the
+   * face would be collapsed to the edge, and your surrounding points would
+   * not be lying on the given shape, raising an exception.
    *
    * @author Luca Heltai, Andrea Mola, 2011--2014.
    */
@@ -66,23 +64,23 @@ namespace OpenCASCADE
   public:
 
     /**
-     * The standard constructor takes a generic TopoDS_Shape @p sh,
-     * and a tolerance used to compute distances internally.
+     * The standard constructor takes a generic TopoDS_Shape @p sh, and a
+     * tolerance used to compute distances internally.
      *
-     * The TopoDS_Shape can be arbitrary, i.e., a collection of
-     * shapes, faces, edges or a single face or edge.
+     * The TopoDS_Shape can be arbitrary, i.e., a collection of shapes, faces,
+     * edges or a single face or edge.
      */
     NormalProjectionBoundary(const TopoDS_Shape &sh,
                              const double tolerance=1e-7);
 
     /**
-     * Perform the actual projection onto the manifold. This function,
-     * in debug mode, checks that each of the @p surrounding_points is
-     * within tolerance from the given TopoDS_Shape. If this is not
-     * the case, an exception is thrown.
+     * Perform the actual projection onto the manifold. This function, in
+     * debug mode, checks that each of the @p surrounding_points is within
+     * tolerance from the given TopoDS_Shape. If this is not the case, an
+     * exception is thrown.
      *
-     * The projected point is computed using OpenCASCADE normal
-     * projection algorithms.
+     * The projected point is computed using OpenCASCADE normal projection
+     * algorithms.
      */
     virtual Point<spacedim>
     project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
@@ -91,10 +89,10 @@ namespace OpenCASCADE
 
   private:
     /**
-     * The topological shape which is used internally to project
-     * points. You can construct such a shape by calling the
-     * OpenCASCADE::read_IGES() function, which will create a
-     * TopoDS_Shape with the geometry contained in the IGES file.
+     * The topological shape which is used internally to project points. You
+     * can construct such a shape by calling the OpenCASCADE::read_IGES()
+     * function, which will create a TopoDS_Shape with the geometry contained
+     * in the IGES file.
      */
     const TopoDS_Shape sh;
 
@@ -105,26 +103,23 @@ namespace OpenCASCADE
   };
 
   /**
-   * A Boundary object based on OpenCASCADE TopoDS_Shape where new
-   * points are first computed by averaging the surrounding points in
-   * the same way as FlatManifold does, and then projecting them onto
-   * the manifold along the direction specified at construction time
-   * using OpenCASCADE utilities.
+   * A Boundary object based on OpenCASCADE TopoDS_Shape where new points are
+   * first computed by averaging the surrounding points in the same way as
+   * FlatManifold does, and then projecting them onto the manifold along the
+   * direction specified at construction time using OpenCASCADE utilities.
    *
-   * This class makes no assumptions on the shape you pass to it, and
-   * the topological dimension of the Manifold is inferred from the
-   * TopoDS_Shape itself. In debug mode there is a sanity check to
-   * make sure that the surrounding points (the ones used in
-   * project_to_manifold()) actually live on the Manifold, i.e.,
-   * calling OpenCASCADE::closest_point() on those points leaves them
-   * untouched. If this is not the case, an ExcPointNotOnManifold is
-   * thrown.
+   * This class makes no assumptions on the shape you pass to it, and the
+   * topological dimension of the Manifold is inferred from the TopoDS_Shape
+   * itself. In debug mode there is a sanity check to make sure that the
+   * surrounding points (the ones used in project_to_manifold()) actually live
+   * on the Manifold, i.e., calling OpenCASCADE::closest_point() on those
+   * points leaves them untouched. If this is not the case, an
+   * ExcPointNotOnManifold is thrown.
    *
-   * Notice that this type of Boundary descriptor may fail to give
-   * results if the triangulation to be refined is close to the
-   * boundary of the given TopoDS_Shape, or when the direction you use
-   * at construction time does not intersect the shape. An exception
-   * is thrown when this happens.
+   * Notice that this type of Boundary descriptor may fail to give results if
+   * the triangulation to be refined is close to the boundary of the given
+   * TopoDS_Shape, or when the direction you use at construction time does not
+   * intersect the shape. An exception is thrown when this happens.
    *
    * @author Luca Heltai, Andrea Mola, 2011--2014.
    */
@@ -141,10 +136,10 @@ namespace OpenCASCADE
                                   const double tolerance=1e-7);
 
     /**
-     * Perform the actual projection onto the manifold. This function,
-     * in debug mode, checks that each of the @p surrounding_points is
-     * within tolerance from the given TopoDS_Shape. If this is not
-     * the case, an exception is thrown.
+     * Perform the actual projection onto the manifold. This function, in
+     * debug mode, checks that each of the @p surrounding_points is within
+     * tolerance from the given TopoDS_Shape. If this is not the case, an
+     * exception is thrown.
      *
      * The projected point is computed using OpenCASCADE directional
      * projection algorithms.
@@ -155,10 +150,10 @@ namespace OpenCASCADE
 
   private:
     /**
-     * The topological shape which is used internally to project
-     * points. You can construct such a shape by calling the
-     * OpenCASCADE::read_IGES() function, which will create a
-     * TopoDS_Shape with the geometry contained in the IGES file.
+     * The topological shape which is used internally to project points. You
+     * can construct such a shape by calling the OpenCASCADE::read_IGES()
+     * function, which will create a TopoDS_Shape with the geometry contained
+     * in the IGES file.
      */
     const TopoDS_Shape sh;
 
@@ -175,51 +170,46 @@ namespace OpenCASCADE
 
 
   /**
-   * A Boundary object based on OpenCASCADE TopoDS_Shape where new
-   * points are first computed by averaging the surrounding points in
-   * the same way as FlatManifold does, and then projecting them using
-   * OpenCASCADE utilities onto the manifold along a direction which
-   * is an estimation of the surrounding points (hence mesh cell)
-   * normal.
+   * A Boundary object based on OpenCASCADE TopoDS_Shape where new points are
+   * first computed by averaging the surrounding points in the same way as
+   * FlatManifold does, and then projecting them using OpenCASCADE utilities
+   * onto the manifold along a direction which is an estimation of the
+   * surrounding points (hence mesh cell) normal.
    *
-   * The direction normal to the mesh is particularly useful because
-   * it is the direction in which the mesh is missing nodes. For
-   * instance, during the refinement of a cell a new node is initially
-   * created around the baricenter of the cell. This location somehow
-   * ensures a uniform distance from the nodes of the old cell.
-   * Projecting such cell baricenter onto the CAD surface in the direction
-   * normal to the original cell will then retain uniform distance from
-   * the points of the original cell. Of course, at the stage of mesh
-   * generation, no dof handler nor finite element are defined, and
-   * such direction has to be estimated.
-   * For the case in which 8 surrounding points are present, 4 different
-   * triangles are identified with the points assigned, and the normals
-   * of such triangles are averaged to obtain the approximation of
-   * the normal to the cell.
+   * The direction normal to the mesh is particularly useful because it is the
+   * direction in which the mesh is missing nodes. For instance, during the
+   * refinement of a cell a new node is initially created around the
+   * baricenter of the cell. This location somehow ensures a uniform distance
+   * from the nodes of the old cell. Projecting such cell baricenter onto the
+   * CAD surface in the direction normal to the original cell will then retain
+   * uniform distance from the points of the original cell. Of course, at the
+   * stage of mesh generation, no dof handler nor finite element are defined,
+   * and such direction has to be estimated. For the case in which 8
+   * surrounding points are present, 4 different triangles are identified with
+   * the points assigned, and the normals of such triangles are averaged to
+   * obtain the approximation of the normal to the cell.
    *
-   * The case in which 2 surrounding points are present (i.e.:a cell
-   * edge is being refined) is of course more tricky. The average of
-   * the CAD surface normals at the 2 surrounding points is first
-   * computed, and then projected onto the plane normal to the
-   * segment linking the surrounding points. This again is an attempt
-   * to have the new point with equal distance with respect to the
-   * surrounding points
+   * The case in which 2 surrounding points are present (i.e.:a cell edge is
+   * being refined) is of course more tricky. The average of the CAD surface
+   * normals at the 2 surrounding points is first computed, and then projected
+   * onto the plane normal to the segment linking the surrounding points. This
+   * again is an attempt to have the new point with equal distance with
+   * respect to the surrounding points
    *
-   * This class only operates with CAD faces and makes the assumption
-   * that the shape you pass to it contains at least one face. If that
-   * is not the case, an Exception is thrown. In debug mode there is a
-   * sanity check to make sure that the surrounding points (the ones
-   * used in project_to_manifold()) actually live on the Manifold,
-   * i.e., calling OpenCASCADE::closest_point() on those points leaves
-   * them untouched. If this is not the case, an ExcPointNotOnManifold
-   * is thrown.
+   * This class only operates with CAD faces and makes the assumption that the
+   * shape you pass to it contains at least one face. If that is not the case,
+   * an Exception is thrown. In debug mode there is a sanity check to make
+   * sure that the surrounding points (the ones used in project_to_manifold())
+   * actually live on the Manifold, i.e., calling OpenCASCADE::closest_point()
+   * on those points leaves them untouched. If this is not the case, an
+   * ExcPointNotOnManifold is thrown.
    *
    *
-   * Notice that this type of Boundary descriptor may fail to give
-   * results if the triangulation to be refined is close to the
-   * boundary of the given TopoDS_Shape, or when the normal direction
-   * estimated from the surrounding points does not intersect the
-   * shape.  An exception is thrown when this happens.
+   * Notice that this type of Boundary descriptor may fail to give results if
+   * the triangulation to be refined is close to the boundary of the given
+   * TopoDS_Shape, or when the normal direction estimated from the surrounding
+   * points does not intersect the shape.  An exception is thrown when this
+   * happens.
    *
    * @author Luca Heltai, Andrea Mola, 2011--2014.
    */
@@ -229,17 +219,17 @@ namespace OpenCASCADE
   public:
     /**
      * Construct a Boundary object which will project points on the
-     * TopoDS_Shape @p sh, along a direction which is approximately
-     * normal to the mesh cell.
+     * TopoDS_Shape @p sh, along a direction which is approximately normal to
+     * the mesh cell.
      */
     NormalToMeshProjectionBoundary(const TopoDS_Shape &sh,
                                    const double tolerance=1e-7);
 
     /**
-     * Perform the actual projection onto the manifold. This function,
-     * in debug mode, checks that each of the @p surrounding_points is
-     * within tolerance from the given TopoDS_Shape. If this is not
-     * the case, an exception is thrown.
+     * Perform the actual projection onto the manifold. This function, in
+     * debug mode, checks that each of the @p surrounding_points is within
+     * tolerance from the given TopoDS_Shape. If this is not the case, an
+     * exception is thrown.
      */
     virtual Point<spacedim>
     project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
@@ -247,10 +237,10 @@ namespace OpenCASCADE
 
   private:
     /**
-     * The topological shape which is used internally to project
-     * points. You can construct such a shape by calling the
-     * OpenCASCADE::read_IGES() function, which will create a
-     * TopoDS_Shape with the geometry contained in the IGES file.
+     * The topological shape which is used internally to project points. You
+     * can construct such a shape by calling the OpenCASCADE::read_IGES()
+     * function, which will create a TopoDS_Shape with the geometry contained
+     * in the IGES file.
      */
     const TopoDS_Shape sh;
 
@@ -266,24 +256,21 @@ namespace OpenCASCADE
   };
 
   /**
-   * A Boundary object based on OpenCASCADE TopoDS_Shape objects which
-   * have topological dimension equal to one (TopoDS_Edge or
-   * TopoDS_Wire) where new points are located at the arclength
-   * average of the surrounding points. If the given TopoDS_Shape can
-   * be casted to a periodic (closed) curve, then this information is
-   * used internally to set the periodicity of the base ChartManifold
-   * class.
+   * A Boundary object based on OpenCASCADE TopoDS_Shape objects which have
+   * topological dimension equal to one (TopoDS_Edge or TopoDS_Wire) where new
+   * points are located at the arclength average of the surrounding points. If
+   * the given TopoDS_Shape can be casted to a periodic (closed) curve, then
+   * this information is used internally to set the periodicity of the base
+   * ChartManifold class.
    *
-   * This class can only work on TopoDS_Edge or TopoDS_Wire objects,
-   * and it only makes sense when spacedim is three. If you use an
-   * object of topological dimension different from one, an exception
-   * is throw.
+   * This class can only work on TopoDS_Edge or TopoDS_Wire objects, and it
+   * only makes sense when spacedim is three. If you use an object of
+   * topological dimension different from one, an exception is throw.
    *
-   * In debug mode there is an additional sanity check to make sure
-   * that the surrounding points actually live on the Manifold, i.e.,
-   * calling OpenCASCADE::closest_point() on those points leaves them
-   * untouched. If this is not the case, an ExcPointNotOnManifold is
-   * thrown.
+   * In debug mode there is an additional sanity check to make sure that the
+   * surrounding points actually live on the Manifold, i.e., calling
+   * OpenCASCADE::closest_point() on those points leaves them untouched. If
+   * this is not the case, an ExcPointNotOnManifold is thrown.
    *
    * @author Luca Heltai, Andrea Mola, 2011--2014.
    */
@@ -298,9 +285,9 @@ namespace OpenCASCADE
                                     const double tolerance=1e-7);
 
     /**
-     * Given a point on real space, find its arclength
-     * parameter. Throws an error in debug mode, if the point is not
-     * on the TopoDS_Edge given at construction time.
+     * Given a point on real space, find its arclength parameter. Throws an
+     * error in debug mode, if the point is not on the TopoDS_Edge given at
+     * construction time.
      */
     virtual Point<1>
     pull_back(const Point<spacedim> &space_point) const;
@@ -313,8 +300,8 @@ namespace OpenCASCADE
 
   private:
     /**
-     * A Curve adaptor. This is the one which is used in the
-     * computations, and it points to the right one above.
+     * A Curve adaptor. This is the one which is used in the computations, and
+     * it points to the right one above.
      */
     Handle_Adaptor3d_HCurve curve;
 
@@ -324,8 +311,8 @@ namespace OpenCASCADE
     const double tolerance;
 
     /**
-     * The total length of the curve. This is also used as a period if
-     * the edge is periodic.
+     * The total length of the curve. This is also used as a period if the
+     * edge is periodic.
      */
     const double length;
   };
index 40228c69b035b1cc6c835b09d3c720b87a845610..8347fa14d51e1339fe7ed95b4d8980b01be80794 100644 (file)
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * We collect in this namespace all utilities which operate on
- * OpenCASCADE entities. OpenCASCADE splits every object into a
- * topological description and a geometrical entity. The basic
- * topological description is a TopoDS_Shape. TopoDS_Shapes are light
- * objects, and can be copied around. The closest deal.II analog is a
- * TriaIterator.
+ * We collect in this namespace all utilities which operate on OpenCASCADE
+ * entities. OpenCASCADE splits every object into a topological description
+ * and a geometrical entity. The basic topological description is a
+ * TopoDS_Shape. TopoDS_Shapes are light objects, and can be copied around.
+ * The closest deal.II analog is a TriaIterator.
  *
- * The OpenCASCADE topology is designed with reference to the STEP
- * standard ISO-10303-42.  The structure is an oriented one-way graph,
- * where parents refer to their children, and there are no back
- * references. Abstract structure is implemented as C++ classes from
- * the TopoDS package. A TopoDS_Shape is manipulated by value and
- * contains 3 fields: location, orientation and a myTShape handle (of
- * the TopoDS_TShape type). According to OpenCASCADE documentation,
- * myTShape and Location are used to share data between various shapes
- * to save memory. For example, an edge belonging to two faces has
- * equal Locations and myTShape fields but different Orientations
- * (Forward in context of one face and Reversed in one of the other).
+ * The OpenCASCADE topology is designed with reference to the STEP standard
+ * ISO-10303-42.  The structure is an oriented one-way graph, where parents
+ * refer to their children, and there are no back references. Abstract
+ * structure is implemented as C++ classes from the TopoDS package. A
+ * TopoDS_Shape is manipulated by value and contains 3 fields: location,
+ * orientation and a myTShape handle (of the TopoDS_TShape type). According to
+ * OpenCASCADE documentation, myTShape and Location are used to share data
+ * between various shapes to save memory. For example, an edge belonging to
+ * two faces has equal Locations and myTShape fields but different
+ * Orientations (Forward in context of one face and Reversed in one of the
+ * other).
  *
- * Valid shapes include collection of other shapes, solids, faces,
- * edges, vertices, etc.
+ * Valid shapes include collection of other shapes, solids, faces, edges,
+ * vertices, etc.
  *
- * Once a topological description is available, if a concrete
- * geometrical object can be created, the BRep classes allow one to
- * extract the actual geometrical information from a shape.
+ * Once a topological description is available, if a concrete geometrical
+ * object can be created, the BRep classes allow one to extract the actual
+ * geometrical information from a shape.
  *
- * This is done by inheriting abstract topology classes from the
- * TopoDS package by those implementing a boundary representation
- * model (from the BRep package). Only 3 types of topological objects
- * have geometric representations – vertex, edge, and face.
+ * This is done by inheriting abstract topology classes from the TopoDS
+ * package by those implementing a boundary representation model (from the
+ * BRep package). Only 3 types of topological objects have geometric
+ * representations – vertex, edge, and face.
  *
- * Every TopoDS_Shape can be queried to figure out what type of shape
- * it is, and actual geometrical objects, like surfaces, curves or
- * points, can be extracted using BRepTools.
+ * Every TopoDS_Shape can be queried to figure out what type of shape it is,
+ * and actual geometrical objects, like surfaces, curves or points, can be
+ * extracted using BRepTools.
  *
- * In this namespace we provide readers and writers that read standard
- * CAD files, and return a TopoDS_Shape, or that write a CAD file,
- * given a TopoDS_Shape. Most of the functions in the OpenCASCADE
- * namespace deal with TopoDS_Shapes of one type or another, and
- * provide interfaces to common deal.II objects, like Triangulation,
- * Manifold, and so on.
+ * In this namespace we provide readers and writers that read standard CAD
+ * files, and return a TopoDS_Shape, or that write a CAD file, given a
+ * TopoDS_Shape. Most of the functions in the OpenCASCADE namespace deal with
+ * TopoDS_Shapes of one type or another, and provide interfaces to common
+ * deal.II objects, like Triangulation, Manifold, and so on.
  *
- * Notice that these tools are only useful when spacedim is equal to
- * three, since OpenCASCADE only operates in three-dimensional mode.
+ * Notice that these tools are only useful when spacedim is equal to three,
+ * since OpenCASCADE only operates in three-dimensional mode.
  *
  * @author Luca Heltai, Andrea Mola, 2011--2014.
  */
 namespace OpenCASCADE
 {
   /**
-   * Count the subobjects of a shape. This function is useful to
-   * gather information about the TopoDS_Shape passed as argument. It
-   * returns the number of faces, edges and vertices (the only
-   * topological entities associated with actual geometries) which are
-   * contained in the given shape.
+   * Count the subobjects of a shape. This function is useful to gather
+   * information about the TopoDS_Shape passed as argument. It returns the
+   * number of faces, edges and vertices (the only topological entities
+   * associated with actual geometries) which are contained in the given
+   * shape.
    */
   std_cxx11::tuple<unsigned int, unsigned int, unsigned int>
   count_elements(const TopoDS_Shape &shape);
 
   /**
-   * Read IGES files and translate their content into openCascade
-   * topological entities. The option scale_factor is used to
-   * compensate for different units being used in the IGES files and
-   * in the target application. The standard unit for IGES files is
-   * millimiters. The return object is a TopoDS_Shape which contains
-   * all objects from the file.
+   * Read IGES files and translate their content into openCascade topological
+   * entities. The option scale_factor is used to compensate for different
+   * units being used in the IGES files and in the target application. The
+   * standard unit for IGES files is millimiters. The return object is a
+   * TopoDS_Shape which contains all objects from the file.
    */
   TopoDS_Shape read_IGES(const std::string &filename,
                          const double scale_factor=1e-3);
 
   /**
-    * Write the given topological shape into an IGES file.
-    */
+   * Write the given topological shape into an IGES file.
+   */
   void write_IGES(const TopoDS_Shape &shape,
                   const std::string &filename);
 
   /**
-   * Read STEP files and translate their content into openCascade
-   * topological entities. The option scale_factor is used to
-   * compensate for different units being used in the STEP files and
-   * in the target application. The standard unit for STEP files is
-   * millimiters. The return object is a TopoDS_Shape which contains
-   * all objects from the file.
+   * Read STEP files and translate their content into openCascade topological
+   * entities. The option scale_factor is used to compensate for different
+   * units being used in the STEP files and in the target application. The
+   * standard unit for STEP files is millimiters. The return object is a
+   * TopoDS_Shape which contains all objects from the file.
    */
   TopoDS_Shape read_STEP(const std::string &filename,
                          const double scale_factor=1e-3);
 
 
   /**
-    * Write the given topological shape into an STEP file.
-    */
+   * Write the given topological shape into an STEP file.
+   */
   void write_STEP(const TopoDS_Shape &shape,
                   const std::string &filename);
 
   /**
-    * This function returns the tolerance associated with the shape.
-    * Each CAD geometrical object is defined along with a tolerance,
-    * which indicates possible inaccuracy of its placement. For
-    * instance, the tolerance of a vertex indicates that it can be
-    * located in any point contained in a sphere centered in the
-    * nominal position and having radius tol. While carrying out an
-    * operation such as projecting a point onto a surface (which will
-    * in turn have its tolerance) we must keep in mind that the
-    * precision of the projection will be limited by the tolerance
-    * with which the surface is built.  The tolerance is computed
-    * taking the maximum tolerance among the subshapes composing the
-    * shape.
-    */
+   * This function returns the tolerance associated with the shape. Each CAD
+   * geometrical object is defined along with a tolerance, which indicates
+   * possible inaccuracy of its placement. For instance, the tolerance of a
+   * vertex indicates that it can be located in any point contained in a
+   * sphere centered in the nominal position and having radius tol. While
+   * carrying out an operation such as projecting a point onto a surface
+   * (which will in turn have its tolerance) we must keep in mind that the
+   * precision of the projection will be limited by the tolerance with which
+   * the surface is built.  The tolerance is computed taking the maximum
+   * tolerance among the subshapes composing the shape.
+   */
   double get_shape_tolerance(const TopoDS_Shape &shape);
 
   /**
-   * Perform the intersection of the given topological shape with the
-   * plane $c_x x + c_y y + c_z z +c = 0$. The returned topological
-   * shape will contain as few bsplines as possible. An exception is
-   * thrown if the intersection produces an empty shape.
+   * Perform the intersection of the given topological shape with the plane
+   * $c_x x + c_y y + c_z z +c = 0$. The returned topological shape will
+   * contain as few bsplines as possible. An exception is thrown if the
+   * intersection produces an empty shape.
    */
   TopoDS_Shape  intersect_plane(const TopoDS_Shape &in_shape,
                                 const double c_x,
@@ -167,34 +161,31 @@ namespace OpenCASCADE
                                 const double tolerance=1e-7);
 
   /**
-   * Try to join all edges contained in the given TopoDS_Shape into a
-   * single TopoDS_Edge, containing as few BSPlines as possible. If
-   * the input shape contains faces, they will be ignored by this
-   * function. If the contained edges cannot be joined into a single
-   * one, i.e., they form disconnected curves, an exception will be
-   * thrown.
+   * Try to join all edges contained in the given TopoDS_Shape into a single
+   * TopoDS_Edge, containing as few BSPlines as possible. If the input shape
+   * contains faces, they will be ignored by this function. If the contained
+   * edges cannot be joined into a single one, i.e., they form disconnected
+   * curves, an exception will be thrown.
    */
   TopoDS_Edge join_edges(const TopoDS_Shape &in_shape,
                          const double tolerance=1e-7);
 
   /**
-   * Creates a 3D smooth BSpline curve passing through the points in
-   * the assigned vector, and store it in the returned TopoDS_Shape
-   * (which is of type TopoDS_Edge). The points are reordered
-   * internally according to their scalar product with the direction,
-   * if direction is different from zero, otherwise they are used as
-   * passed. Notice that this function changes the input points if
-   * required by the algorithm.
+   * Creates a 3D smooth BSpline curve passing through the points in the
+   * assigned vector, and store it in the returned TopoDS_Shape (which is of
+   * type TopoDS_Edge). The points are reordered internally according to their
+   * scalar product with the direction, if direction is different from zero,
+   * otherwise they are used as passed. Notice that this function changes the
+   * input points if required by the algorithm.
    *
-   * This class is used to interpolate a BsplineCurve passing through
-   * an array of points, with a C2 Continuity. If the optional
-   * parameter @p closed is set to true, then the curve will be C2 at
-   * all points except the first (where only C1 continuity will be
-   * given), and it will be a closed curve.
+   * This class is used to interpolate a BsplineCurve passing through an array
+   * of points, with a C2 Continuity. If the optional parameter @p closed is
+   * set to true, then the curve will be C2 at all points except the first
+   * (where only C1 continuity will be given), and it will be a closed curve.
    *
-   * The curve is garanteed to be at distance @p tolerance from the
-   * input points. If the algorithm fails in generating such a curve,
-   * an exception is thrown.
+   * The curve is garanteed to be at distance @p tolerance from the input
+   * points. If the algorithm fails in generating such a curve, an exception
+   * is thrown.
    */
   TopoDS_Edge interpolation_curve(std::vector<Point<3> >  &curve_points,
                                   const Tensor<1,3> &direction=Tensor<1,3>(),
@@ -202,9 +193,9 @@ namespace OpenCASCADE
                                   const double tolerance=1e-7);
 
   /**
-   * Extract all subshapes from a TopoDS_Shape, and store the results
-   * into standard containers. If the shape does not contain a certain
-   * type of shape, the respective container will be empty.
+   * Extract all subshapes from a TopoDS_Shape, and store the results into
+   * standard containers. If the shape does not contain a certain type of
+   * shape, the respective container will be empty.
    */
   void extract_geometrical_shapes(const TopoDS_Shape &shape,
                                   std::vector<TopoDS_Face> &faces,
@@ -212,22 +203,21 @@ namespace OpenCASCADE
                                   std::vector<TopoDS_Vertex> &vertices);
 
   /**
-   * Create a triangulation from a single face. This class extract the
-   * first u and v parameter of the parametric surface making up this
-   * face, and creates a Triangulation<2,3> containing a single coarse
-   * cell reflecting this face. If the surface is not a trimmed
-   * surface, the vertices of this cell will coincide with the
-   * TopoDS_Vertex vertices of the original TopoDS_Face. This,
-   * however, is often not the case, and the user should be careful on
-   * how this mesh is used.
+   * Create a triangulation from a single face. This class extract the first u
+   * and v parameter of the parametric surface making up this face, and
+   * creates a Triangulation<2,3> containing a single coarse cell reflecting
+   * this face. If the surface is not a trimmed surface, the vertices of this
+   * cell will coincide with the TopoDS_Vertex vertices of the original
+   * TopoDS_Face. This, however, is often not the case, and the user should be
+   * careful on how this mesh is used.
    */
   void create_triangulation(const TopoDS_Face &face,
                             Triangulation<2,3> &tria);
 
   /**
-   * Extract all compound shapes from a TopoDS_Shape, and store the
-   * results into standard containers. If the shape does not contain a
-   * certain type of compound, the respective container will be empty.
+   * Extract all compound shapes from a TopoDS_Shape, and store the results
+   * into standard containers. If the shape does not contain a certain type of
+   * compound, the respective container will be empty.
    */
   void extract_compound_shapes(const TopoDS_Shape &shape,
                                std::vector<TopoDS_Compound> &compounds,
@@ -238,17 +228,17 @@ namespace OpenCASCADE
 
   /**
    * Project the point @p origin on the topological shape given by @p
-   * in_shape, and returns the projected point, the subshape which
-   * contains the point and the parametric u and v coordinates of the
-   * point within the resulting shape. If the shape is not elementary,
-   * all its subshapes are iterated, faces first, then edges, and the
-   * returned shape is the closest one to the point @p origin. If the
-   * returned shape is an edge, then only the u coordinate is filled
-   * with sensible information, and the v coordinate is set to zero.
+   * in_shape, and returns the projected point, the subshape which contains
+   * the point and the parametric u and v coordinates of the point within the
+   * resulting shape. If the shape is not elementary, all its subshapes are
+   * iterated, faces first, then edges, and the returned shape is the closest
+   * one to the point @p origin. If the returned shape is an edge, then only
+   * the u coordinate is filled with sensible information, and the v
+   * coordinate is set to zero.
    *
-   * This function returns a tuple containing the projected point, the
-   * shape, the u coordinate and the v coordinate (which is different
-   * from zero only if the resulting shape is a face).
+   * This function returns a tuple containing the projected point, the shape,
+   * the u coordinate and the v coordinate (which is different from zero only
+   * if the resulting shape is a face).
    */
   std_cxx11::tuple<Point<3>, TopoDS_Shape, double, double>
   project_point_and_pull_back(const TopoDS_Shape &in_shape,
@@ -256,23 +246,22 @@ namespace OpenCASCADE
                               const double tolerance=1e-7);
 
   /**
-   * Return the projection of the point @p origin on the topological
-   * shape given by @p in_shape. If the shape is not elementary, all
-   * its subshapes are iterated, faces first, then edges, and the
-   * returned point is the closest one to the @p in_shape, regardless
-   * of its type.
+   * Return the projection of the point @p origin on the topological shape
+   * given by @p in_shape. If the shape is not elementary, all its subshapes
+   * are iterated, faces first, then edges, and the returned point is the
+   * closest one to the @p in_shape, regardless of its type.
    */
   Point<3> closest_point(const TopoDS_Shape &in_shape,
                          const Point<3> &origin,
                          const double tolerance=1e-7);
 
   /**
-   * Given an elementary shape @p in_shape and the reference
-   * coordinates within the shape, returns the corresponding point in
-   * real space. If the shape is a TopoDS_Edge, the @p v coordinate is
-   * ignored. Only edges or faces, as returned by the function
-   * project_point_and_pull_back(), can be used as input to this
-   * function. If this is not the case, an Exception is thrown.
+   * Given an elementary shape @p in_shape and the reference coordinates
+   * within the shape, returns the corresponding point in real space. If the
+   * shape is a TopoDS_Edge, the @p v coordinate is ignored. Only edges or
+   * faces, as returned by the function project_point_and_pull_back(), can be
+   * used as input to this function. If this is not the case, an Exception is
+   * thrown.
    */
   Point<3> push_forward(const TopoDS_Shape &in_shape,
                         const double u,
@@ -280,10 +269,9 @@ namespace OpenCASCADE
 
 
   /**
-   * Given a TopoDS_Face @p face and the reference coordinates within
-   * this face, returns the corresponding point in real space, the
-   * normal to the surface at that point and the mean curvature as a
-   * tuple.
+   * Given a TopoDS_Face @p face and the reference coordinates within this
+   * face, returns the corresponding point in real space, the normal to the
+   * surface at that point and the mean curvature as a tuple.
    */
   std_cxx11::tuple<Point<3>, Point<3>, double >
   push_forward_and_differential_forms(const TopoDS_Face &face,
@@ -293,12 +281,11 @@ namespace OpenCASCADE
 
 
   /**
-   * Get the closest point to the given topological shape, together
-   * with the normal and the mean curvature at that point. If the
-   * shape is not elementary, all its sub-faces (only the faces) are
-   * iterated, faces first, and only the closest point is
-   * returned. This function will throw an exception if the @p
-   * in_shape does not contain at least one face.
+   * Get the closest point to the given topological shape, together with the
+   * normal and the mean curvature at that point. If the shape is not
+   * elementary, all its sub-faces (only the faces) are iterated, faces first,
+   * and only the closest point is returned. This function will throw an
+   * exception if the @p in_shape does not contain at least one face.
    */
   std_cxx11::tuple<Point<3>, Point<3>, double>
   closest_point_and_differential_forms(const TopoDS_Shape &in_shape,
@@ -307,9 +294,9 @@ namespace OpenCASCADE
 
 
   /**
-   * Intersect a line passing through the given @p origin point along
-   * @p direction and the given topological shape. If there is more than
-   * one intersection, it will return the closest one.
+   * Intersect a line passing through the given @p origin point along @p
+   * direction and the given topological shape. If there is more than one
+   * intersection, it will return the closest one.
    *
    * The optional @p tolerance parameter is used to compute distances.
    */
@@ -332,10 +319,10 @@ namespace OpenCASCADE
 
 
   /**
-   * Sort two points according to their scalar product with
-   * direction. If the norm of the direction is zero, then use
-   * lexicographical ordering. The optional parameter is used as a
-   * relative tolerance when comparing objects.
+   * Sort two points according to their scalar product with direction. If the
+   * norm of the direction is zero, then use lexicographical ordering. The
+   * optional parameter is used as a relative tolerance when comparing
+   * objects.
    */
   bool point_compare(const Point<3> &p1, const Point<3> &p2,
                      const Tensor<1,3> &direction=Tensor<1,3>(),
@@ -343,16 +330,16 @@ namespace OpenCASCADE
 
 
   /**
-   * Exception thrown when the point specified as argument does not
-   * lie between @p tolerance from the given TopoDS_Shape.
+   * Exception thrown when the point specified as argument does not lie
+   * between @p tolerance from the given TopoDS_Shape.
    */
   DeclException1 (ExcPointNotOnManifold,
                   Point<3>,
                   <<"The point [ "<<arg1<<" ] is not on the manifold.");
 
   /**
-   * Exception thrown when the point specified as argument cannot be
-   * projected to the manifold.
+   * Exception thrown when the point specified as argument cannot be projected
+   * to the manifold.
    */
   DeclException1 (ExcProjectionFailed,
                   Point<3>,
@@ -360,8 +347,7 @@ namespace OpenCASCADE
                   << " ] failed.");
 
   /**
-   * Thrown when internal OpenCASCADE utilities fail to return the OK
-   * status.
+   * Thrown when internal OpenCASCADE utilities fail to return the OK status.
    */
   DeclException1 (ExcOCCError,
                   IFSelect_ReturnStatus,

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.