Reference documentation for deal.II version 8.5.0
FETools::Compositing Namespace Reference

## Functions

template<int dim, int spacedim>
FiniteElementData< dim > multiply_dof_numbers (const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities, const bool do_tensor_product=true)

template<int dim, int spacedim>
FiniteElementData< dim > multiply_dof_numbers (const FiniteElement< dim, spacedim > *fe1, const unsigned int N1, const FiniteElement< dim, spacedim > *fe2=NULL, const unsigned int N2=0, const FiniteElement< dim, spacedim > *fe3=NULL, const unsigned int N3=0, const FiniteElement< dim, spacedim > *fe4=NULL, const unsigned int N4=0, const FiniteElement< dim, spacedim > *fe5=NULL, const unsigned int N5=0)

template<int dim, int spacedim>
std::vector< bool > compute_restriction_is_additive_flags (const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities)

template<int dim, int spacedim>
std::vector< bool > compute_restriction_is_additive_flags (const FiniteElement< dim, spacedim > *fe1, const unsigned int N1, const FiniteElement< dim, spacedim > *fe2=NULL, const unsigned int N2=0, const FiniteElement< dim, spacedim > *fe3=NULL, const unsigned int N3=0, const FiniteElement< dim, spacedim > *fe4=NULL, const unsigned int N4=0, const FiniteElement< dim, spacedim > *fe5=NULL, const unsigned int N5=0)

template<int dim, int spacedim>
std::vector< ComponentMaskcompute_nonzero_components (const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities, const bool do_tensor_product=true)

template<int dim, int spacedim>
std::vector< ComponentMaskcompute_nonzero_components (const FiniteElement< dim, spacedim > *fe1, const unsigned int N1, const FiniteElement< dim, spacedim > *fe2=NULL, const unsigned int N2=0, const FiniteElement< dim, spacedim > *fe3=NULL, const unsigned int N3=0, const FiniteElement< dim, spacedim > *fe4=NULL, const unsigned int N4=0, const FiniteElement< dim, spacedim > *fe5=NULL, const unsigned int N5=0, const bool do_tensor_product=true)

template<int dim, int spacedim>
void build_cell_tables (std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > &system_to_base_table, std::vector< std::pair< unsigned int, unsigned int > > &system_to_component_table, std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > &component_to_base_table, const FiniteElement< dim, spacedim > &finite_element, const bool do_tensor_product=true)

template<int dim, int spacedim>
void build_face_tables (std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > &face_system_to_base_table, std::vector< std::pair< unsigned int, unsigned int > > &face_system_to_component_table, const FiniteElement< dim, spacedim > &finite_element, const bool do_tensor_product=true)

## Detailed Description

A namespace that contains functions that help setting up internal data structures when implementing FiniteElement which are build from simpler ("base") elements, for example FESystem. The things computed by these functions typically serve as constructor arguments to the FiniteElement base class of the derived finite element object being constructed.

There are generally two ways in which one can build more complex elements, and this is reflected by several of the functions in this namespace having arguments called do_tensor_product:

1. Tensor product construction (do_tensor_product=true): The tensor product construction, in the simplest case, builds a vector-valued element from scalar elements (see this documentation module and this glossary entry for more information). To give an example, consider creating a vector-valued element with two vector components, where the first should have linear shape functions and the second quadratic shape functions. In 1d, the shape functions (on the reference cell) of the base elements are then

\begin{align*} Q_1 &= \{ 1-x, x \}, \\ Q_2 &= \{ 2(\frac 12 - x)(1-x), 2(x - \frac 12)x, 4x(1-x) \}, \end{align*}

where shape functions are ordered in the usual way (first on the first vertex, then on the second vertex, then in the interior of the cell). The tensor product construction will create an element with the following shape functions:

\begin{align*} Q_1 \times Q_2 &= \left\{ \begin{pmatrix} 1-x \\ 0 \end{pmatrix}, \begin{pmatrix} 0 \\ 2(\frac 12 - x)(1-x) \end{pmatrix}, \begin{pmatrix} x \\ 0 \end{pmatrix}, \begin{pmatrix} 0 \\ 2(x - \frac 12)x \end{pmatrix}, \begin{pmatrix} 0 \\ 4x(1-x) \end{pmatrix} \right\}. \end{align*}

