Reference documentation for deal.II version 9.3.0

#include <deal.II/distributed/cell_weights.h>
Public Types  
using  WeightingFunction = std::function< unsigned int(const typename DoFHandler< dim, spacedim >::cell_iterator &, const FiniteElement< dim, spacedim > &)> 
Public Member Functions  
CellWeights (const ::DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function)  
~CellWeights ()  
void  reinit (const DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function) 
Deprecated functions  
CellWeights (const ::DoFHandler< dim, spacedim > &dof_handler)  
void  register_constant_weighting (const unsigned int factor=1000) 
void  register_ndofs_weighting (const unsigned int factor=1000) 
void  register_ndofs_squared_weighting (const unsigned int factor=1000) 
void  register_custom_weighting (const std::function< unsigned int(const FiniteElement< dim, spacedim > &, const typename DoFHandler< dim, spacedim >::cell_iterator &)> custom_function) 
Static Public Member Functions  
static std::function< unsigned int(const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const typename ::Triangulation< dim, spacedim >::CellStatus status)>  make_weighting_callback (const DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function) 
Selection of weighting functions  
static WeightingFunction  constant_weighting (const unsigned int factor=1000) 
static WeightingFunction  ndofs_weighting (const std::pair< float, float > &coefficients) 
static WeightingFunction  ndofs_weighting (const std::vector< std::pair< float, float >> &coefficients) 
Static Private Member Functions  
static unsigned int  weighting_callback (const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const typename ::Triangulation< dim, spacedim >::CellStatus status, const DoFHandler< dim, spacedim > &dof_handler, const parallel::TriangulationBase< dim, spacedim > &triangulation, const WeightingFunction &weighting_function) 
Private Attributes  
boost::signals2::connection  connection 
Deprecated members  
SmartPointer< const ::DoFHandler< dim, spacedim >, CellWeights >  dof_handler 
SmartPointer< const parallel::TriangulationBase< dim, spacedim >, CellWeights >  triangulation 
Anytime a parallel::TriangulationBase is repartitioned, either upon request or by refinement/coarsening, cells will be distributed amongst all subdomains to achieve an equally balanced workload. If the workload per cell varies, which is in general the case for DoFHandler objects with hpcapabilities, we can take that into account by introducing individual weights for different cells.
This class allows computing these weights for load balancing by consulting the FiniteElement that is associated with each cell of a DoFHandler. One can choose from predefined weighting algorithms provided by this class or provide a custom one.
If the associated DoFHandler has not been initialized yet, i.e., its hp::FECollection is empty, all cell weights will be evaluated as zero.
This class offers two different ways of connecting the chosen weighting function to the corresponding signal of the linked parallel::TriangulationBase. The recommended way involves creating an object of this class which will automatically take care of registering the weighting function upon creation and deregistering it once destroyed. An object of this class needs to exist for every DoFHandler associated with the Triangulation we work on to achieve satisfying work balancing results. The connected weighting function may be changed anytime using the CellWeights::reinit() function. The following code snippet demonstrates how to achieve each cell being weighted by its current number of degrees of freedom. We chose a factor of 1000
that corresponds to the initial weight each cell is assigned to upon creation.
On the other hand, you are also able to take care of handling the signal connection manually by using the static member function of this class. In this case, an analogous code example looks as follows.
The use of this class is demonstrated in step75.
Definition at line 91 of file cell_weights.h.
using parallel::CellWeights< dim, spacedim >::WeightingFunction = std::function< unsigned int(const typename DoFHandler<dim, spacedim>::cell_iterator &, const FiniteElement<dim, spacedim> &)> 
An alias that defines the characteristics of a function that can be used for weighting cells during load balancing.
Such weighting functions take as arguments an iterator to a cell and the future finite element that will be assigned to it after repartitioning. They return an unsigned integer which is interpreted as the cell's weight or, in other words, the additional computational load associated with it.
Definition at line 106 of file cell_weights.h.
parallel::CellWeights< dim, spacedim >::CellWeights  (  const ::DoFHandler< dim, spacedim > &  dof_handler, 
const WeightingFunction &  weighting_function  
) 
Constructor.
[in]  dof_handler  The DoFHandler which will be used to determine each cell's finite element. 
[in]  weighting_function  The function that determines each cell's weight during load balancing. 
Definition at line 28 of file cell_weights.cc.
parallel::CellWeights< dim, spacedim >::~CellWeights  (  ) 
Destructor.
Disconnects the function previously connected to the weighting signal.
Definition at line 38 of file cell_weights.cc.
parallel::CellWeights< dim, spacedim >::CellWeights  (  const ::DoFHandler< dim, spacedim > &  dof_handler  ) 
Constructor.
[in]  dof_handler  The DoFHandler which will be used to determine each cell's finite element. 
Definition at line 225 of file cell_weights.cc.
void parallel::CellWeights< dim, spacedim >::reinit  (  const DoFHandler< dim, spacedim > &  dof_handler, 
const WeightingFunction &  weighting_function  
) 
Connect a different weighting_function
to the Triangulation associated with the dof_handler
.
Disconnects the function previously connected to the weighting signal.
Definition at line 47 of file cell_weights.cc.

