Reference documentation for deal.II version GIT relicensing-14-gd371fb467a 2024-02-26 20:50:01+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Loading...
Searching...
No Matches
Functions
TriangulationDescription::Utilities Namespace Reference

Functions

template<int dim, int spacedim = dim>
Description< dim, spacedim > create_description_from_triangulation (const ::Triangulation< dim, spacedim > &tria, const MPI_Comm comm, const TriangulationDescription::Settings settings=TriangulationDescription::Settings::default_setting, const unsigned int my_rank_in=numbers::invalid_unsigned_int)
 
template<int dim, int spacedim>
Description< dim, spacedim > create_description_from_triangulation (const Triangulation< dim, spacedim > &tria, const LinearAlgebra::distributed::Vector< double, MemorySpace::Host > &partition, const TriangulationDescription::Settings settings=TriangulationDescription::Settings::default_setting)
 
template<int dim, int spacedim>
Description< dim, spacedim > create_description_from_triangulation (const Triangulation< dim, spacedim > &tria, const LinearAlgebra::distributed::Vector< double, MemorySpace::Host > &partition, const std::vector< LinearAlgebra::distributed::Vector< double, MemorySpace::Host > > &mg_partitions, const TriangulationDescription::Settings settings=TriangulationDescription::Settings::default_setting)
 
template<int dim, int spacedim = dim>
Description< dim, spacedim > create_description_from_triangulation_in_groups (const std::function< void(::Triangulation< dim, spacedim > &)> &serial_grid_generator, const std::function< void(::Triangulation< dim, spacedim > &, const MPI_Comm, const unsigned int)> &serial_grid_partitioner, const MPI_Comm comm, const int group_size=1, const typename Triangulation< dim, spacedim >::MeshSmoothing smoothing=::Triangulation< dim, spacedim >::none, const TriangulationDescription::Settings setting=TriangulationDescription::Settings::default_setting)
 
template<int dim, int spacedim>
Description< dim, spacedim > create_description_from_triangulation (const Triangulation< dim, spacedim > &tria, const LinearAlgebra::distributed::Vector< double > &partition, const TriangulationDescription::Settings settings)
 
template<int dim, int spacedim>
Description< dim, spacedim > create_description_from_triangulation (const Triangulation< dim, spacedim > &tria, const LinearAlgebra::distributed::Vector< double > &partition, const std::vector< LinearAlgebra::distributed::Vector< double > > &partitions_mg, const TriangulationDescription::Settings settings_in)
 

Detailed Description

A namespace for TriangulationDescription::Description utility functions.

Function Documentation

◆ create_description_from_triangulation() [1/5]

template<int dim, int spacedim = dim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation ( const ::Triangulation< dim, spacedim > &  tria,
const MPI_Comm  comm,
const TriangulationDescription::Settings  settings = TriangulationDescription::Settings::default_setting,
const unsigned int  my_rank_in = numbers::invalid_unsigned_int 
)

Construct a TriangulationDescription::Description object that for the current process, using a given triangulation tria describes how one can re-create a partitioned triangulation (such as a parallel::fullydistributed::Triangulation). The input triangulation can be either a serial triangulation of type Triangulation which has been colored (i.e., for which the subdomain_id and/or level_subdomain_id have been set to create partitions), or a distributed triangulation of type parallel::distributed::Triangulation, where the output of this function takes over the existing partitioning unaltered.

An example for a serial Triangulation looks like this:

// Create a serial triangulation (here by reading an external mesh):
grid_in.attach_triangulation(tria_base);
grid_in.read(file_name);
// Partition serial triangulation:
// Create building blocks:
// Create a fully distributed triangulation:
tria_pft.create_triangulation(description);
void attach_triangulation(Triangulation< dim, spacedim > &tria)
Definition grid_in.cc:154
void read(std::istream &in, Format format=Default)
Definition grid_in.cc:4179
void partition_triangulation(const unsigned int n_partitions, Triangulation< dim, spacedim > &triangulation, const SparsityTools::Partitioner partitioner=SparsityTools::Partitioner::metis)
Description< dim, spacedim > create_description_from_triangulation(const ::Triangulation< dim, spacedim > &tria, const MPI_Comm comm, const TriangulationDescription::Settings settings=TriangulationDescription::Settings::default_setting, const unsigned int my_rank_in=numbers::invalid_unsigned_int)
unsigned int n_mpi_processes(const MPI_Comm mpi_communicator)
Definition mpi.cc:128
*braid_SplitCommworld & comm

In this example, all processes in a parallel universe read the same mesh, and partition it in the same way based on the subdomain ids set by GridTools::partition_triangulation(). Then, on each process, the current function creates building blocks that extract information about those cells whose subdomain ids match the current process's rank (plus perhaps other necessary information), and in a last step, we create a fully distributed triangulation out of these building blocks.

In contrast, when starting with a parallel::distributed::Triangulation object, partitioning can be skipped, since the triangulation has already been partitioned and the corresponding code looks as follows:

// Create a triangulation (not shown, see for example @ref step_40 "step-40")
...
// Create building blocks:
// Create a fully distributed triangulation:
tria_pft.create_triangulation(description);

This code therefore takes a parallel::distributed::Triangulation object (such as the ones used, for example, in step-40 and many other tutorial programs) and converts it into a parallel::fullydistributed::Triangulation.

