From: Jean-Paul Pelteret <jppelteret@gmail.com>
Date: Tue, 10 Jul 2018 12:01:51 +0000 (+0200)
Subject: Enhance parallel::distributed::SolutionTransfer documentation
X-Git-Tag: v9.1.0-rc1~931^2~2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=99040048b7ca467ff61b9a0cba4e56df6fc245ed;p=dealii.git

Enhance parallel::distributed::SolutionTransfer documentation

Includes a note on how the old solution vector must be configured with
access to locally relevant data
---

diff --git a/include/deal.II/distributed/solution_transfer.h b/include/deal.II/distributed/solution_transfer.h
index e23d5c1413..962bc4e349 100644
--- a/include/deal.II/distributed/solution_transfer.h
+++ b/include/deal.II/distributed/solution_transfer.h
@@ -87,6 +87,36 @@ namespace parallel
      * interpolated_solution.update_ghost_values();
      * @endcode
      *
+     * As the grid is distributed, it is important to note that the old
+     * solution(s) must be copied to one that also provides access to the
+     * locally relevant DoF values (these values required for the interpolation
+     * process):
+     * @code
+     * // Create initial indexsets pertaining to the grid before refinement
+     * IndexSet locally_owned_dofs, locally_relevant_dofs;
+     * locally_owned_dofs = dof_handler.locally_owned_dofs();
+     * DoFTools::extract_locally_relevant_dofs(dof_handler,
+     * locally_relevant_dofs);
+     *
+     * // The solution vector only knows about locally owned DoFs
+     * TrilinosWrappers::MPI::Vector solution;
+     * solution.reinit(locally_owned_dofs,
+     *                 mpi_communicator);
+     * ...
+     * // Transfer solution to vector that provides access to locally relevant
+     * DoFs TrilinosWrappers::MPI::Vector old_solution;
+     * old_solution.reinit(locally_owned_dofs,
+     *                     locally_relevant_dofs,
+     *                     mpi_communicator);
+     * old_solution = solution;
+     * ...
+     * // Refine grid
+     * // Recreate locally_owned_dofs and locally_relevant_dofs index sets
+     * ...
+     * solution.reinit(locally_owned_dofs, mpi_communicator);
+     * soltrans.refine_interpolate(old_solution, solution);
+     * @endcode
+     *
      * <h3>Use for Serialization</h3>
      *
      * This class can be used to serialize and later deserialize a distributed