step-18.h

Go to the documentation of this file.

,
 *                                            Vector<double> &values) const
 *   {
 *     Assert(values.size() == dim, ExcDimensionMismatch(values.size(), dim));
 * 
 *     const double g   = 9.81;
 *     const double rho = 7700;
 * 
 *     values          = 0;
 *     values(dim - 1) = -rho * g;
 *   }
 * 
 * 
 * 
 *   template <int dim>
 *   void BodyForce<dim>::vector_value_list(
 *     const std::vector<Point<dim>> &points,
 *     std::vector<Vector<double>> &  value_list) const
 *   {
 *     const unsigned int n_points = points.size();
 * 
 *     Assert(value_list.size() == n_points,
 *            ExcDimensionMismatch(value_list.size(), n_points));
 * 
 *     for (unsigned int p = 0; p < n_points; ++p)
 *       BodyForce<dim>::vector_value(points[p], value_list[p]);
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="ThecodeIncrementalBoundaryValuecodeclass"></a> 
 * <h3>The <code>IncrementalBoundaryValue</code> class</h3>
 * 

 * 
 * In addition to body forces, movement can be induced by boundary forces
 * and forced boundary displacement. The latter case is equivalent to forces
 * being chosen in such a way that they induce certain displacement.
 *   

 * 
 * For quasistatic displacement, typical boundary forces would be pressure
 * on a body, or tangential friction against another body. We chose a
 * somewhat simpler case here: we prescribe a certain movement of (parts of)
 * the boundary, or at least of certain components of the displacement
 * vector. We describe this by another vector-valued function that, for a
 * given point on the boundary, returns the prescribed displacement.
 *   

 * 
 * Since we have a time-dependent problem, the displacement increment of the
 * boundary equals the displacement accumulated during the length of the
 * timestep. The class therefore has to know both the present time and the
 * length of the present time step, and can then approximate the incremental
 * displacement as the present velocity times the present timestep.
 *   

 * 
 * For the purposes of this program, we choose a simple form of boundary
 * displacement: we displace the top boundary with constant velocity
 * downwards. The rest of the boundary is either going to be fixed (and is
 * then described using an object of type
 * <code>Functions::ZeroFunction</code>) or free (Neumann-type, in which case
 * nothing special has to be done).  The implementation of the class
 * describing the constant downward motion should then be obvious using the
 * knowledge we gained through all the previous example programs:
 * 
 * @code
 *   template <int dim>
 *   class IncrementalBoundaryValues : public Function<dim>
 *   {
 *   public:
 *     IncrementalBoundaryValues(const double present_time,
 *                               const double present_timestep);
 * 
 *     virtual void vector_value(const Point<dim> &p,
 *                               Vector<double> &  values) const override;
 * 
 *     virtual void
 *     vector_value_list(const std::vector<Point<dim>> &points,
 *                       std::vector<Vector<double>> &  value_list) const override;
 * 
 *   private:
 *     const double velocity;
 *     const double present_time;
 *     const double present_timestep;
 *   };
 * 
 * 
 *   template <int dim>
 *   IncrementalBoundaryValues<dim>::IncrementalBoundaryValues(
 *     const double present_time,
 *     const double present_timestep)
 *     : Function<dim>(dim)
 *     , velocity(.08)
 *     , present_time(present_time)
 *     , present_timestep(present_timestep)
 *   {}
 * 
 * 
 *   template <int dim>
 *   void
 *   IncrementalBoundaryValues<dim>::vector_value(const Point<dim> & /*p*/,
 *                                                Vector<double> &values) const
 *   {
 *     Assert(values.size() == dim, ExcDimensionMismatch(values.size(), dim));
 * 
 *     values    = 0;
 *     values(2) = -present_timestep * velocity;
 *   }
 * 
 * 
 * 
 *   template <int dim>
 *   void IncrementalBoundaryValues<dim>::vector_value_list(
 *     const std::vector<Point<dim>> &points,
 *     std::vector<Vector<double>> &  value_list) const
 *   {
 *     const unsigned int n_points = points.size();
 * 
 *     Assert(value_list.size() == n_points,
 *            ExcDimensionMismatch(value_list.size(), n_points));
 * 
 *     for (unsigned int p = 0; p < n_points; ++p)
 *       IncrementalBoundaryValues<dim>::vector_value(points[p], value_list[p]);
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="ImplementationofthecodeTopLevelcodeclass"></a> 
 * <h3>Implementation of the <code>TopLevel</code> class</h3>
 * 

 * 
 * Now for the implementation of the main class. First, we initialize the
 * stress-strain tensor, which we have declared as a static const
 * variable. We chose Lam&eacute; constants that are appropriate for steel:
 * 
 * @code
 *   template <int dim>
 *   const SymmetricTensor<4, dim> TopLevel<dim>::stress_strain_tensor =
 *     get_stress_strain_tensor<dim>(/*lambda = */ 9.695e10,
 *                                   /*mu     = */ 7.617e10);
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="Thepublicinterface"></a> 
 * <h4>The public interface</h4>
 * 

 * 
 * The next step is the definition of constructors and destructors. There
 * are no surprises here: we choose linear and continuous finite elements
 * for each of the <code>dim</code> vector components of the solution, and a
 * Gaussian quadrature formula with 2 points in each coordinate
 * direction. The destructor should be obvious:
 * 
 * @code
 *   template <int dim>
 *   TopLevel<dim>::TopLevel()
 *     : triangulation(MPI_COMM_WORLD)
 *     , fe(FE_Q<dim>(1), dim)
 *     , dof_handler(triangulation)
 *     , quadrature_formula(fe.degree + 1)
 *     , present_time(0.0)
 *     , present_timestep(1.0)
 *     , end_time(10.0)
 *     , timestep_no(0)
 *     , mpi_communicator(MPI_COMM_WORLD)
 *     , n_mpi_processes(Utilities::MPI::n_mpi_processes(mpi_communicator))
 *     , this_mpi_process(Utilities::MPI::this_mpi_process(mpi_communicator))
 *     , pcout(std::cout, this_mpi_process == 0)
 *   {}
 * 
 * 
 * 
 *   template <int dim>
 *   TopLevel<dim>::~TopLevel()
 *   {
 *     dof_handler.clear();
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * The last of the public functions is the one that directs all the work,
 * <code>run()</code>. It initializes the variables that describe where in
 * time we presently are, then runs the first time step, then loops over all
 * the other time steps. Note that for simplicity we use a fixed time step,
 * whereas a more sophisticated program would of course have to choose it in
 * some more reasonable way adaptively:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::run()
 *   {
 *     do_initial_timestep();
 * 
 *     while (present_time < end_time)
 *       do_timestep();
 *   }
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelcreate_coarse_grid"></a> 
 * <h4>TopLevel::create_coarse_grid</h4>
 * 

 * 
 * The next function in the order in which they were declared above is the
 * one that creates the coarse grid from which we start. For this example
 * program, we want to compute the deformation of a cylinder under axial
 * compression. The first step therefore is to generate a mesh for a
 * cylinder of length 3 and with inner and outer radii of 0.8 and 1,
 * respectively. Fortunately, there is a library function for such a mesh.
 *   

 * 
 * In a second step, we have to associated boundary conditions with the
 * upper and lower faces of the cylinder. We choose a boundary indicator of
 * 0 for the boundary faces that are characterized by their midpoints having
 * z-coordinates of either 0 (bottom face), an indicator of 1 for z=3 (top
 * face); finally, we use boundary indicator 2 for all faces on the inside
 * of the cylinder shell, and 3 for the outside.
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::create_coarse_grid()
 *   {
 *     const double inner_radius = 0.8, outer_radius = 1;
 *     GridGenerator::cylinder_shell(triangulation, 3, inner_radius, outer_radius);
 *     for (const auto &cell : triangulation.active_cell_iterators())
 *       for (const auto &face : cell->face_iterators())
 *         if (face->at_boundary())
 *           {
 *             const Point<dim> face_center = face->center();
 * 
 *             if (face_center[2] == 0)
 *               face->set_boundary_id(0);
 *             else if (face_center[2] == 3)
 *               face->set_boundary_id(1);
 *             else if (std::sqrt(face_center[0] * face_center[0] +
 *                                face_center[1] * face_center[1]) <
 *                      (inner_radius + outer_radius) / 2)
 *               face->set_boundary_id(2);
 *             else
 *               face->set_boundary_id(3);
 *           }
 * 
 * @endcode
 * 
 * Once all this is done, we can refine the mesh once globally:
 * 
 * @code
 *     triangulation.refine_global(1);
 * 
 * @endcode
 * 
 * As the final step, we need to set up a clean state of the data that we
 * store in the quadrature points on all cells that are treated on the
 * present processor.
 * 
 * @code
 *     setup_quadrature_point_history();
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelsetup_system"></a> 
 * <h4>TopLevel::setup_system</h4>
 * 

 * 
 * The next function is the one that sets up the data structures for a given
 * mesh. This is done in most the same way as in @ref step_17 "step-17": distribute the
 * degrees of freedom, then sort these degrees of freedom in such a way that
 * each processor gets a contiguous chunk of them. Note that subdivisions into
 * chunks for each processor is handled in the functions that create or
 * refine grids, unlike in the previous example program (the point where
 * this happens is mostly a matter of taste; here, we chose to do it when
 * grids are created since in the <code>do_initial_timestep</code> and
 * <code>do_timestep</code> functions we want to output the number of cells
 * on each processor at a point where we haven't called the present function
 * yet).
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::setup_system()
 *   {
 *     dof_handler.distribute_dofs(fe);
 *     locally_owned_dofs = dof_handler.locally_owned_dofs();
 *     DoFTools::extract_locally_relevant_dofs(dof_handler, locally_relevant_dofs);
 * 
 * @endcode
 * 
 * The next step is to set up constraints due to hanging nodes. This has
 * been handled many times before:
 * 
 * @code
 *     hanging_node_constraints.clear();
 *     DoFTools::make_hanging_node_constraints(dof_handler,
 *                                             hanging_node_constraints);
 *     hanging_node_constraints.close();
 * 
 * @endcode
 * 
 * And then we have to set up the matrix. Here we deviate from @ref step_17 "step-17", in
 * which we simply used PETSc's ability to just know about the size of the
 * matrix and later allocate those nonzero elements that are being written
 * to. While this works just fine from a correctness viewpoint, it is not
 * at all efficient: if we don't give PETSc a clue as to which elements
 * are written to, it is (at least at the time of this writing) unbearably
 * slow when we set the elements in the matrix for the first time (i.e. in
 * the first timestep). Later on, when the elements have been allocated,
 * everything is much faster. In experiments we made, the first timestep
 * can be accelerated by almost two orders of magnitude if we instruct
 * PETSc which elements will be used and which are not.
 *     

 * 
 * To do so, we first generate the sparsity pattern of the matrix we are
 * going to work with, and make sure that the condensation of hanging node
 * constraints add the necessary additional entries in the sparsity
 * pattern:
 * 
 * @code
 *     DynamicSparsityPattern sparsity_pattern(locally_relevant_dofs);
 *     DoFTools::make_sparsity_pattern(dof_handler,
 *                                     sparsity_pattern,
 *                                     hanging_node_constraints,
 *                                     /*keep constrained dofs*/ false);
 *     SparsityTools::distribute_sparsity_pattern(sparsity_pattern,
 *                                                locally_owned_dofs,
 *                                                mpi_communicator,
 *                                                locally_relevant_dofs);
 * @endcode
 * 
 * Note that we have used the <code>DynamicSparsityPattern</code> class
 * here that was already introduced in @ref step_11 "step-11", rather than the
 * <code>SparsityPattern</code> class that we have used in all other
 * cases. The reason for this is that for the latter class to work we have
 * to give an initial upper bound for the number of entries in each row, a
 * task that is traditionally done by
 * <code>DoFHandler::max_couplings_between_dofs()</code>. However, this
 * function suffers from a serious problem: it has to compute an upper
 * bound to the number of nonzero entries in each row, and this is a
 * rather complicated task, in particular in 3d. In effect, while it is
 * quite accurate in 2d, it often comes up with much too large a number in
 * 3d, and in that case the <code>SparsityPattern</code> allocates much
 * too much memory at first, often several 100 MBs. This is later
 * corrected when <code>DoFTools::make_sparsity_pattern</code> is called
 * and we realize that we don't need all that much memory, but at time it
 * is already too late: for large problems, the temporary allocation of
 * too much memory can lead to out-of-memory situations.
 *     

 * 
 * In order to avoid this, we resort to the
 * <code>DynamicSparsityPattern</code> class that is slower but does
 * not require any up-front estimate on the number of nonzero entries per
 * row. It therefore only ever allocates as much memory as it needs at any
 * given time, and we can build it even for large 3d problems.
 *     

 * 
 * It is also worth noting that due to the specifics of
 * parallel::shared::Triangulation, the sparsity pattern we construct is
 * global, i.e. comprises all degrees of freedom whether they will be
 * owned by the processor we are on or another one (in case this program
 * is run in %parallel via MPI). This of course is not optimal -- it
 * limits the size of the problems we can solve, since storing the entire
 * sparsity pattern (even if only for a short time) on each processor does
 * not scale well. However, there are several more places in the program
 * in which we do this, for example we always keep the global
 * triangulation and DoF handler objects around, even if we only work on
 * part of them. At present, deal.II does not have the necessary
 * facilities to completely distribute these objects (a task that, indeed,
 * is very hard to achieve with adaptive meshes, since well-balanced
 * subdivisions of a domain tend to become unbalanced as the mesh is
 * adaptively refined).
 *     

 * 
 * With this data structure, we can then go to the PETSc sparse matrix and
 * tell it to preallocate all the entries we will later want to write to:
 * 
 * @code
 *     system_matrix.reinit(locally_owned_dofs,
 *                          locally_owned_dofs,
 *                          sparsity_pattern,
 *                          mpi_communicator);
 * @endcode
 * 
 * After this point, no further explicit knowledge of the sparsity pattern
 * is required any more and we can let the <code>sparsity_pattern</code>
 * variable go out of scope without any problem.
 * 

 * 
 * The last task in this function is then only to reset the right hand
 * side vector as well as the solution vector to its correct size;
 * remember that the solution vector is a local one, unlike the right hand
 * side that is a distributed %parallel one and therefore needs to know
 * the MPI communicator over which it is supposed to transmit messages:
 * 
 * @code
 *     system_rhs.reinit(locally_owned_dofs, mpi_communicator);
 *     incremental_displacement.reinit(dof_handler.n_dofs());
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelassemble_system"></a> 
 * <h4>TopLevel::assemble_system</h4>
 * 

 * 
 * Again, assembling the system matrix and right hand side follows the same
 * structure as in many example programs before. In particular, it is mostly
 * equivalent to @ref step_17 "step-17", except for the different right hand side that now
 * only has to take into account internal stresses. In addition, assembling
 * the matrix is made significantly more transparent by using the
 * <code>SymmetricTensor</code> class: note the elegance of forming the
 * scalar products of symmetric tensors of rank 2 and 4. The implementation
 * is also more general since it is independent of the fact that we may or
 * may not be using an isotropic elasticity tensor.
 *   

 * 
 * The first part of the assembly routine is as always:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::assemble_system()
 *   {
 *     system_rhs    = 0;
 *     system_matrix = 0;
 * 
 *     FEValues<dim> fe_values(fe,
 *                             quadrature_formula,
 *                             update_values | update_gradients |
 *                               update_quadrature_points | update_JxW_values);
 * 
 *     const unsigned int dofs_per_cell = fe.dofs_per_cell;
 *     const unsigned int n_q_points    = quadrature_formula.size();
 * 
 *     FullMatrix<double> cell_matrix(dofs_per_cell, dofs_per_cell);
 *     Vector<double>     cell_rhs(dofs_per_cell);
 * 
 *     std::vector<types::global_dof_index> local_dof_indices(dofs_per_cell);
 * 
 *     BodyForce<dim>              body_force;
 *     std::vector<Vector<double>> body_force_values(n_q_points,
 *                                                   Vector<double>(dim));
 * 
 * @endcode
 * 
 * As in @ref step_17 "step-17", we only need to loop over all cells that belong to the
 * present processor:
 * 
 * @code
 *     for (const auto &cell : dof_handler.active_cell_iterators())
 *       if (cell->is_locally_owned())
 *         {
 *           cell_matrix = 0;
 *           cell_rhs    = 0;
 * 
 *           fe_values.reinit(cell);
 * 
 * @endcode
 * 
 * Then loop over all indices i,j and quadrature points and assemble
 * the system matrix contributions from this cell.  Note how we
 * extract the symmetric gradients (strains) of the shape functions
 * at a given quadrature point from the <code>FEValues</code>
 * object, and the elegance with which we form the triple
 * contraction <code>eps_phi_i : C : eps_phi_j</code>; the latter
 * needs to be compared to the clumsy computations needed in
 * @ref step_17 "step-17", both in the introduction as well as in the respective
 * place in the program:
 * 
 * @code
 *           for (unsigned int i = 0; i < dofs_per_cell; ++i)
 *             for (unsigned int j = 0; j < dofs_per_cell; ++j)
 *               for (unsigned int q_point = 0; q_point < n_q_points; ++q_point)
 *                 {
 *                   const SymmetricTensor<2, dim>
 *                     eps_phi_i = get_strain(fe_values, i, q_point),
 *                     eps_phi_j = get_strain(fe_values, j, q_point);
 * 
 *                   cell_matrix(i, j) += (eps_phi_i *            
 *                                         stress_strain_tensor * 
 *                                         eps_phi_j              
 *                                         ) *                    
 *                                        fe_values.JxW(q_point); 
 *                 }
 * 
 * 
 * @endcode
 * 
 * Then also assemble the local right hand side contributions. For
 * this, we need to access the prior stress value in this quadrature
 * point. To get it, we use the user pointer of this cell that
 * points into the global array to the quadrature point data
 * corresponding to the first quadrature point of the present cell,
 * and then add an offset corresponding to the index of the
 * quadrature point we presently consider:
 * 
 * @code
 *           const PointHistory<dim> *local_quadrature_points_data =
 *             reinterpret_cast<PointHistory<dim> *>(cell->user_pointer());
 * @endcode
 * 
 * In addition, we need the values of the external body forces at
 * the quadrature points on this cell:
 * 
 * @code
 *           body_force.vector_value_list(fe_values.get_quadrature_points(),
 *                                        body_force_values);
 * @endcode
 * 
 * Then we can loop over all degrees of freedom on this cell and
 * compute local contributions to the right hand side:
 * 
 * @code
 *           for (unsigned int i = 0; i < dofs_per_cell; ++i)
 *             {
 *               const unsigned int component_i =
 *                 fe.system_to_component_index(i).first;
 * 
 *               for (unsigned int q_point = 0; q_point < n_q_points; ++q_point)
 *                 {
 *                   const SymmetricTensor<2, dim> &old_stress =
 *                     local_quadrature_points_data[q_point].old_stress;
 * 
 *                   cell_rhs(i) +=
 *                     (body_force_values[q_point](component_i) *
 *                        fe_values.shape_value(i, q_point) -
 *                      old_stress * get_strain(fe_values, i, q_point)) *
 *                     fe_values.JxW(q_point);
 *                 }
 *             }
 * 
 * @endcode
 * 
 * Now that we have the local contributions to the linear system, we
 * need to transfer it into the global objects. This is done exactly
 * as in @ref step_17 "step-17":
 * 
 * @code
 *           cell->get_dof_indices(local_dof_indices);
 * 
 *           hanging_node_constraints.distribute_local_to_global(cell_matrix,
 *                                                               cell_rhs,
 *                                                               local_dof_indices,
 *                                                               system_matrix,
 *                                                               system_rhs);
 *         }
 * 
 * @endcode
 * 
 * Now compress the vector and the system matrix:
 * 
 * @code
 *     system_matrix.compress(VectorOperation::add);
 *     system_rhs.compress(VectorOperation::add);
 * 
 * 
 * @endcode
 * 
 * The last step is to again fix up boundary values, just as we already
 * did in previous programs. A slight complication is that the
 * <code>apply_boundary_values</code> function wants to have a solution
 * vector compatible with the matrix and right hand side (i.e. here a
 * distributed %parallel vector, rather than the sequential vector we use
 * in this program) in order to preset the entries of the solution vector
 * with the correct boundary values. We provide such a compatible vector
 * in the form of a temporary vector which we then copy into the
 * sequential one.
 * 

 * 
 * We make up for this complication by showing how boundary values can be
 * used flexibly: following the way we create the triangulation, there are
 * three distinct boundary indicators used to describe the domain,
 * corresponding to the bottom and top faces, as well as the inner/outer
 * surfaces. We would like to impose boundary conditions of the following
 * type: The inner and outer cylinder surfaces are free of external
 * forces, a fact that corresponds to natural (Neumann-type) boundary
 * conditions for which we don't have to do anything. At the bottom, we
 * want no movement at all, corresponding to the cylinder being clamped or
 * cemented in at this part of the boundary. At the top, however, we want
 * a prescribed vertical downward motion compressing the cylinder; in
 * addition, we only want to restrict the vertical movement, but not the
 * horizontal ones -- one can think of this situation as a well-greased
 * plate sitting on top of the cylinder pushing it downwards: the atoms of
 * the cylinder are forced to move downward, but they are free to slide
 * horizontally along the plate.
 * 

 * 
 * The way to describe this is as follows: for boundary indicator zero
 * (bottom face) we use a dim-dimensional zero function representing no
 * motion in any coordinate direction. For the boundary with indicator 1
 * (top surface), we use the <code>IncrementalBoundaryValues</code> class,
 * but we specify an additional argument to the
 * <code>VectorTools::interpolate_boundary_values</code> function denoting
 * which vector components it should apply to; this is a vector of bools
 * for each vector component and because we only want to restrict vertical
 * motion, it has only its last component set:
 * 
 * @code
 *     FEValuesExtractors::Scalar                z_component(dim - 1);
 *     std::map<types::global_dof_index, double> boundary_values;
 *     VectorTools::interpolate_boundary_values(dof_handler,
 *                                              0,
 *                                              Functions::ZeroFunction<dim>(dim),
 *                                              boundary_values);
 *     VectorTools::interpolate_boundary_values(
 *       dof_handler,
 *       1,
 *       IncrementalBoundaryValues<dim>(present_time, present_timestep),
 *       boundary_values,
 *       fe.component_mask(z_component));
 * 
 *     PETScWrappers::MPI::Vector tmp(locally_owned_dofs, mpi_communicator);
 *     MatrixTools::apply_boundary_values(
 *       boundary_values, system_matrix, tmp, system_rhs, false);
 *     incremental_displacement = tmp;
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelsolve_timestep"></a> 
 * <h4>TopLevel::solve_timestep</h4>
 * 

 * 
 * The next function is the one that controls what all has to happen within
 * a timestep. The order of things should be relatively self-explanatory
 * from the function names:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::solve_timestep()
 *   {
 *     pcout << "    Assembling system..." << std::flush;
 *     assemble_system();
 *     pcout << " norm of rhs is " << system_rhs.l2_norm() << std::endl;
 * 
 *     const unsigned int n_iterations = solve_linear_problem();
 * 
 *     pcout << "    Solver converged in " << n_iterations << " iterations."
 *           << std::endl;
 * 
 *     pcout << "    Updating quadrature point data..." << std::flush;
 *     update_quadrature_point_history();
 *     pcout << std::endl;
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelsolve_linear_problem"></a> 
 * <h4>TopLevel::solve_linear_problem</h4>
 * 

 * 
 * Solving the linear system again works mostly as before. The only
 * difference is that we want to only keep a complete local copy of the
 * solution vector instead of the distributed one that we get as output from
 * PETSc's solver routines. To this end, we declare a local temporary
 * variable for the distributed vector and initialize it with the contents
 * of the local variable (remember that the
 * <code>apply_boundary_values</code> function called in
 * <code>assemble_system</code> preset the values of boundary nodes in this
 * vector), solve with it, and at the end of the function copy it again into
 * the complete local vector that we declared as a member variable. Hanging
 * node constraints are then distributed only on the local copy,
 * i.e. independently of each other on each of the processors:
 * 
 * @code
 *   template <int dim>
 *   unsigned int TopLevel<dim>::solve_linear_problem()
 *   {
 *     PETScWrappers::MPI::Vector distributed_incremental_displacement(
 *       locally_owned_dofs, mpi_communicator);
 *     distributed_incremental_displacement = incremental_displacement;
 * 
 *     SolverControl solver_control(dof_handler.n_dofs(),
 *                                  1e-16 * system_rhs.l2_norm());
 * 
 *     PETScWrappers::SolverCG cg(solver_control, mpi_communicator);
 * 
 *     PETScWrappers::PreconditionBlockJacobi preconditioner(system_matrix);
 * 
 *     cg.solve(system_matrix,
 *              distributed_incremental_displacement,
 *              system_rhs,
 *              preconditioner);
 * 
 *     incremental_displacement = distributed_incremental_displacement;
 * 
 *     hanging_node_constraints.distribute(incremental_displacement);
 * 
 *     return solver_control.last_step();
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLeveloutput_results"></a> 
 * <h4>TopLevel::output_results</h4>
 * 

 * 
 * This function generates the graphical output in .vtu format as explained
 * in the introduction. Each process will only work on the cells it owns,
 * and then write the result into a file of its own. Additionally, processor
 * 0 will write the record files the reference all the .vtu files.
 *   

 * 
 * The crucial part of this function is to give the <code>DataOut</code>
 * class a way to only work on the cells that the present process owns.
 * 

 * 
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::output_results() const
 *   {
 *     DataOut<dim> data_out;
 *     data_out.attach_dof_handler(dof_handler);
 * 
 * @endcode
 * 
 * Then, just as in @ref step_17 "step-17", define the names of solution variables (which
 * here are the displacement increments) and queue the solution vector for
 * output. Note in the following switch how we make sure that if the space
 * dimension should be unhandled that we throw an exception saying that we
 * haven't implemented this case yet (another case of defensive
 * programming):
 * 
 * @code
 *     std::vector<std::string> solution_names;
 *     switch (dim)
 *       {
 *         case 1:
 *           solution_names.emplace_back("delta_x");
 *           break;
 *         case 2:
 *           solution_names.emplace_back("delta_x");
 *           solution_names.emplace_back("delta_y");
 *           break;
 *         case 3:
 *           solution_names.emplace_back("delta_x");
 *           solution_names.emplace_back("delta_y");
 *           solution_names.emplace_back("delta_z");
 *           break;
 *         default:
 *           Assert(false, ExcNotImplemented());
 *       }
 * 
 *     data_out.add_data_vector(incremental_displacement, solution_names);
 * 
 * 
 * @endcode
 * 
 * The next thing is that we wanted to output something like the average
 * norm of the stresses that we have stored in each cell. This may seem
 * complicated, since on the present processor we only store the stresses
 * in quadrature points on those cells that actually belong to the present
 * process. In other words, it seems as if we can't compute the average
 * stresses for all cells. However, remember that our class derived from
 * <code>DataOut</code> only iterates over those cells that actually do
 * belong to the present processor, i.e. we don't have to compute anything
 * for all the other cells as this information would not be touched. The
 * following little loop does this. We enclose the entire block into a
 * pair of braces to make sure that the iterator variables do not remain
 * accidentally visible beyond the end of the block in which they are
 * used:
 * 
 * @code
 *     Vector<double> norm_of_stress(triangulation.n_active_cells());
 *     {
 * @endcode
 * 
 * Loop over all the cells...
 * 
 * @code
 *       for (auto &cell : triangulation.active_cell_iterators())
 *         if (cell->is_locally_owned())
 *           {
 * @endcode
 * 
 * On these cells, add up the stresses over all quadrature
 * points...
 * 
 * @code
 *             SymmetricTensor<2, dim> accumulated_stress;
 *             for (unsigned int q = 0; q < quadrature_formula.size(); ++q)
 *               accumulated_stress +=
 *                 reinterpret_cast<PointHistory<dim> *>(cell->user_pointer())[q]
 *                   .old_stress;
 * 
 * @endcode
 * 
 * ...then write the norm of the average to their destination:
 * 
 * @code
 *             norm_of_stress(cell->active_cell_index()) =
 *               (accumulated_stress / quadrature_formula.size()).norm();
 *           }
 * @endcode
 * 
 * And on the cells that we are not interested in, set the respective
 * value in the vector to a bogus value (norms must be positive, and a
 * large negative value should catch your eye) in order to make sure
 * that if we were somehow wrong about our assumption that these
 * elements would not appear in the output file, that we would find out
 * by looking at the graphical output:
 * 
 * @code
 *         else
 *           norm_of_stress(cell->active_cell_index()) = -1e+20;
 *     }
 * @endcode
 * 
 * Finally attach this vector as well to be treated for output:
 * 
 * @code
 *     data_out.add_data_vector(norm_of_stress, "norm_of_stress");
 * 
 * @endcode
 * 
 * As a last piece of data, let us also add the partitioning of the domain
 * into subdomains associated with the processors if this is a parallel
 * job. This works in the exact same way as in the @ref step_17 "step-17" program:
 * 
 * @code
 *     std::vector<types::subdomain_id> partition_int(
 *       triangulation.n_active_cells());
 *     GridTools::get_subdomain_association(triangulation, partition_int);
 *     const Vector<double> partitioning(partition_int.begin(),
 *                                       partition_int.end());
 *     data_out.add_data_vector(partitioning, "partitioning");
 * 
 * @endcode
 * 
 * Finally, with all this data, we can instruct deal.II to munge the
 * information and produce some intermediate data structures that contain
 * all these solution and other data vectors:
 * 
 * @code
 *     data_out.build_patches();
 * 
 * @endcode
 * 
 * Let us call a function that opens the necessary output files and writes
 * the data we have generated into them. The function automatically
 * constructs the file names from the given directory name (the first
 * argument) and file name base (second argument). It augments the resulting
 * string by pieces that result from the time step number and a "piece
 * number" that corresponds to a part of the overall domain that can consist
 * of one or more subdomains.
 *     

 * 
 * The function also writes a record files (with suffix `.pvd`) for Paraview
 * that describes how all of these output files combine into the data for
 * this single time step:
 * 
 * @code
 *     const std::string pvtu_master_filename =
 *       data_out.write_vtu_with_pvtu_record(
 *         "./", "solution", timestep_no, mpi_communicator, 4);
 * 
 * @endcode
 * 
 * The record files must be written only once and not by each processor,
 * so we do this on processor 0:
 * 
 * @code
 *     if (this_mpi_process == 0)
 *       {
 * @endcode
 * 
 * Finally, we write the paraview record, that references all .pvtu
 * files and their respective time. Note that the variable
 * times_and_names is declared static, so it will retain the entries
 * from the previous timesteps.
 * 
 * @code
 *         static std::vector<std::pair<double, std::string>> times_and_names;
 *         times_and_names.push_back(
 *           std::pair<double, std::string>(present_time, pvtu_master_filename));
 *         std::ofstream pvd_output("solution.pvd");
 *         DataOutBase::write_pvd_record(pvd_output, times_and_names);
 *       }
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLeveldo_initial_timestep"></a> 
 * <h4>TopLevel::do_initial_timestep</h4>
 * 

 * 
 * This and the next function handle the overall structure of the first and
 * following timesteps, respectively. The first timestep is slightly more
 * involved because we want to compute it multiple times on successively
 * refined meshes, each time starting from a clean state. At the end of
 * these computations, in which we compute the incremental displacements
 * each time, we use the last results obtained for the incremental
 * displacements to compute the resulting stress updates and move the mesh
 * accordingly. On this new mesh, we then output the solution and any
 * additional data we consider important.
 *   

 * 
 * All this is interspersed by generating output to the console to update
 * the person watching the screen on what is going on. As in @ref step_17 "step-17", the
 * use of <code>pcout</code> instead of <code>std::cout</code> makes sure
 * that only one of the parallel processes is actually writing to the
 * console, without having to explicitly code an if-statement in each place
 * where we generate output:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::do_initial_timestep()
 *   {
 *     present_time += present_timestep;
 *     ++timestep_no;
 *     pcout << "Timestep " << timestep_no << " at time " << present_time
 *           << std::endl;
 * 
 *     for (unsigned int cycle = 0; cycle < 2; ++cycle)
 *       {
 *         pcout << "  Cycle " << cycle << ':' << std::endl;
 * 
 *         if (cycle == 0)
 *           create_coarse_grid();
 *         else
 *           refine_initial_grid();
 * 
 *         pcout << "    Number of active cells:       "
 *               << triangulation.n_active_cells() << " (by partition:";
 *         for (unsigned int p = 0; p < n_mpi_processes; ++p)
 *           pcout << (p == 0 ? ' ' : '+')
 *                 << (GridTools::count_cells_with_subdomain_association(
 *                      triangulation, p));
 *         pcout << ")" << std::endl;
 * 
 *         setup_system();
 * 
 *         pcout << "    Number of degrees of freedom: " << dof_handler.n_dofs()
 *               << " (by partition:";
 *         for (unsigned int p = 0; p < n_mpi_processes; ++p)
 *           pcout << (p == 0 ? ' ' : '+')
 *                 << (DoFTools::count_dofs_with_subdomain_association(dof_handler,
 *                                                                     p));
 *         pcout << ")" << std::endl;
 * 
 *         solve_timestep();
 *       }
 * 
 *     move_mesh();
 *     output_results();
 * 
 *     pcout << std::endl;
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLeveldo_timestep"></a> 
 * <h4>TopLevel::do_timestep</h4>
 * 

 * 
 * Subsequent timesteps are simpler, and probably do not require any more
 * documentation given the explanations for the previous function above:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::do_timestep()
 *   {
 *     present_time += present_timestep;
 *     ++timestep_no;
 *     pcout << "Timestep " << timestep_no << " at time " << present_time
 *           << std::endl;
 *     if (present_time > end_time)
 *       {
 *         present_timestep -= (present_time - end_time);
 *         present_time = end_time;
 *       }
 * 
 * 
 *     solve_timestep();
 * 
 *     move_mesh();
 *     output_results();
 * 
 *     pcout << std::endl;
 *   }
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelrefine_initial_grid"></a> 
 * <h4>TopLevel::refine_initial_grid</h4>
 * 

 * 
 * The following function is called when solving the first time step on
 * successively refined meshes. After each iteration, it computes a
 * refinement criterion, refines the mesh, and sets up the history variables
 * in each quadrature point again to a clean state.
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::refine_initial_grid()
 *   {
 * @endcode
 * 
 * First, let each process compute error indicators for the cells it owns:
 * 
 * @code
 *     Vector<float> error_per_cell(triangulation.n_active_cells());
 *     KellyErrorEstimator<dim>::estimate(
 *       dof_handler,
 *       QGauss<dim - 1>(fe.degree + 1),
 *       std::map<types::boundary_id, const Function<dim> *>(),
 *       incremental_displacement,
 *       error_per_cell,
 *       ComponentMask(),
 *       nullptr,
 *       MultithreadInfo::n_threads(),
 *       this_mpi_process);
 * 
 * @endcode
 * 
 * Then set up a global vector into which we merge the local indicators
 * from each of the %parallel processes:
 * 
 * @code
 *     const unsigned int n_local_cells =
 *       triangulation.n_locally_owned_active_cells();
 * 
 *     PETScWrappers::MPI::Vector distributed_error_per_cell(
 *       mpi_communicator, triangulation.n_active_cells(), n_local_cells);
 * 
 *     for (unsigned int i = 0; i < error_per_cell.size(); ++i)
 *       if (error_per_cell(i) != 0)
 *         distributed_error_per_cell(i) = error_per_cell(i);
 *     distributed_error_per_cell.compress(VectorOperation::insert);
 * 
 * @endcode
 * 
 * Once we have that, copy it back into local copies on all processors and
 * refine the mesh accordingly:
 * 
 * @code
 *     error_per_cell = distributed_error_per_cell;
 *     GridRefinement::refine_and_coarsen_fixed_number(triangulation,
 *                                                     error_per_cell,
 *                                                     0.35,
 *                                                     0.03);
 *     triangulation.execute_coarsening_and_refinement();
 * 
 * @endcode
 * 
 * Finally, set up quadrature point data again on the new mesh, and only
 * on those cells that we have determined to be ours:
 * 
 * @code
 *     setup_quadrature_point_history();
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelmove_mesh"></a> 
 * <h4>TopLevel::move_mesh</h4>
 * 

 * 
 * At the end of each time step, we move the nodes of the mesh according to
 * the incremental displacements computed in this time step. To do this, we
 * keep a vector of flags that indicate for each vertex whether we have
 * already moved it around, and then loop over all cells and move those
 * vertices of the cell that have not been moved yet. It is worth noting
 * that it does not matter from which of the cells adjacent to a vertex we
 * move this vertex: since we compute the displacement using a continuous
 * finite element, the displacement field is continuous as well and we can
 * compute the displacement of a given vertex from each of the adjacent
 * cells. We only have to make sure that we move each node exactly once,
 * which is why we keep the vector of flags.
 *   

 * 
 * There are two noteworthy things in this function. First, how we get the
 * displacement field at a given vertex using the
 * <code>cell-@>vertex_dof_index(v,d)</code> function that returns the index
 * of the <code>d</code>th degree of freedom at vertex <code>v</code> of the
 * given cell. In the present case, displacement in the k-th coordinate
 * direction corresponds to the k-th component of the finite element. Using a
 * function like this bears a certain risk, because it uses knowledge of the
 * order of elements that we have taken together for this program in the
 * <code>FESystem</code> element. If we decided to add an additional
 * variable, for example a pressure variable for stabilization, and happened
 * to insert it as the first variable of the element, then the computation
 * below will start to produce nonsensical results. In addition, this
 * computation rests on other assumptions: first, that the element we use
 * has, indeed, degrees of freedom that are associated with vertices. This
 * is indeed the case for the present Q1 element, as would be for all Qp
 * elements of polynomial order <code>p</code>. However, it would not hold
 * for discontinuous elements, or elements for mixed formulations. Secondly,
 * it also rests on the assumption that the displacement at a vertex is
 * determined solely by the value of the degree of freedom associated with
 * this vertex; in other words, all shape functions corresponding to other
 * degrees of freedom are zero at this particular vertex. Again, this is the
 * case for the present element, but is not so for all elements that are
 * presently available in deal.II. Despite its risks, we choose to use this
 * way in order to present a way to query individual degrees of freedom
 * associated with vertices.
 *   

 * 
 * In this context, it is instructive to point out what a more general way
 * would be. For general finite elements, the way to go would be to take a
 * quadrature formula with the quadrature points in the vertices of a
 * cell. The <code>QTrapez</code> formula for the trapezoidal rule does
 * exactly this. With this quadrature formula, we would then initialize an
 * <code>FEValues</code> object in each cell, and use the
 * <code>FEValues::get_function_values</code> function to obtain the values
 * of the solution function in the quadrature points, i.e. the vertices of
 * the cell. These are the only values that we really need, i.e. we are not
 * at all interested in the weights (or the <code>JxW</code> values)
 * associated with this particular quadrature formula, and this can be
 * specified as the last argument in the constructor to
 * <code>FEValues</code>. The only point of minor inconvenience in this
 * scheme is that we have to figure out which quadrature point corresponds
 * to the vertex we consider at present, as they may or may not be ordered
 * in the same order.
 *   

 * 
 * This inconvenience could be avoided if finite elements have support
 * points on vertices (which the one here has; for the concept of support
 * points, see @ref GlossSupport "support points"). For such a case, one
 * could construct a custom quadrature rule using
 * FiniteElement::get_unit_support_points(). The first
 * <code>GeometryInfo@<dim@>::%vertices_per_cell*fe.dofs_per_vertex</code>
 * quadrature points will then correspond to the vertices of the cell and
 * are ordered consistent with <code>cell-@>vertex(i)</code>, taking into
 * account that support points for vector elements will be duplicated
 * <code>fe.dofs_per_vertex</code> times.
 *   

 * 
 * Another point worth explaining about this short function is the way in
 * which the triangulation class exports information about its vertices:
 * through the <code>Triangulation::n_vertices</code> function, it
 * advertises how many vertices there are in the triangulation. Not all of
 * them are actually in use all the time -- some are left-overs from cells
 * that have been coarsened previously and remain in existence since deal.II
 * never changes the number of a vertex once it has come into existence,
 * even if vertices with lower number go away. Secondly, the location
 * returned by <code>cell-@>vertex(v)</code> is not only a read-only object
 * of type <code>Point@<dim@></code>, but in fact a reference that can be
 * written to. This allows to move around the nodes of a mesh with relative
 * ease, but it is worth pointing out that it is the responsibility of an
 * application program using this feature to make sure that the resulting
 * cells are still useful, i.e. are not distorted so much that the cell is
 * degenerated (indicated, for example, by negative Jacobians). Note that we
 * do not have any provisions in this function to actually ensure this, we
 * just have faith.
 *   

 * 
 * After this lengthy introduction, here are the full 20 or so lines of
 * code:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::move_mesh()
 *   {
 *     pcout << "    Moving mesh..." << std::endl;
 * 
 *     std::vector<bool> vertex_touched(triangulation.n_vertices(), false);
 *     for (auto &cell : dof_handler.active_cell_iterators())
 *       for (unsigned int v = 0; v < GeometryInfo<dim>::vertices_per_cell; ++v)
 *         if (vertex_touched[cell->vertex_index(v)] == false)
 *           {
 *             vertex_touched[cell->vertex_index(v)] = true;
 * 
 *             Point<dim> vertex_displacement;
 *             for (unsigned int d = 0; d < dim; ++d)
 *               vertex_displacement[d] =
 *                 incremental_displacement(cell->vertex_dof_index(v, d));
 * 
 *             cell->vertex(v) += vertex_displacement;
 *           }
 *   }
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelsetup_quadrature_point_history"></a> 
 * <h4>TopLevel::setup_quadrature_point_history</h4>
 * 

 * 
 * At the beginning of our computations, we needed to set up initial values
 * of the history variables, such as the existing stresses in the material,
 * that we store in each quadrature point. As mentioned above, we use the
 * <code>user_pointer</code> for this that is available in each cell.
 *   

 * 
 * To put this into larger perspective, we note that if we had previously
 * available stresses in our model (which we assume do not exist for the
 * purpose of this program), then we would need to interpolate the field of
 * preexisting stresses to the quadrature points. Likewise, if we were to
 * simulate elasto-plastic materials with hardening/softening, then we would
 * have to store additional history variables like the present yield stress
 * of the accumulated plastic strains in each quadrature
 * points. Pre-existing hardening or weakening would then be implemented by
 * interpolating these variables in the present function as well.
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::setup_quadrature_point_history()
 *   {
 * @endcode
 * 
 * For good measure, we set all user pointers of all cells, whether
 * ours of not, to the null pointer. This way, if we ever access the user
 * pointer of a cell which we should not have accessed, a segmentation
 * fault will let us know that this should not have happened:
 * 

 * 
 * 
 * @code
 *     triangulation.clear_user_data();
 * 
 * @endcode
 * 
 * Next, allocate the quadrature objects that are within the responsibility
 * of this processor. This, of course, equals the number of cells that
 * belong to this processor times the number of quadrature points our
 * quadrature formula has on each cell. Since the `resize()` function does
 * not actually shrink the amount of allocated memory if the requested new
 * size is smaller than the old size, we resort to a trick to first free all
 * memory, and then reallocate it: we declare an empty vector as a temporary
 * variable and then swap the contents of the old vector and this temporary
 * variable. This makes sure that the `quadrature_point_history` is now
 * really empty, and we can let the temporary variable that now holds the
 * previous contents of the vector go out of scope and be destroyed. In the
 * next step we can then re-allocate as many elements as we need, with the
 * vector default-initializing the `PointHistory` objects, which includes
 * setting the stress variables to zero.
 * 
 * @code
 *     {
 *       std::vector<PointHistory<dim>> tmp;
 *       quadrature_point_history.swap(tmp);
 *     }
 *     quadrature_point_history.resize(
 *       triangulation.n_locally_owned_active_cells() * quadrature_formula.size());
 * 
 * @endcode
 * 
 * Finally loop over all cells again and set the user pointers from the
 * cells that belong to the present processor to point to the first
 * quadrature point objects corresponding to this cell in the vector of
 * such objects:
 * 
 * @code
 *     unsigned int history_index = 0;
 *     for (auto &cell : triangulation.active_cell_iterators())
 *       if (cell->is_locally_owned())
 *         {
 *           cell->set_user_pointer(&quadrature_point_history[history_index]);
 *           history_index += quadrature_formula.size();
 *         }
 * 
 * @endcode
 * 
 * At the end, for good measure make sure that our count of elements was
 * correct and that we have both used up all objects we allocated
 * previously, and not point to any objects beyond the end of the
 * vector. Such defensive programming strategies are always good checks to
 * avoid accidental errors and to guard against future changes to this
 * function that forget to update all uses of a variable at the same
 * time. Recall that constructs using the <code>Assert</code> macro are
 * optimized away in optimized mode, so do not affect the run time of
 * optimized runs:
 * 
 * @code
 *     Assert(history_index == quadrature_point_history.size(),
 *            ExcInternalError());
 *   }
 * 
 * 
 * 
 * @endcode
 * 
 * 
 * <a name="TopLevelupdate_quadrature_point_history"></a> 
 * <h4>TopLevel::update_quadrature_point_history</h4>
 * 

 * 
 * At the end of each time step, we should have computed an incremental
 * displacement update so that the material in its new configuration
 * accommodates for the difference between the external body and boundary
 * forces applied during this time step minus the forces exerted through
 * preexisting internal stresses. In order to have the preexisting
 * stresses available at the next time step, we therefore have to update the
 * preexisting stresses with the stresses due to the incremental
 * displacement computed during the present time step. Ideally, the
 * resulting sum of internal stresses would exactly counter all external
 * forces. Indeed, a simple experiment can make sure that this is so: if we
 * choose boundary conditions and body forces to be time independent, then
 * the forcing terms (the sum of external forces and internal stresses)
 * should be exactly zero. If you make this experiment, you will realize
 * from the output of the norm of the right hand side in each time step that
 * this is almost the case: it is not exactly zero, since in the first time
 * step the incremental displacement and stress updates were computed
 * relative to the undeformed mesh, which was then deformed. In the second
 * time step, we again compute displacement and stress updates, but this
 * time in the deformed mesh -- there, the resulting updates are very small
 * but not quite zero. This can be iterated, and in each such iteration the
 * residual, i.e. the norm of the right hand side vector, is reduced; if one
 * makes this little experiment, one realizes that the norm of this residual
 * decays exponentially with the number of iterations, and after an initial
 * very rapid decline is reduced by roughly a factor of about 3.5 in each
 * iteration (for one testcase I looked at, other testcases, and other
 * numbers of unknowns change the factor, but not the exponential decay).
 * 

 * 
 * In a sense, this can then be considered as a quasi-timestepping scheme to
 * resolve the nonlinear problem of solving large-deformation elasticity on
 * a mesh that is moved along in a Lagrangian manner.
 *   

 * 
 * Another complication is that the existing (old) stresses are defined on
 * the old mesh, which we will move around after updating the stresses. If
 * this mesh update involves rotations of the cell, then we need to also
 * rotate the updated stress, since it was computed relative to the
 * coordinate system of the old cell.
 *   

 * 
 * Thus, what we need is the following: on each cell which the present
 * processor owns, we need to extract the old stress from the data stored
 * with each quadrature point, compute the stress update, add the two
 * together, and then rotate the result together with the incremental
 * rotation computed from the incremental displacement at the present
 * quadrature point. We will detail these steps below:
 * 
 * @code
 *   template <int dim>
 *   void TopLevel<dim>::update_quadrature_point_history()
 *   {
 * @endcode
 * 
 * First, set up an <code>FEValues</code> object by which we will evaluate
 * the incremental displacements and the gradients thereof at the
 * quadrature points, together with a vector that will hold this
 * information:
 * 
 * @code
 *     FEValues<dim> fe_values(fe,
 *                             quadrature_formula,
 *                             update_values | update_gradients);
 * 
 *     std::vector<std::vector<Tensor<1, dim>>> displacement_increment_grads(
 *       quadrature_formula.size(), std::vector<Tensor<1, dim>>(dim));
 * 
 * @endcode
 * 
 * Then loop over all cells and do the job in the cells that belong to our
 * subdomain:
 * 
 * @code
 *     for (auto &cell : dof_handler.active_cell_iterators())
 *       if (cell->is_locally_owned())
 *         {
 * @endcode
 * 
 * Next, get a pointer to the quadrature point history data local to
 * the present cell, and, as a defensive measure, make sure that
 * this pointer is within the bounds of the global array:
 * 
 * @code
 *           PointHistory<dim> *local_quadrature_points_history =
 *             reinterpret_cast<PointHistory<dim> *>(cell->user_pointer());
 *           Assert(local_quadrature_points_history >=
 *                    &quadrature_point_history.front(),
 *                  ExcInternalError());
 *           Assert(local_quadrature_points_history <=
 *                    &quadrature_point_history.back(),
 *                  ExcInternalError());
 * 
 * @endcode
 * 
 * Then initialize the <code>FEValues</code> object on the present
 * cell, and extract the gradients of the displacement at the
 * quadrature points for later computation of the strains
 * 
 * @code
 *           fe_values.reinit(cell);
 *           fe_values.get_function_gradients(incremental_displacement,
 *                                            displacement_increment_grads);
 * 
 * @endcode
 * 
 * Then loop over the quadrature points of this cell:
 * 
 * @code
 *           for (unsigned int q = 0; q < quadrature_formula.size(); ++q)
 *             {
 * @endcode
 * 
 * On each quadrature point, compute the strain increment from
 * the gradients, and multiply it by the stress-strain tensor to
 * get the stress update. Then add this update to the already
 * existing strain at this point:
 * 
 * @code
 *               const SymmetricTensor<2, dim> new_stress =
 *                 (local_quadrature_points_history[q].old_stress +
 *                  (stress_strain_tensor *
 *                   get_strain(displacement_increment_grads[q])));
 * 
 * @endcode
 * 
 * Finally, we have to rotate the result. For this, we first
 * have to compute a rotation matrix at the present quadrature
 * point from the incremental displacements. In fact, it can be
 * computed from the gradients, and we already have a function
 * for that purpose:
 * 
 * @code
 *               const Tensor<2, dim> rotation =
 *                 get_rotation_matrix(displacement_increment_grads[q]);
 * @endcode
 * 
 * Note that the result, a rotation matrix, is in general an
 * antisymmetric tensor of rank 2, so we must store it as a full
 * tensor.
 * 

 * 
 * With this rotation matrix, we can compute the rotated tensor
 * by contraction from the left and right, after we expand the
 * symmetric tensor <code>new_stress</code> into a full tensor:
 * 
 * @code
 *               const SymmetricTensor<2, dim> rotated_new_stress =
 *                 symmetrize(transpose(rotation) *
 *                            static_cast<Tensor<2, dim>>(new_stress) * rotation);
 * @endcode
 * 
 * Note that while the result of the multiplication of these
 * three matrices should be symmetric, it is not due to floating
 * point round off: we get an asymmetry on the order of 1e-16 of
 * the off-diagonal elements of the result. When assigning the
 * result to a <code>SymmetricTensor</code>, the constructor of
 * that class checks the symmetry and realizes that it isn't
 * exactly symmetric; it will then raise an exception. To avoid
 * that, we explicitly symmetrize the result to make it exactly
 * symmetric.
 * 

 * 
 * The result of all these operations is then written back into
 * the original place:
 * 
 * @code
 *               local_quadrature_points_history[q].old_stress =
 *                 rotated_new_stress;
 *             }
 *         }
 *   }
 * 
 * @endcode
 * 
 * This ends the project specific namespace <code>Step18</code>. The rest is
 * as usual and as already shown in @ref step_17 "step-17": A <code>main()</code> function
 * that initializes and terminates PETSc, calls the classes that do the
 * actual work, and makes sure that we catch all exceptions that propagate
 * up to this point:
 * 
 * @code
 * } // namespace Step18
 * 
 * 
 * int main(int argc, char **argv)
 * {
 *   try
 *     {
 *       using namespace dealii;
 *       using namespace Step18;
 * 
 *       Utilities::MPI::MPI_InitFinalize mpi_initialization(argc, argv, 1);
 * 
 *       TopLevel<3> elastic_problem;
 *       elastic_problem.run();
 *     }
 *   catch (std::exception &exc)
 *     {
 *       std::cerr << std::endl
 *                 << std::endl
 *                 << "----------------------------------------------------"
 *                 << std::endl;
 *       std::cerr << "Exception on processing: " << std::endl
 *                 << exc.what() << std::endl
 *                 << "Aborting!" << std::endl
 *                 << "----------------------------------------------------"
 *                 << std::endl;
 * 
 *       return 1;
 *     }
 *   catch (...)
 *     {
 *       std::cerr << std::endl
 *                 << std::endl
 *                 << "----------------------------------------------------"
 *                 << std::endl;
 *       std::cerr << "Unknown exception!" << std::endl
 *                 << "Aborting!" << std::endl
 *                 << "----------------------------------------------------"
 *                 << std::endl;
 *       return 1;
 *     }
 * 
 *   return 0;
 * }
 * @endcode
<a name="Results"></a><h1>Results</h1>



Running the program takes a good while if one uses debug mode; it takes about
eleven minutes on my i7 desktop. Fortunately, the version compiled with
optimizations is much faster; the program only takes about a minute and a half
after recompiling with the command <tt>make release</tt> on the same machine, a
much more reasonable time.


If run, the program prints the following output, explaining what it is
doing during all that time:
@verbatim
$ time make run
[ 66%] Built target step-18
[100%] Run step-18 with Release configuration
Timestep 1 at time 1
  Cycle 0:
    Number of active cells:       3712 (by partition: 3712)
    Number of degrees of freedom: 17226 (by partition: 17226)
    Assembling system... norm of rhs is 1.88062e+10
    Solver converged in 103 iterations.
    Updating quadrature point data...
  Cycle 1:
    Number of active cells:       12812 (by partition: 12812)
    Number of degrees of freedom: 51738 (by partition: 51738)
    Assembling system... norm of rhs is 1.86145e+10
    Solver converged in 121 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 2 at time 2
    Assembling system... norm of rhs is 1.84169e+10
    Solver converged in 122 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 3 at time 3
    Assembling system... norm of rhs is 1.82355e+10
    Solver converged in 122 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 4 at time 4
    Assembling system... norm of rhs is 1.80728e+10
    Solver converged in 117 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 5 at time 5
    Assembling system... norm of rhs is 1.79318e+10
    Solver converged in 116 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 6 at time 6
    Assembling system... norm of rhs is 1.78171e+10
    Solver converged in 115 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 7 at time 7
    Assembling system... norm of rhs is 1.7737e+10
    Solver converged in 112 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 8 at time 8
    Assembling system... norm of rhs is 1.77127e+10
    Solver converged in 111 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 9 at time 9
    Assembling system... norm of rhs is 1.78207e+10
    Solver converged in 113 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 10 at time 10
    Assembling system... norm of rhs is 1.83544e+10
    Solver converged in 115 iterations.
    Updating quadrature point data...
    Moving mesh...

[100%] Built target run
make run  176.82s user 0.15s system 198% cpu 1:28.94 total
@endverbatim
In other words, it is computing on 12,000 cells and with some 52,000
unknowns. Not a whole lot, but enough for a coupled three-dimensional
problem to keep a computer busy for a while. At the end of the day,
this is what we have for output:
@verbatim
$ ls -l *vtu *visit
-rw-r--r-- 1 drwells users 1706059 Feb 13 19:36 solution-0010.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:36 solution-0010.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:36 solution-0010.visit
-rw-r--r-- 1 drwells users 1707907 Feb 13 19:36 solution-0009.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:36 solution-0009.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:36 solution-0009.visit
-rw-r--r-- 1 drwells users 1703771 Feb 13 19:35 solution-0008.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0008.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0008.visit
-rw-r--r-- 1 drwells users 1693671 Feb 13 19:35 solution-0007.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0007.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0007.visit
-rw-r--r-- 1 drwells users 1681847 Feb 13 19:35 solution-0006.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0006.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0006.visit
-rw-r--r-- 1 drwells users 1670115 Feb 13 19:35 solution-0005.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0005.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0005.visit
-rw-r--r-- 1 drwells users 1658559 Feb 13 19:35 solution-0004.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0004.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0004.visit
-rw-r--r-- 1 drwells users 1639983 Feb 13 19:35 solution-0003.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0003.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0003.visit
-rw-r--r-- 1 drwells users 1625851 Feb 13 19:35 solution-0002.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:35 solution-0002.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:35 solution-0002.visit
-rw-r--r-- 1 drwells users 1616035 Feb 13 19:34 solution-0001.000.vtu
-rw-r--r-- 1 drwells users     761 Feb 13 19:34 solution-0001.pvtu
-rw-r--r-- 1 drwells users      33 Feb 13 19:34 solution-0001.visit
@endverbatim


If we visualize these files with VisIt or Paraview, we get to see the full picture
of the disaster our forced compression wreaks on the cylinder (colors in the
images encode the norm of the stress in the material):


<div class="threecolumn" style="width: 80%">
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0002.0000.png"
           alt="Time = 2"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 2
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0005.0000.png"
           alt="Time = 5"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 5
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0007.0000.png"
           alt="Time = 7"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 7
    </div>
  </div>
</div>


<div class="threecolumn" style="width: 80%">
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0008.0000.png"
           alt="Time = 8"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 8
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0009.0000.png"
           alt="Time = 9"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 9
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.sequential-0010.0000.png"
           alt="Time = 10"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 10
    </div>
  </div>
</div>


As is clearly visible, as we keep compressing the cylinder, it starts
to bow out near the fully constrained bottom surface and, after about eight
time units, buckle in an azimuthally symmetric manner.


Although the result appears plausible for the symmetric geometry and loading,
it is yet to be established whether or not the computation is fully converged.
In order to see whether it is, we ran the program again with one more global
refinement at the beginning and with the time step halved. This would have
taken a very long time on a single machine, so we used a proper workstation and
ran it on 16 processors in parallel. The beginning of the output now looks like
this:
@verbatim
Timestep 1 at time 0.5
  Cycle 0:
    Number of active cells:       29696 (by partition: 1808+1802+1894+1881+1870+1840+1884+1810+1876+1818+1870+1884+1854+1903+1816+1886)
    Number of degrees of freedom: 113100 (by partition: 6936+6930+7305+7116+7326+6869+7331+6786+7193+6829+7093+7162+6920+7280+6843+7181)
    Assembling system... norm of rhs is 1.10765e+10
    Solver converged in 209 iterations.
    Updating quadrature point data...
  Cycle 1:
    Number of active cells:       102034 (by partition: 6387+6202+6421+6341+6408+6201+6428+6428+6385+6294+6506+6244+6417+6527+6299+6546)
    Number of degrees of freedom: 359337 (by partition: 23255+21308+24774+24019+22304+21415+22430+22184+22298+21796+22396+21592+22325+22553+21977+22711)
    Assembling system... norm of rhs is 1.35759e+10
    Solver converged in 268 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 2 at time 1
    Assembling system... norm of rhs is 1.34674e+10
    Solver converged in 267 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 3 at time 1.5
    Assembling system... norm of rhs is 1.33607e+10
    Solver converged in 265 iterations.
    Updating quadrature point data...
    Moving mesh...

Timestep 4 at time 2
    Assembling system... norm of rhs is 1.32558e+10
    Solver converged in 263 iterations.
    Updating quadrature point data...
    Moving mesh...

[...]

Timestep 20 at time 10
    Assembling system... norm of rhs is 1.47755e+10
    Solver converged in 425 iterations.
    Updating quadrature point data...
    Moving mesh...
@endverbatim
That's quite a good number of unknowns, given that we are in 3d. The output of
this program are 16 files for each time step:
@verbatim
$ ls -l solution-0001*
-rw-r--r-- 1 wellsd2 user 761065 Feb 13 21:09 solution-0001.000.vtu
-rw-r--r-- 1 wellsd2 user 759277 Feb 13 21:09 solution-0001.001.vtu
-rw-r--r-- 1 wellsd2 user 761217 Feb 13 21:09 solution-0001.002.vtu
-rw-r--r-- 1 wellsd2 user 761605 Feb 13 21:09 solution-0001.003.vtu
-rw-r--r-- 1 wellsd2 user 756917 Feb 13 21:09 solution-0001.004.vtu
-rw-r--r-- 1 wellsd2 user 752669 Feb 13 21:09 solution-0001.005.vtu
-rw-r--r-- 1 wellsd2 user 735217 Feb 13 21:09 solution-0001.006.vtu
-rw-r--r-- 1 wellsd2 user 750065 Feb 13 21:09 solution-0001.007.vtu
-rw-r--r-- 1 wellsd2 user 760273 Feb 13 21:09 solution-0001.008.vtu
-rw-r--r-- 1 wellsd2 user 777265 Feb 13 21:09 solution-0001.009.vtu
-rw-r--r-- 1 wellsd2 user 772469 Feb 13 21:09 solution-0001.010.vtu
-rw-r--r-- 1 wellsd2 user 760833 Feb 13 21:09 solution-0001.011.vtu
-rw-r--r-- 1 wellsd2 user 782241 Feb 13 21:09 solution-0001.012.vtu
-rw-r--r-- 1 wellsd2 user 748905 Feb 13 21:09 solution-0001.013.vtu
-rw-r--r-- 1 wellsd2 user 738413 Feb 13 21:09 solution-0001.014.vtu
-rw-r--r-- 1 wellsd2 user 762133 Feb 13 21:09 solution-0001.015.vtu
-rw-r--r-- 1 wellsd2 user   1421 Feb 13 21:09 solution-0001.pvtu
-rw-r--r-- 1 wellsd2 user    364 Feb 13 21:09 solution-0001.visit
@endverbatim


Here are first the mesh on which we compute as well as the partitioning
for the 16 processors:


<div class="twocolumn" style="width: 80%">
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-000mesh.png"
           alt="Discretization"
           width="400">
    </div>
    <div class="text" align="center">
      Discretization
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0002.p.png"
           alt="Parallel partitioning"
           width="400">
    </div>
    <div class="text" align="center">
      Parallel partitioning
    </div>
  </div>
</div>


Finally, here is the same output as we have shown before for the much smaller
sequential case:

<div class="threecolumn" style="width: 80%">
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0002.s.png"
           alt="Time = 2"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 2
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0005.s.png"
           alt="Time = 5"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 5
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0007.s.png"
           alt="Time = 7"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 7
    </div>
  </div>
</div>


<div class="threecolumn" style="width: 80%">
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0008.s.png"
           alt="Time = 8"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 8
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0009.s.png"
           alt="Time = 9"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 9
    </div>
  </div>
  <div class="parent">
    <div class="img" align="center">
      <img src="https://www.dealii.org/images/steps/developer/step-18.parallel-0010.s.png"
           alt="Time = 10"
           width="400">
    </div>
    <div class="text" align="center">
      Time = 10
    </div>
  </div>
</div>


As before, we observe that at high axial compression the cylinder begins
to buckle, but this time ultimately collapses on itself. In contrast to our
first run, towards the end of the simulation the deflection pattern becomes
nonsymmetric (the central bulge deflects laterally). The model clearly does not
provide for this (all our forces and boundary deflections are symmetric) but the
effect is probably physically correct anyway: in reality, small inhomogeneities
in the body's material properties would lead it to buckle to one side
to evade the forcing; in numerical simulations, small perturbations
such as numerical round-off or an inexact solution of a linear system
by an iterative solver could have the same effect. Another typical source for
asymmetries in adaptive computations is that only a certain fraction of cells
is refined in each step, which may lead to asymmetric meshes even if the
original coarse mesh was symmetric.


If one compares this with the previous run, the results both qualitatively
and quantitatively different. The previous computation was
therefore certainly not converged, though we can't say for sure anything about
the present one. One would need an even finer computation to find out. However,
the point may be moot: looking at the last picture in detail, it is pretty
obvious that not only is the linear small deformation model we chose completely
inadequate, but for a realistic simulation we would also need to make sure that
the body does not intersect itself during deformation (if we continued
compressing the cylinder we would observe some self-intersection).
Without such a formulation we cannot expect anything to make physical sense,
even if it produces nice pictures!


<a name="Possibledirectionsforextensions"></a><h3>Possible directions for extensions</h3>


The program as is does not really solve an equation that has many applications
in practice: quasi-static material deformation based on a purely elastic law
is almost boring. However, the program may serve as the starting point for
more interesting experiments, and that indeed was the initial motivation for
writing it. Here are some suggestions of what the program is missing and in
what direction it may be extended:

<a name="Plasticitymodels"></a><h5>Plasticity models</h5>


 The most obvious extension is to use a more
realistic material model for large-scale quasistatic deformation. The natural
choice for this would be plasticity, in which a nonlinear relationship between
stress and strain replaces equation <a href="#step_18.stress-strain">[stress-strain]</a>. Plasticity
models are usually rather complicated to program since the stress-strain
dependence is generally non-smooth. The material can be thought of being able
to withstand only a maximal stress (the yield stress) after which it starts to
&ldquo;flow&rdquo;. A mathematical description to this can be given in the form of a
variational inequality, which alternatively can be treated as minimizing the
elastic energy
@f[
  E(\mathbf{u}) =
  (\varepsilon(\mathbf{u}), C\varepsilon(\mathbf{u}))_{\Omega}
  - (\mathbf{f}, \mathbf{u})_{\Omega} - (\mathbf{b}, \mathbf{u})_{\Gamma_N},
@f]
subject to the constraint
@f[
  f(\sigma(\mathbf{u})) \le 0
@f]
on the stress. This extension makes the problem to be solved in each time step
nonlinear, so we need another loop within each time step.

Without going into further details of this model, we refer to the excellent
book by Simo and Hughes on &ldquo;Computational Inelasticity&rdquo; for a
comprehensive overview of computational strategies for solving plastic
models. Alternatively, a brief but concise description of an algorithm for
plasticity is given in an article by S. Commend, A. Truty, and Th. Zimmermann;
@cite CTZ04.


<a name="Stabilizationissues"></a><h5>Stabilization issues</h5>


The formulation we have chosen, i.e. using
piecewise (bi-, tri-)linear elements for all components of the displacement
vector, and treating the stress as a variable dependent on the displacement is
appropriate for most materials. However, this so-called displacement-based
formulation becomes unstable and exhibits spurious modes for incompressible or
nearly-incompressible materials. While fluids are usually not elastic (in most
cases, the stress depends on velocity gradients, not displacement gradients,
although there are exceptions such as electro-rheologic fluids), there are a
few solids that are nearly incompressible, for example rubber. Another case is
that many plasticity models ultimately let the material become incompressible,
although this is outside the scope of the present program.

Incompressibility is characterized by Poisson's ratio
@f[
  \nu = \frac{\lambda}{2(\lambda+\mu)},
@f]
where @f$\lambda,\mu@f$ are the Lam&eacute; constants of the material.
Physical constraints indicate that @f$-1\le \nu\le \frac 12@f$ (the condition
also follows from mathematical stability considerations). If @f$\nu@f$
approaches @f$\frac 12@f$, then the material becomes incompressible. In that
case, pure displacement-based formulations are no longer appropriate for the
solution of such problems, and stabilization techniques have to be employed
for a stable and accurate solution. The book and paper cited above give
indications as to how to do this, but there is also a large volume of
literature on this subject; a good start to get an overview of the topic can
be found in the references of the paper by H.-Y. Duan and Q. Lin; @cite DL05.


<a name="Refinementduringtimesteps"></a><h5>Refinement during timesteps</h5>


In the present form, the program
only refines the initial mesh a number of times, but then never again. For any
kind of realistic simulation, one would want to extend this so that the mesh
is refined and coarsened every few time steps instead. This is not hard to do,
in fact, but has been left for future tutorial programs or as an exercise, if
you wish.

The main complication one has to overcome is that one has to
transfer the data that is stored in the quadrature points of the cells of the
old mesh to the new mesh, preferably by some sort of projection scheme. The
general approach to this would go like this:

- At the beginning, the data is only available in the quadrature points of
  individual cells, not as a finite element field that is defined everywhere.

- So let us find a finite element field that <i>is</i> defined everywhere so
  that we can later interpolate it to the quadrature points of the new
  mesh. In general, it will be difficult to find a continuous finite element
  field that matches the values in the quadrature points exactly because the
  number of degrees of freedom of these fields does not match the number of
  quadrature points there are, and the nodal values of this global field will
  either be over- or underdetermined. But it is usually not very difficult to
  find a discontinuous field that matches the values in the quadrature points;
  for example, if you have a QGauss(2) quadrature formula (i.e. 4 points per
  cell in 2d, 8 points in 3d), then one would use a finite element of kind
  FE_DGQ(1), i.e. bi-/tri-linear functions as these have 4 degrees of freedom
  per cell in 2d and 8 in 3d.

- There are functions that can make this conversion from individual points to
  a global field simpler. The following piece of pseudo-code should help if
  you use a QGauss(2) quadrature formula. Note that the multiplication by the
  projection matrix below takes a vector of scalar components, i.e., we can only
  convert one set of scalars at a time from the quadrature points to the degrees
  of freedom and vice versa. So we need to store each component of stress separately,
  which requires <code>dim*dim</code> vectors. We'll store this set of vectors in a 2D array to
  make it easier to read off components in the same way you would the stress tensor.
  Thus, we'll loop over the components of stress on each cell and store
  these values in the global history field. (The prefix <code>history_</code>
  indicates that we work with quantities related to the history variables defined
  in the quadrature points.)
  @code
    FE_DGQ<dim>     history_fe (1);
    DoFHandler<dim> history_dof_handler (triangulation);
    history_dof_handler.distribute_dofs (history_fe);

    std::vector< std::vector< Vector<double> > >
                 history_field (dim, std::vector< Vector<double> >(dim)),
                 local_history_values_at_qpoints (dim, std::vector< Vector<double> >(dim)),
                 local_history_fe_values (dim, std::vector< Vector<double> >(dim));

    for (unsigned int i=0; i<dim; i++)
      for (unsigned int j=0; j<dim; j++)
      {
        history_field[i][j].reinit(history_dof_handler.n_dofs());
        local_history_values_at_qpoints[i][j].reinit(quadrature.size());
        local_history_fe_values[i][j].reinit(history_fe.dofs_per_cell);
      }

    FullMatrix<double> qpoint_to_dof_matrix (history_fe.dofs_per_cell,
                                             quadrature.size());
    FETools::compute_projection_from_quadrature_points_matrix
              (history_fe,
               quadrature, quadrature,
               qpoint_to_dof_matrix);

    typename DoFHandler<dim>::active_cell_iterator cell = dof_handler.begin_active(),
                                                   endc = dof_handler.end(),
                                                   dg_cell = history_dof_handler.begin_active();

    for (; cell!=endc; ++cell, ++dg_cell)
      {

        PointHistory<dim> *local_quadrature_points_history
          = reinterpret_cast<PointHistory<dim> *>(cell->user_pointer());

        Assert (local_quadrature_points_history >= &quadrature_point_history.front(),
                ExcInternalError());
        Assert (local_quadrature_points_history < &quadrature_point_history.back(),
                ExcInternalError());

        for (unsigned int i=0; i<dim; i++)
          for (unsigned int j=0; j<dim; j++)
          {
            for (unsigned int q=0; q<quadrature.size(); ++q)
              local_history_values_at_qpoints[i][j](q)
                = local_quadrature_points_history[q].old_stress[i][j];

            qpoint_to_dof_matrix.vmult (local_history_fe_values[i][j],
                                        local_history_values_at_qpoints[i][j]);

            dg_cell->set_dof_values (local_history_fe_values[i][j],
                                     history_field[i][j]);
          }
      }
  @endcode

- Now that we have a global field, we can refine the mesh and transfer the
  history_field vector as usual using the SolutionTransfer class. This will
  interpolate everything from the old to the new mesh.

- In a final step, we have to get the data back from the now interpolated
  global field to the quadrature points on the new mesh. The following code
  will do that:
  @code
    FullMatrix<double> dof_to_qpoint_matrix (quadrature.size(),
                                             history_fe.dofs_per_cell);
    FETools::compute_interpolation_to_quadrature_points_matrix
              (history_fe,
               quadrature,
               dof_to_qpoint_matrix);

    typename DoFHandler<dim>::active_cell_iterator cell = dof_handler.begin_active(),
                                                   endc = dof_handler.end(),
                                                   dg_cell = history_dof_handler.begin_active();

    for (; cell != endc; ++cell, ++dg_cell)
    {
      PointHistory<dim> *local_quadrature_points_history
       = reinterpret_cast<PointHistory<dim> *>(cell->user_pointer());

      Assert (local_quadrature_points_history >= &quadrature_point_history.front(),
              ExcInternalError());
      Assert (local_quadrature_points_history < &quadrature_point_history.back(),
              ExcInternalError());

      for (unsigned int i=0; i<dim; i++)
        for (unsigned int j=0; j<dim; j++)
        {
          dg_cell->get_dof_values (history_field[i][j],
                                   local_history_fe_values[i][j]);

          dof_to_qpoint_matrix.vmult (local_history_values_at_qpoints[i][j],
                                      local_history_fe_values[i][j]);

          for (unsigned int q=0; q<quadrature.size(); ++q)
            local_quadrature_points_history[q].old_stress[i][j]
              = local_history_values_at_qpoints[i][j](q);
      }
  @endcode

It becomes a bit more complicated once we run the program in parallel, since
then each process only stores this data for the cells it owned on the old
mesh. That said, using a parallel vector for <code>history_field</code> will
do the trick if you put a call to <code>compress</code> after the transfer
from quadrature points into the global vector.


<a name="Ensuringmeshregularity"></a><h5>Ensuring mesh regularity</h5>


At present, the program makes no attempt
to make sure that a cell, after moving its vertices at the end of the time
step, still has a valid geometry (i.e. that its Jacobian determinant is
positive and bounded away from zero everywhere). It is, in fact, not very hard
to set boundary values and forcing terms in such a way that one gets distorted
and inverted cells rather quickly. Certainly, in some cases of large
deformation, this is unavoidable with a mesh of finite mesh size, but in some
other cases this should be preventable by appropriate mesh refinement and/or a
reduction of the time step size. The program does not do that, but a more
sophisticated version definitely should employ some sort of heuristic defining
what amount of deformation of cells is acceptable, and what isn't.
 *
 *
<a name="PlainProg"></a>
<h1> The plain program</h1>
@include "step-18.cc"
*/