Parameters
[in]triaThe input triangulation. This function uses the partitioning provided by either explicitly setting subdomain_ids (if the triangulation is sequential) or based on how the existing triangulation is already distributed to different processes.
[in]commThe MPI communicator to be used. If the input triangulation is parallel, then the communicators have to match.
[in]settingsSee the description of the Settings enumerator.
[in]my_rank_inConstruct Description for the specified rank. This parameter can only be set for serial input triangulations that have been partitioned by functions like GridTools::partition_triangulation(). For parallel input triangulations, my_rank_in needs to equal to the default value, or to the rank of the current process within the given communicator.
Returns
The Description object that can then be used to set up a parallel::fullydistributed::Triangulation.
Note
If construct_multigrid_hierarchy is set in the settings, then the input triangulation has to be set up with limit_level_difference_at_vertices among the triangulation's smoothing flags provided to the triangulation constructor.

Definition at line 717 of file tria_description.cc.

◆ create_description_from_triangulation() [2/5]

template<int dim, int spacedim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation ( const Triangulation< dim, spacedim > &  tria,
const LinearAlgebra::distributed::Vector< double, MemorySpace::Host > &  partition,
const TriangulationDescription::Settings  settings = TriangulationDescription::Settings::default_setting 
)

Similar to the above function but the desired owners of active cells are not provided via the subdomain_ids of cells, but rather by the corresponding values of a cell vector (see also parallel::TriangulationBase::global_active_cell_index_partitioner() and CellAccessor::global_active_cell_index()). This function allows repartitioning Triangulation objects that are already distributed and that may be partitioned differently than the desired partitioning.

If the setup of multigrid levels is requested by the settings argument, they are partitioned according to a first-child policy. In other words, a process owns a (non-active) cell if it owns its first child. If that first child is not active itself, the policy is applied recursively.

The partitioning of cells is determined based on the elements of the partition vector. While that vector stores elements of type double, actual values must be integers and be within the range of process ranks of the relevant communicator.

Note
The communicator is extracted from the vector partition.
The triangulation tria can be set up on a subcommunicator of the communicator of partitioner. All processes that are not part of that subcommunicator need to set up the local triangulation with the special-purpose communicator MPI_COMM_NULL.
The multigrid levels are currently not constructed, since partition only describes the partitioning of the active level.

◆ create_description_from_triangulation() [3/5]

template<int dim, int spacedim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation ( const Triangulation< dim, spacedim > &  tria,
const LinearAlgebra::distributed::Vector< double, MemorySpace::Host > &  partition,
const std::vector< LinearAlgebra::distributed::Vector< double, MemorySpace::Host > > &  mg_partitions,
const TriangulationDescription::Settings  settings = TriangulationDescription::Settings::default_setting 
)

Similar to the above function but allowing the user to prescribe the partitioning of the multigrid levels. As with the other function, while both the global and level-wise partition vectors store elements with data type double, actual elements must be integers and equal possible process ranks within the relevant communicator.

◆ create_description_from_triangulation_in_groups()

template<int dim, int spacedim = dim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation_in_groups ( const std::function< void(::Triangulation< dim, spacedim > &)> &  serial_grid_generator,
const std::function< void(::Triangulation< dim, spacedim > &, const MPI_Comm, const unsigned int)> &  serial_grid_partitioner,
const MPI_Comm  comm,
const int  group_size = 1,
const typename Triangulation< dim, spacedim >::MeshSmoothing  smoothing = ::Triangulation<dim, spacedim>::none,
const TriangulationDescription::Settings  setting = TriangulationDescription::Settings::default_setting 
)

Construct a TriangulationDescription::Description. In contrast to the function above, this function is also responsible for creating a serial triangulation and for its partitioning (by calling the provided std::function objects). Internally only selected processes ( every n-th/each root of a group of size group_size) create a serial 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.

// create and partition serial triangulation and create description
TriangulationDescription::Utilities::
create_description_from_triangulation_in_groups<dim, spacedim>(
[file_name](auto &tria_base) {
grid_in.attach_triangulation(tria_base);
grid_in.read(file_name);
},
[](auto &tria_base, const auto comm, const auto group_size) {
},
// create triangulation
tria_pft.create_triangulation(description);
Note
A reasonable group size is the size of a NUMA domain or the size of a compute node.
Parameters
serial_grid_generatorA function which creates a serial triangulation.
serial_grid_partitionerA function which can partition a serial triangulation, i.e., sets the sudomain_ids of the active cells. The function takes as the first argument a serial triangulation, as the second argument the MPI communicator, and as the third argument the group size.
commMPI communicator.
group_sizeThe size of each group.
smoothingMesh smoothing type.
settingSee the description of the Settings enumerator.
Returns
Description to be used to set up a Triangulation.
Note
If construct_multigrid_hierarchy is set in the settings, the smoothing parameter is extended with the limit_level_difference_at_vertices flag.

Definition at line 794 of file tria_description.cc.

◆ create_description_from_triangulation() [4/5]

template<int dim, int spacedim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation ( const Triangulation< dim, spacedim > &  tria,
const LinearAlgebra::distributed::Vector< double > &  partition,
const TriangulationDescription::Settings  settings 
)

Definition at line 924 of file tria_description.cc.

◆ create_description_from_triangulation() [5/5]

template<int dim, int spacedim>
Description< dim, spacedim > TriangulationDescription::Utilities::create_description_from_triangulation ( const Triangulation< dim, spacedim > &  tria,
const LinearAlgebra::distributed::Vector< double > &  partition,
const std::vector< LinearAlgebra::distributed::Vector< double > > &  partitions_mg,
const TriangulationDescription::Settings  settings_in 
)

Definition at line 1008 of file tria_description.cc.