From: Peter Munch Date: Sun, 1 Aug 2021 06:09:15 +0000 (+0200) Subject: Extend documention of TriangulationDescription X-Git-Tag: v9.4.0-rc1~1108^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F12618%2Fhead;p=dealii.git Extend documention of TriangulationDescription --- diff --git a/include/deal.II/grid/tria_description.h b/include/deal.II/grid/tria_description.h index 1b1edad1d5..b0a12d3f02 100644 --- a/include/deal.II/grid/tria_description.h +++ b/include/deal.II/grid/tria_description.h @@ -430,6 +430,48 @@ namespace TriangulationDescription * dealii::parallel::distributed::Triangulation, where the partitioning is * adopted unaltered. * + * Example for a serial Triangulation: + * + * @code + * Triangulation tria_base; + * + * // fill serial triangulation (e.g., read external mesh) + * GridIn grid_in; + * grid_in.attach_triangulation(tria_base); + * grid_in.read(file_name); + * + * // partition serial triangulation + * GridTools::partition_triangulation( + * Utilities::MPI::n_mpi_processes(comm), tria_base); + * + * // create description + * const TriangulationDescription::Description description = + * TriangulationDescription::Utilities:: + * create_description_from_triangulation(tria_base, comm); + * + * // create triangulation + * parallel::fullydistributed::Triangulation tria_pft(comm); + * tria_pft.create_triangulation(description); + * @endcode + * + * Example for parallel::distributed::Triangulation (partitioning can be + * skipped, since the trianguation has already been partitioned by p4est): + * + * @code + * parallel::distributed::Triangulation tria_base(comm); + * + * // fill tria_base (not shown) + * + * // create triangulation + * const TriangulationDescription::Description description = + * TriangulationDescription::Utilities:: + * create_description_from_triangulation(tria_base, comm); + * + * // create triangulation + * parallel::fullydistributed::Triangulation tria_pft(comm); + * tria_pft.create_triangulation(description); + * @endcode + * * @param tria Partitioned input triangulation. * @param comm MPI_Communicator to be used. In the case * of dealii::parallel::distributed::Triangulation, the communicators have @@ -485,6 +527,35 @@ namespace TriangulationDescription * triangulation and the TriangulationDescription::Description for all * processes in its group, which is communicated. * + * This function can also be used to read an external mesh only once (by + * the root process and a group consisting all processes). The following + * code snippet shows a modified version of the example provided in the + * documentation of create_description_from_triangulation(). + * Function calls that only need to be performed by the root process + * (read and partition mesh) have been moved into `std::function` objects. + * + * @code + * // create and partition serial triangulation and create description + * const TriangulationDescription::Description description = + * TriangulationDescription::Utilities:: + * create_description_from_triangulation_in_groups( + * [file_name](auto &tria_base) { + * GridIn grid_in; + * grid_in.attach_triangulation(tria_base); + * grid_in.read(file_name); + * }, + * [](auto &tria_base, const auto comm, const auto group_size) { + * GridTools::partition_triangulation( + * Utilities::MPI::n_mpi_processes(comm), tria_base); + * }, + * comm, + * Utilities::MPI::n_mpi_processes(comm)); + * + * // create triangulation + * parallel::fullydistributed::Triangulation tria_pft(comm); + * tria_pft.create_triangulation(description); + * @endcode + * * @note A reasonable group size is the size of a NUMA domain or the * size of a compute node. *