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:

Triangulation<dim, spacedim> tria_base;
 
// Create a serial triangulation (here by reading an external mesh):
GridIn<dim, spacedim> 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 building blocks:
const TriangulationDescription::Description<dim, spacedim> description =
  TriangulationDescription::Utilities::
    create_description_from_triangulation(tria_base, comm);
 
// Create a fully distributed triangulation:
parallel::fullydistributed::Triangulation<dim, spacedim> tria_pft(comm);
tria_pft.create_triangulation(description);

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:

parallel::distributed::Triangulation<dim, spacedim> tria_base(comm);
 
// Create a triangulation (not shown, see for example @ref step_40 "step-40")
...
 
// Create building blocks:
const TriangulationDescription::Description<dim, spacedim> description =
  TriangulationDescription::Utilities::
    create_description_from_triangulation(tria_base, comm);
 
// Create a fully distributed triangulation:
parallel::fullydistributed::Triangulation<dim, spacedim> tria_pft(comm);
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]	tria	The 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]	comm	The MPI communicator to be used. If the input triangulation is parallel, then the communicators have to match.
[in]	settings	See the description of the Settings enumerator.
[in]	my_rank_in	Construct 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
const TriangulationDescription::Description<dim, spacedim> description =
  TriangulationDescription::Utilities::
    create_description_from_triangulation_in_groups<dim, spacedim>(
      [file_name](auto &tria_base) {
        GridIn<dim, spacedim> 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<dim, spacedim> tria_pft(comm);
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_generator	A function which creates a serial triangulation.
serial_grid_partitioner	A 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.
comm	MPI communicator.
group_size	The size of each group.
smoothing	Mesh smoothing type.
setting	See 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.