Reference documentation for deal.II version Git 3e8fd02 2017-09-22 11:37:14 +0200
Functions
parallel::GridTools Namespace Reference

Functions

template<typename DataType , typename MeshType >
void exchange_cell_data_to_ghosts (const MeshType &mesh, std::function< boost::optional< DataType >(const typename MeshType::active_cell_iterator &)> pack, std::function< void(const typename MeshType::active_cell_iterator &, const DataType &)> unpack)
 

Detailed Description

This namespace defines parallel algorithms that operate on meshes.

Function Documentation

template<typename DataType , typename MeshType >
void parallel::GridTools::exchange_cell_data_to_ghosts ( const MeshType &  mesh,
std::function< boost::optional< DataType >(const typename MeshType::active_cell_iterator &)>  pack,
std::function< void(const typename MeshType::active_cell_iterator &, const DataType &)>  unpack 
)

Exchange arbitrary data of type DataType provided by the function objects from locally owned cells to ghost cells on other processors.

After this call, you typically will have received data from unpack on every ghost cell as it was given by pack on the owning processor. Whether you do or do not receive information to unpack on a given ghost cell depends on whether the pack function decided that something needs to be sent. It does so using the boost::optional mechanism: if the boost::optional return object of the pack function is empty, then this implies that no data has to be sent for the locally owned cell it was called on. In that case, unpack will also not be called on the ghost cell that corresponds to it on the receiving side. On the other hand, if the boost::optional object is not empty, then the data stored within it will be sent to the received and the unpack function called with it.

Template Parameters
DataTypeThe type of the data to be communicated. It is assumed to be serializable by boost::serialization. In many cases, this data type can not be deduced by the compiler, e.g., if you provide lambda functions for the second and third argument to this function. In this case, you have to explicitly specify the DataType as a template argument to the function call.
MeshTypeThe type of mesh.
Parameters
meshA variable of a type that satisfies the requirements of the MeshType concept.
packThe function that will be called on each locally owned cell that is a ghost cell somewhere else. As mentioned above, the function may return a regular data object of type DataType to indicate that data should be sent, or an empty boost::optional<DataType> to indicate that nothing has to be sent for this cell.
unpackThe function that will be called for each ghost cell for which data was sent, i.e., for which the pack function on the sending side returned a non-empty boost::optional object. The unpack function is then called with the data sent by the processor that owns that cell.

An example

Here is an example that shows how this function is to be used in a concrete context. It is taken from the code that makes sure that the active_fe_index (a single unsigned integer) is transported from locally owned cells where one can set it in hp::DoFHandler objects, to the corresponding ghost cells on other processors to ensure that one can query the right value also on those processors:

auto pack
= [] (const typename ::hp::DoFHandler<dim,spacedim>::active_cell_iterator &cell) -> unsigned int
{
return cell->active_fe_index();
};
auto unpack
= [] (const typename ::hp::DoFHandler<dim,spacedim>::active_cell_iterator &cell,
const unsigned int &active_fe_index) -> void
{
cell->set_active_fe_index(active_fe_index);
};
parallel::GridTools::exchange_cell_data_to_ghosts<unsigned int, ::hp::DoFHandler<dim,spacedim>>
(dof_handler, pack, unpack);

You will notice that the pack lambda function returns an unsigned int, not a boost::optional<unsigned int>. The former converts automatically to the latter, implying that data will always be transported to the other processor.

(In reality, the unpack function needs to be a bit more complicated because it is not allowed to call DoFAccessor::set_active_fe_index() on ghost cells. Rather, the unpack function directly accesses internal data structures. But you get the idea – the code could, just as well, have exchanged material ids, user indices, boundary indictors, or any kind of other data with similar calls as the ones above.)