static 
Converts a weighting_function
to a different type that qualifies as a callback function, which can be connected to a weighting signal of a Triangulation.
This function does not connect the converted function to the Triangulation associated with the dof_handler
.
Definition at line 131 of file cell_weights.cc.

static 
Choose a constant weight factor
on each cell.
Definition at line 65 of file cell_weights.cc.

static 
The pair of floating point numbers \((a,b)\) provided via coefficients
determines the weight \(w_K\) of each cell \(K\) with \(n_K\) degrees of freedom in the following way:
\[ w_K = a \, n_K^b \]
The right hand side will be rounded to the nearest integer since cell weights are required to be integers.
Definition at line 77 of file cell_weights.cc.

static 
The container coefficients
provides pairs of floating point numbers \((a_i, b_i)\) that determine the weight \(w_K\) of each cell \(K\) with \(n_K\) degrees of freedom in the following way:
\[ w_K = \sum_i a_i \, n_K^{b_i} \]
The right hand side will be rounded to the nearest integer since cell weights are required to be integers.
Definition at line 101 of file cell_weights.cc.
void parallel::CellWeights< dim, spacedim >::register_constant_weighting  (  const unsigned int  factor = 1000  ) 
Choose a constant weight factor
on each cell.
Definition at line 244 of file cell_weights.cc.
void parallel::CellWeights< dim, spacedim >::register_ndofs_weighting  (  const unsigned int  factor = 1000  ) 
Choose a weight for each cell that is proportional to its number of degrees of freedom with a factor factor
.
Definition at line 266 of file cell_weights.cc.
void parallel::CellWeights< dim, spacedim >::register_ndofs_squared_weighting  (  const unsigned int  factor = 1000  ) 
Choose a weight for each cell that is proportional to its number of degrees of freedom squared with a factor factor
.
Definition at line 288 of file cell_weights.cc.
void parallel::CellWeights< dim, spacedim >::register_custom_weighting  (  const std::function< unsigned int(const FiniteElement< dim, spacedim > &, const typename DoFHandler< dim, spacedim >::cell_iterator &)>  custom_function  ) 
Register a custom weight for each cell by providing a function as a parameter.
[in]  custom_function  The custom weighting function returning the weight of each cell as an unsigned integer. It is required to have two arguments, namely the FiniteElement that will be active on the particular cell, and the cell itself of type DoFHandler::cell_iterator. We require both to make sure to get the right active FiniteElement on each cell in case that we coarsen the Triangulation. 
Definition at line 310 of file cell_weights.cc.

staticprivate 
A callback function that will be connected to the cell_weight signal of the triangulation
, to which the dof_handler
is attached. Ultimately returns the weight for each cell, determined by the weighting_function
provided as a parameter. Returns zero if dof_handler
has not been initialized yet.
Definition at line 164 of file cell_weights.cc.

private 
Pointer to the degree of freedom handler.
Definition at line 263 of file cell_weights.h.

private 
Pointer to the Triangulation associated with the degree of freedom handler.
We store both to make sure to always work on the correct combination of both.
Definition at line 274 of file cell_weights.h.

private 
A connection to the corresponding cell_weight signal of the Triangulation which is attached to the DoFHandler.
Definition at line 284 of file cell_weights.h.