parallel::CellWeights< dim, spacedim > Class Template Reference

#include <deal.II/distributed/cell_weights.h>

Detailed Description

template<int dim, int spacedim = dim>
class parallel::CellWeights< dim, spacedim >

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. By default, if you don't do anything specific, the workload is assumed to be the same for every cell of the triangulation, and in that case a well-balanced mesh will have about the same number of cells on each process. But, if the workload per cell varies, which is in general the case for DoFHandler objects that hp-capabilities (i.e., where you use different finite elements on different cells), 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 de-registering 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.

parallel::CellWeights<dim, spacedim> cell_weights(
  hp_dof_handler,
  parallel::CellWeights<dim, spacedim>::ndofs_weighting({1, 1}));

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.

boost::signals2::connection connection =
  hp_dof_handler.get_triangulation().signals.weight.connect(
    parallel::CellWeights<dim, spacedim>::make_weighting_callback(
      hp_dof_handler,
      parallel::CellWeights<dim, spacedim>::ndofs_weighting({1, 1})));

Oftentimes, the weighting function only requires information about the finite element (for example about the number of degrees of freedom per cell), but not the cell we are currently considering (even though the weighting function takes a cell iterator as argument). In this case, it is wasteful to re-compute the weight on every cell we visit; instead, the weights can be computed in advance for each finite element in use on the DoFHandler with precompute_weights(). The returned container can then be either passed to the corresponding constructor, reinit() or make_weighting_callback() function. Of course, in this case no other cell-specific information can be used in the computation of the weights.

The use of this class is demonstrated in step-75.

Note

See Triangulation::Signals::weight for more information on weighting and load balancing.

Be aware that this class connects the weight function to the Triangulation during this class's constructor. If the Triangulation associated with the DoFHandler changes during the lifetime of the latter via DoFHandler::reinit(), an assertion will be triggered in the weight_callback() function. Use CellWeights::reinit() to deregister the weighting function on the old Triangulation and connect it to the new one.

A hp::FECollection needs to be attached to your DoFHandler object via DoFHandler::distribute_dofs() before the Triangulation::Signals::weight signal will be triggered. Otherwise, your DoFHandler does not know many degrees of freedom your cells have. In other words, you need to call DoFHandler::distribute_dofs() once before you call parallel::distributed::Triangulation::execute_coarsening_and_refinement(), parallel::distributed::Triangulation::refine_global(), parallel::distributed::Triangulation::repartition(), or GridTools::partition_triangulation() for the very first time.

Definition at line 122 of file 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 ()=default
	CellWeights (const DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function)
	CellWeights (const DoFHandler< dim, spacedim > &dof_handler, const std::vector< unsigned int > &precomputed_weights)
	~CellWeights ()
void	reinit (const DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function)
void	reinit (const DoFHandler< dim, spacedim > &dof_handler, const std::vector< unsigned int > &precomputed_weights)

Static Public Member Functions
static std::function< unsigned int(const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status)>	make_weighting_callback (const DoFHandler< dim, spacedim > &dof_handler, const WeightingFunction &weighting_function)
static std::function< unsigned int(const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status)>	make_weighting_callback (const DoFHandler< dim, spacedim > &dof_handler, const std::vector< unsigned int > &precomputed_weights)
Selection of weighting functions
static WeightingFunction	constant_weighting (const unsigned int factor=1)
static WeightingFunction	ndofs_weighting (const std::pair< float, float > &coefficients)
static WeightingFunction	ndofs_weighting (const std::vector< std::pair< float, float > > &coefficients)
static std::vector< unsigned int >	precompute_weights (const hp::FECollection< dim, spacedim > &fe_collection, const WeightingFunction &weighting_function)

Static Private Member Functions
static unsigned int	weighting_callback (const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status, const DoFHandler< dim, spacedim > &dof_handler, const parallel::TriangulationBase< dim, spacedim > &triangulation, const WeightingFunction &weighting_function)
static unsigned int	weighting_callback (const typename ::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status, const DoFHandler< dim, spacedim > &dof_handler, const parallel::TriangulationBase< dim, spacedim > &triangulation, const std::vector< unsigned int > &precomputed_weights)

Private Attributes
boost::signals2::connection	connection

Member Typedef Documentation

WeightingFunction

template<int dim, int spacedim = dim>

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 135 of file cell_weights.h.

Constructor & Destructor Documentation

CellWeights() [1/3]

template<int dim, int spacedim = dim>

parallel::CellWeights< dim, spacedim >::CellWeights ( )

default

Constructor.

No weighting function will be connected yet. Please call reinit().

CellWeights() [2/3]

template<int dim, int spacedim>

parallel::CellWeights< dim, spacedim >::CellWeights	(	const DoFHandler< dim, spacedim > &	dof_handler,
		const WeightingFunction &	weighting_function
	)

Constructor.

Parameters