The list here is again in standard order.

Of course, the procedure also works if the base elements are already vector valued themselves: in that case, the composed element simply has as many vector components as the base elements taken together.

2. Combining shape functions (do_tensor_product=false): In contrast to the previous strategy, combining shape functions simply takes all of the shape functions together. In the case above, this would yield the following element:

\begin{align*} Q_1 + Q_2 &= \{ 1-x, 2(\frac 12 - x)(1-x), x, 2(x - \frac 12)x, 4x(1-x) \}. \end{align*}

In other words, if the base elements are scalar, the resulting element will also be. In general, the base elements all will have to have the same number of vector components.

The element constructed above of course no longer has a linearly independent set of shape functions. As a consequence, any matrix one creates by treating all shape functions of the composed element in the same way will be singular. In practice, this strategy is therefore typically used in situations where one explicitly makes sure that certain shape functions are treated differently (e.g., by multiplying them with weight functions), or in cases where the shape functions one combines are not linearly dependent.

## Function Documentation

template<int dim, int spacedim>
 FiniteElementData< dim > FETools::Compositing::multiply_dof_numbers ( const std::vector< const FiniteElement< dim, spacedim > * > & fes, const std::vector< unsigned int > & multiplicities, const bool do_tensor_product = true )

Take vectors of finite elements and multiplicities and multiply out how many degrees of freedom the composed element has per vertex, line, etc.

If do_tensor_product is true, the number of components returned in the FiniteElementData object is the sum over the product of the number of components in each of the finite elements times the corresponding multiplicity. Otherwise the number of components is taken from the first finite element with non-zero multiplicity, and all other elements with non-zero multiplicities need to have the same number of vector components.

See the documentation of namespace FETools::Compositing for more information about the do_tensor_product argument.

Definition at line 73 of file fe_tools.cc.

template<int dim, int spacedim>
 FiniteElementData< dim > FETools::Compositing::multiply_dof_numbers ( const FiniteElement< dim, spacedim > * fe1, const unsigned int N1, const FiniteElement< dim, spacedim > * fe2 = NULL, const unsigned int N2 = 0, const FiniteElement< dim, spacedim > * fe3 = NULL, const unsigned int N3 = 0, const FiniteElement< dim, spacedim > * fe4 = NULL, const unsigned int N4 = 0, const FiniteElement< dim, spacedim > * fe5 = NULL, const unsigned int N5 = 0 )

Same as above but for a specific number of sub-elements.

Definition at line 158 of file fe_tools.cc.

template<int dim, int spacedim>
 std::vector< bool > FETools::Compositing::compute_restriction_is_additive_flags ( const std::vector< const FiniteElement< dim, spacedim > * > & fes, const std::vector< unsigned int > & multiplicities )

Compute the "restriction is additive" flags (see the documentation of the FiniteElement class) for a list of finite elements with multiplicities given in the second argument.

The "restriction is additive" flags are properties of individual shape functions that do not depend on whether the composed element uses the tensor product or combination strategy outlined in the documentation of the FETools::Composition namespace. Consequently, this function does not have a do_tensor_product argument.

Definition at line 189 of file fe_tools.cc.

template<int dim, int spacedim>
 std::vector< bool > FETools::Compositing::compute_restriction_is_additive_flags ( const FiniteElement< dim, spacedim > * fe1, const unsigned int N1, const FiniteElement< dim, spacedim > * fe2 = NULL, const unsigned int N2 = 0, const FiniteElement< dim, spacedim > * fe3 = NULL, const unsigned int N3 = 0, const FiniteElement< dim, spacedim > * fe4 = NULL, const unsigned int N4 = 0, const FiniteElement< dim, spacedim > * fe5 = NULL, const unsigned int N5 = 0 )

Take a FiniteElement object and return a boolean vector describing the restriction_is_additive_flags (see the documentation of the FiniteElement class) for each shape function of the mixed element consisting of N1, N2, ... copies of the sub-elements fe1, fe2, ...

The "restriction is additive" flags are properties of individual shape functions that do not depend on whether the composed element uses the tensor product or combination strategy outlined in the documentation of the FETools::Composition namespace. Consequently, this function does not have a do_tensor_product argument.

Take a FiniteElement object and return an boolean vector including the restriction_is_additive_flags of the mixed element consisting of N elements of the sub-element fe.

Definition at line 316 of file fe_tools.cc.

template<int dim, int spacedim>
 std::vector< ComponentMask > FETools::Compositing::compute_nonzero_components ( const std::vector< const FiniteElement< dim, spacedim > * > & fes, const std::vector< unsigned int > & multiplicities, const bool do_tensor_product = true )

Compute the nonzero components for each shape function of a composed finite element described by a list of finite elements with multiplicities given in the second argument.

If do_tensor_product is true, the number of components (and thus the size of the ComponentMask objects) is the sum over the product of the number of components in each of the finite elements times the corresponding multiplicity. Otherwise the number of components is taken from the first finite element with non-zero multiplicity, and all other elements with non-zero multiplicities need to have the same number of vector components.

See the documentation of namespace FETools::Compositing for more information about the do_tensor_product argument.

Definition at line 351 of file fe_tools.cc.

template<int dim, int spacedim>
 std::vector< ComponentMask > FETools::Compositing::compute_nonzero_components ( const FiniteElement< dim, spacedim > * fe1, const unsigned int N1, const FiniteElement< dim, spacedim > * fe2 = NULL, const unsigned int N2 = 0, const FiniteElement< dim, spacedim > * fe3 = NULL, const unsigned int N3 = 0, const FiniteElement< dim, spacedim > * fe4 = NULL, const unsigned int N4 = 0, const FiniteElement< dim, spacedim > * fe5 = NULL, const unsigned int N5 = 0, const bool do_tensor_product = true )

Compute the non-zero vector components of a composed finite element. This function is similar to the previous one, except that the pointers indicate the elements to be composed, and the arguments N1, N2, ... the multiplicities. Null pointers indicate that an argument is to be skipped.

If do_tensor_product is true, the number of components (and thus the size of the ComponentMask objects) is the sum over the product of the number of components in each of the finite elements times the corresponding multiplicity. Otherwise the number of components is taken from the first finite element with non-zero multiplicity, and all other elements with non-zero multiplicities need to have the same number of vector components.

See the documentation of namespace FETools::Compositing for more information about the do_tensor_product argument.

Compute the non-zero vector components of a composed finite element.

Definition at line 543 of file fe_tools.cc.

template<int dim, int spacedim>
 void FETools::Compositing::build_cell_tables ( std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > & system_to_base_table, std::vector< std::pair< unsigned int, unsigned int > > & system_to_component_table, std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > & component_to_base_table, const FiniteElement< dim, spacedim > & finite_element, const bool do_tensor_product = true )

For a given (composite) finite_element build system_to_component_table, system_to_base_table and component_to_base_table.

If do_tensor_product is true, the number of components used for the composite element is the sum over the product of the number of components in each of the finite elements times the corresponding multiplicity. Otherwise the number of components is taken from the first finite element with non-zero multiplicity, and all other elements with non-zero multiplicities need to have the same number of vector components.

See the documentation of namespace FETools::Compositing for more information about the do_tensor_product argument.

Definition at line 581 of file fe_tools.cc.

template<int dim, int spacedim>
 void FETools::Compositing::build_face_tables ( std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int > > & face_system_to_base_table, std::vector< std::pair< unsigned int, unsigned int > > & face_system_to_component_table, const FiniteElement< dim, spacedim > & finite_element, const bool do_tensor_product = true )

For a given (composite) finite_element build face_system_to_base_table, and face_system_to_component_table.

If do_tensor_product is true, the number of components used for the composite element is the sum over the product of the number of components in each of the finite elements times the corresponding multiplicity. Otherwise the number of components is taken from the first finite element with non-zero multiplicity, and all other elements with non-zero multiplicities need to have the same number of vector components.

See the documentation of namespace FETools::Compositing for more information about the do_tensor_product argument.

Definition at line 776 of file fe_tools.cc.