[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 112 of file cell_weights.cc.

CellWeights() [3/3]

template<int dim, int spacedim>

parallel::CellWeights< dim, spacedim >::CellWeights	(	const DoFHandler< dim, spacedim > &	dof_handler,
		const std::vector< unsigned int > &	precomputed_weights
	)

Constructor.

Parameters

[in]	dof_handler	The DoFHandler which will be used to determine each cell's finite element.
[in]	precomputed_weights	Weights for each finite element of the hp::FECollection used by dof_handler. On each cell, we query its active finite element index and use this index to look up its weight during load balancing.

Definition at line 122 of file cell_weights.cc.

~CellWeights()

template<int dim, int spacedim>

parallel::CellWeights< dim, spacedim >::~CellWeights

(

)

Destructor.

Disconnects the function previously connected to the weighting signal.

Definition at line 132 of file cell_weights.cc.

Member Function Documentation

constant_weighting()

template<int dim, int spacedim>

CellWeights< dim, spacedim >::WeightingFunction parallel::CellWeights< dim, spacedim >::constant_weighting ( const unsigned int  factor = 1 )

static

This function returns a WeightingFunction which determines the weight to be applied on each cell. It is used to initialize a CellWeights object.

Chooses a constant weight factor on each cell.

Definition at line 29 of file cell_weights.cc.

ndofs_weighting() [1/2]

template<int dim, int spacedim>

CellWeights< dim, spacedim >::WeightingFunction parallel::CellWeights< dim, spacedim >::ndofs_weighting ( const std::pair< float, float > &  coefficients )

static

This function returns a WeightingFunction which determines the weight to be applied on each cell. It is used to initialize a CellWeights object.

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 41 of file cell_weights.cc.

ndofs_weighting() [2/2]

template<int dim, int spacedim>

CellWeights< dim, spacedim >::WeightingFunction parallel::CellWeights< dim, spacedim >::ndofs_weighting ( const std::vector< std::pair< float, float > > &  coefficients )

static

This function returns a WeightingFunction which determines the weight to be applied on each cell. It is used to initialize a CellWeights object.

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 65 of file cell_weights.cc.

precompute_weights()

template<int dim, int spacedim>

std::vector< unsigned int > parallel::CellWeights< dim, spacedim >::precompute_weights ( const hp::FECollection< dim, spacedim > &  fe_collection, const WeightingFunction &  weighting_function  )

static

For a given WeightingFunction, this function returns pre-computed weights for each finite element in fe_collection. Pass the container to the corresponding constructor, reinit() or make_weighting_callback() functions.

If your weights only require information about the finite element on each cell, consider pre-computing them with this function. All other cell-specific characteristics in determining weights will be omitted.

Definition at line 93 of file cell_weights.cc.

reinit() [1/2]

template<int dim, int spacedim>

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 141 of file cell_weights.cc.

reinit() [2/2]

template<int dim, int spacedim>

void parallel::CellWeights< dim, spacedim >::reinit	(	const DoFHandler< dim, spacedim > &	dof_handler,
		const std::vector< unsigned int > &	precomputed_weights
	)

Connect a different weighting mechanism to the Triangulation associated with the dof_handler. Values in precomputed_weights will be used as weights for each finite element. On each cell, we query its active finite element index and use this index to look up its weight during load balancing.

Disconnects the function previously connected to the weighting signal.

Definition at line 155 of file cell_weights.cc.

make_weighting_callback() [1/2]

template<int dim, int spacedim>

std::function< unsigned int(const typename::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status)> parallel::CellWeights< dim, spacedim >::make_weighting_callback ( const DoFHandler< dim, spacedim > &  dof_handler, const WeightingFunction &  weighting_function  )

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 173 of file cell_weights.cc.

make_weighting_callback() [2/2]

template<int dim, int spacedim>

std::function< unsigned int(const typename::Triangulation< dim, spacedim >::cell_iterator &cell, const CellStatus status)> parallel::CellWeights< dim, spacedim >::make_weighting_callback ( const DoFHandler< dim, spacedim > &  dof_handler, const std::vector< unsigned int > &  precomputed_weights  )

static

Use precomputed_weights as weights for each finite element of dof_handler. Returns a callback function, which can be connected to a weighting signal of a Triangulation.

This function does not connect the callback function to the Triangulation associated with the dof_handler.

Definition at line 259 of file cell_weights.cc.

weighting_callback() [1/2]

template<int dim, int spacedim>

unsigned int parallel::CellWeights< dim, spacedim >::weighting_callback ( const typename ::Triangulation< dim, spacedim >::cell_iterator &  cell, const CellStatus  status, const DoFHandler< dim, spacedim > &  dof_handler, const parallel::TriangulationBase< dim, spacedim > &  triangulation, const WeightingFunction &  weighting_function  )

staticprivate

A callback function that can be connected to the 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 199 of file cell_weights.cc.

weighting_callback() [2/2]

template<int dim, int spacedim>

unsigned int parallel::CellWeights< dim, spacedim >::weighting_callback ( const typename ::Triangulation< dim, spacedim >::cell_iterator &  cell, const CellStatus  status, const DoFHandler< dim, spacedim > &  dof_handler, const parallel::TriangulationBase< dim, spacedim > &  triangulation, const std::vector< unsigned int > &  precomputed_weights  )

staticprivate

A callback function that can be connected to the weight signal of the triangulation, to which the dof_handler is attached. Ultimately returns the weight for each cell, determined by the precomputed_weights provided as a parameter. Returns zero if dof_handler has not been initialized yet.

Definition at line 287 of file cell_weights.cc.

Member Data Documentation

connection

template<int dim, int spacedim = dim>

boost::signals2::connection parallel::CellWeights< dim, spacedim >::connection

private

A connection to the corresponding weight signal of the Triangulation which is attached to the DoFHandler.

Definition at line 296 of file cell_weights.h.

---

The documentation for this class was generated from the following files:

• include/deal.II/distributed/cell_weights.h
• source/distributed/cell_weights.cc