FEAT 3
Finite Element Analysis Toolbox
Loading...
Searching...
No Matches
FEAT::Assembly::DomainAssembler< Trafo_ > Class Template Reference

Domain Integral Assembler class template. More...

#include <domain_assembler.hpp>

Classes

class  ThreadStats
 Thread statistics helper class. More...
 
class  Worker
 Worker thread data class. More...
 

Public Types

typedef TrafoType::MeshType MeshType
 the underlying mesh type More...
 
typedef Trafo_ TrafoType
 the underlying trafo type More...
 

Public Member Functions

 DomainAssembler (const DomainAssembler &)=delete
 delete copy constructor
 
 DomainAssembler (const TrafoType &trafo)
 Constructor. More...
 
virtual ~DomainAssembler ()
 virtual destructor More...
 
void add_element (Index ielem)
 Adds a single element to the assembler. More...
 
void add_mesh_part (const Geometry::MeshPart< MeshType > &mesh_part)
 Adds all elements of a mesh-part to the assembler. More...
 
template<typename Job_ >
void assemble (Job_ &job)
 Executes a domain assembly job (in parallel) by (multiple) worker threads. More...
 
template<typename Job_ >
void assemble_master (Job_ &job)
 Executes a domain assembly job directly on the calling thread. More...
 
template<typename Job_ >
void assemble_omp (Job_ &job)
 
void clear ()
 Clears the assembler. More...
 
void compile ()
 Compiles the assembler for all elements that have been added manually. More...
 
void compile_all_elements ()
 Compiles the assembler for all elements of the underlying mesh. More...
 
String dump () const
 Returns a string dump of various debugging information. More...
 
const std::vector< Index > & get_element_indices () const
 Returns the element indices vector. More...
 
std::size_t get_max_worker_threads () const
 Returns the maximum number of worker threads. More...
 
std::size_t get_num_worker_threads () const
 Returns the actual number of worker threads. More...
 
ThreadingStrategy get_threading_strategy () const
 Returns the threading strategy. More...
 
const Trafo_ & get_trafo () const
 Returns a reference to the domain assembler's trafo. More...
 
DomainAssembleroperator= (const DomainAssembler &)=delete
 delete copy assignment operator
 
ThreadStats reduce_thread_stats () const
 Reduces the thread statistics to a single object. More...
 
void reset_thread_stats ()
 Resets the thread statistics. More...
 
void set_max_worker_threads (std::size_t max_worker_threads)
 Sets the maximum number of worker threads. More...
 
void set_threading_strategy (ThreadingStrategy strategy)
 Sets the desired threading strategy. More...
 

Static Public Attributes

static constexpr int shape_dim = MeshType::shape_dim
 the shape dimension More...
 

Protected Member Functions

void _build_colors ()
 Builds the color element vectors for the colored threading strategy. More...
 
void _build_graphs ()
 Builds the element adjacencies graphs. More...
 
void _build_layers (bool reverse, bool sorted)
 Builds the Cuthill-McKee layer graphs. More...
 
bool _build_thread_layers ()
 Build the actual thread layers for the layered strategy. More...
 
void _compile ()
 Compiles the domain assembler. More...
 

Protected Attributes

std::vector< Index_color_elements
 a vector of element color offsets More...
 
bool _compiled
 specifies whether the assembler has already been compiled More...
 
Adjacency::Graph _elem_neighbors
 adjacency graph for element neighbors More...
 
std::vector< Index_element_indices
 a vector of all elements to assemble on More...
 
std::vector< char > _element_mask
 an element mask vector More...
 
Adjacency::Graph _elems_at_vert
 adjacency graph for elements-at-vertex More...
 
std::vector< Index_layer_elements
 a vector of element layer offsets More...
 
std::size_t _max_worker_threads
 specifies the maximum number of worker threads to use More...
 
std::size_t _num_worker_threads
 specifies the actual number of worker threads to use More...
 
ThreadingStrategy _strategy
 specifies the chosen threading strategy More...
 
std::vector< ThreadFence_thread_fences
 a vector of thread fences More...
 
std::vector< Index_thread_layers
 a vector of thread layer blocks More...
 
std::mutex _thread_mutex
 a mutex for free use by the worker threads More...
 
std::vector< ThreadStats_thread_stats
 a vector of thread statistics More...
 
std::vector< std::thread > _threads
 a vector of worker threads More...
 
const TrafoType_trafo
 a reference to the underlying trafo More...
 
Adjacency::Graph _verts_at_elem
 adjacency graph for vertices-at-element More...
 

Detailed Description

template<typename Trafo_>
class FEAT::Assembly::DomainAssembler< Trafo_ >

Domain Integral Assembler class template.

This class implements a multi-threaded domain assembler, which is capable of executing domain assembly jobs.

After you have constructed the domain assembler object, there are still a few steps left that have to be performed before you can assemble a assembly job by the domain assembler:

  • Optional: You can choose a specific threading strategy by calling the set_threading_strategy member function or you can just stick with the default automatic strategy that is preselected.
  • Optional: You can choose the maximum number of desired worker threads for the multi-threaded assembly by calling the set_max_worker_threads member function. Skipping this step always results in single-threaded assembly.
  • If you want to assemble on the whole domain, i.e. on all elements of the mesh (which is the usual case), all you have to do as a final mandatory step is to call the compile_all_elements() member function.
  • If you want to assemble on a subset of the domain, you have to add all elements to the domain assembler by either adding them individually using the add_element() function or by adding them as mesh-parts using the add_mesh_part() member function. Once all elements have been added, you have to call the compile() member function.
Note
Each domain assembler object is tied to the trafo object that is has been constructed on, i.e. if you have several different trafo objects (such as in a multigrid scenario) then you also need several domain assembler objects – one for each trafo object. Also, a domain assembler always assembles over the elements of its trafo, so all FE spaces used in the assembly have to be defined on the same trafo object as the domain assembler.
Attention
Please be aware that the setup of a DomainAssembler object is a rather expensive operation, because the assembler has to perform a lot of internal initialization including an analysis of the element adjacency pattern as well as applying graph coloring/layering algorithms, which (in general) may have super-linear runtime. Therefore you should always hang on to a DomainAssembler object once it has been created and avoid re-creation of several DomainAssembler objects that could have been avoided by saving a previously created DomainAssembler object.
Author
Peter Zajac

Definition at line 393 of file domain_assembler.hpp.

Member Typedef Documentation

◆ MeshType

template<typename Trafo_ >
typedef TrafoType::MeshType FEAT::Assembly::DomainAssembler< Trafo_ >::MeshType

the underlying mesh type

Definition at line 399 of file domain_assembler.hpp.

◆ TrafoType

template<typename Trafo_ >
typedef Trafo_ FEAT::Assembly::DomainAssembler< Trafo_ >::TrafoType

the underlying trafo type

Definition at line 397 of file domain_assembler.hpp.

Constructor & Destructor Documentation

◆ DomainAssembler()

template<typename Trafo_ >
FEAT::Assembly::DomainAssembler< Trafo_ >::DomainAssembler ( const TrafoType trafo)
inlineexplicit

Constructor.

Parameters
[in]trafoA resident reference to the transformation that defines the assembly domain.

Definition at line 998 of file domain_assembler.hpp.

◆ ~DomainAssembler()

template<typename Trafo_ >
virtual FEAT::Assembly::DomainAssembler< Trafo_ >::~DomainAssembler ( )
inlinevirtual

virtual destructor

Definition at line 1024 of file domain_assembler.hpp.

Member Function Documentation

◆ _build_colors()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::_build_colors ( )
inlineprotected

Builds the color element vectors for the colored threading strategy.

Todo:
utilize mesh permutation coloring if available

Definition at line 1922 of file domain_assembler.hpp.

References FEAT::Adjacency::Coloring::create_partition_graph(), FEAT::Adjacency::Graph::degree(), FEAT::Adjacency::Graph::get_domain_ptr(), FEAT::Adjacency::Graph::get_image_idx(), FEAT::Math::min(), and XASSERT.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::_compile().

◆ _build_graphs()

◆ _build_layers()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::_build_layers ( bool  reverse,
bool  sorted 
)
inlineprotected

Builds the Cuthill-McKee layer graphs.

Parameters
[in]reverseSpecifies whether to reverse the ordering.
[in]sortedSpecifies whether to sort entities in each layer by their degree.
Todo:
utilize mesh permutation layering if available

Definition at line 1686 of file domain_assembler.hpp.

References FEAT::Adjacency::Graph::degree(), FEAT::Adjacency::Graph::get_domain_ptr(), FEAT::Adjacency::Graph::get_image_idx(), and XASSERTM.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::_compile().

◆ _build_thread_layers()

template<typename Trafo_ >
bool FEAT::Assembly::DomainAssembler< Trafo_ >::_build_thread_layers ( )
inlineprotected

Build the actual thread layers for the layered strategy.

Definition at line 1829 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_num_worker_threads, FEAT::Math::min(), and XASSERT.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::_compile().

◆ _compile()

◆ add_element()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::add_element ( Index  ielem)
inline

Adds a single element to the assembler.

Parameters
[in]ielemThe index of the mesh element that is to be added.
Note
If the element ielem has already been added to the assembler by calling this function or the add_mesh_part function, then it will not be added a second time, so every element is processed at most once, no matter how often it has been added to the assembler.

Definition at line 1060 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compiled, and XASSERTM.

◆ add_mesh_part()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::add_mesh_part ( const Geometry::MeshPart< MeshType > &  mesh_part)
inline

Adds all elements of a mesh-part to the assembler.

Parameters
[in]mesh_partA transient reference to the mesh part whose elements are to be added.
Note
If an element in the mesh-part has already been added to the assembler by calling this function or the add_element function, then it will not be added a second time, so every element is processed at most once, no matter how often it has been added to the assembler.

Definition at line 1077 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compiled, and XASSERTM.

◆ assemble()

◆ assemble_master()

template<typename Trafo_ >
template<typename Job_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::assemble_master ( Job_ &  job)
inline

Executes a domain assembly job directly on the calling thread.

This function executes the assembly job directly on the calling thread without spawning dedicated worker threads, which makes debugging of assembly jobs and tasks much easier. Note that as a consequence, the assembly performed by this function is always single-threaded even if the assembler has been configured to work with multiple threads.

Parameters
[in,out]jobA transient reference to the job that is to be assembled. See Assembly::DomainAssemblyJob for details.

Definition at line 1335 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compiled, FEAT::Assembly::DomainAssembler< Trafo_ >::_threads, and XASSERTM.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::assemble().

◆ assemble_omp()

template<typename Trafo_ >
template<typename Job_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::assemble_omp ( Job_ &  job)
inline

Definition at line 1362 of file domain_assembler.hpp.

◆ clear()

◆ compile()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::compile ( )
inline

Compiles the assembler for all elements that have been added manually.

This function compiles the assembler for all cells/elements that have been added manually by previous calls of the add_element or add_mesh_part functions according to the chosen threading strategy and desired maximum worker thread count.

Note
If you want to compile the assembler for all cells/elements of the trafo's underlying mesh, consider using the compile_all_elements() function instead.

Definition at line 1168 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compile(), FEAT::Assembly::DomainAssembler< Trafo_ >::_element_indices, XASSERT, and XASSERTM.

◆ compile_all_elements()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::compile_all_elements ( )
inline

Compiles the assembler for all elements of the underlying mesh.

This function compiles the assembler for all elements of the trafo's underlying mesh according to the chosen threading strategy and desired maximum worker thread count.

Definition at line 1193 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compile(), FEAT::Assembly::DomainAssembler< Trafo_ >::_element_indices, XASSERT, and XASSERTM.

◆ dump()

template<typename Trafo_ >
String FEAT::Assembly::DomainAssembler< Trafo_ >::dump ( ) const
inline

Returns a string dump of various debugging information.

Returns
A string dump of various debugging information

Definition at line 1483 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_strategy, FEAT::Assembly::layered, FEAT::Math::max(), FEAT::String::pad_front(), FEAT::stringify(), and FEAT::stringify_fp_fix().

◆ get_element_indices()

template<typename Trafo_ >
const std::vector< Index > & FEAT::Assembly::DomainAssembler< Trafo_ >::get_element_indices ( ) const
inline

Returns the element indices vector.

Definition at line 1096 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_element_indices.

◆ get_max_worker_threads()

template<typename Trafo_ >
std::size_t FEAT::Assembly::DomainAssembler< Trafo_ >::get_max_worker_threads ( ) const
inline

Returns the maximum number of worker threads.

Definition at line 1116 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_max_worker_threads.

◆ get_num_worker_threads()

template<typename Trafo_ >
std::size_t FEAT::Assembly::DomainAssembler< Trafo_ >::get_num_worker_threads ( ) const
inline

Returns the actual number of worker threads.

This returned count corresponds to the actual number of worker threads used for assembling, which may be lower than the maximum number of worker requested by the user.

Note
The assembler has to be compiled before calling this function, because the actual number of worker threads to use is determined in the compilation process.

Definition at line 1130 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_num_worker_threads.

◆ get_threading_strategy()

template<typename Trafo_ >
ThreadingStrategy FEAT::Assembly::DomainAssembler< Trafo_ >::get_threading_strategy ( ) const
inline

Returns the threading strategy.

Definition at line 1152 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_strategy.

◆ get_trafo()

◆ reduce_thread_stats()

template<typename Trafo_ >
ThreadStats FEAT::Assembly::DomainAssembler< Trafo_ >::reduce_thread_stats ( ) const
inline

Reduces the thread statistics to a single object.

Returns
A combined thread statistics object.

Definition at line 1544 of file domain_assembler.hpp.

◆ reset_thread_stats()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::reset_thread_stats ( )
inline

Resets the thread statistics.

Definition at line 1533 of file domain_assembler.hpp.

◆ set_max_worker_threads()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::set_max_worker_threads ( std::size_t  max_worker_threads)
inline

Sets the maximum number of worker threads.

Attention
The number of worker threads has to be set before the assembler is compiled.

Definition at line 1107 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compiled, and XASSERTM.

◆ set_threading_strategy()

template<typename Trafo_ >
void FEAT::Assembly::DomainAssembler< Trafo_ >::set_threading_strategy ( ThreadingStrategy  strategy)
inline

Sets the desired threading strategy.

See Assembly::ThreadingStrategy for details.

Attention
The threading strategy has to be set before the assembler is compiled.

Definition at line 1143 of file domain_assembler.hpp.

References FEAT::Assembly::DomainAssembler< Trafo_ >::_compiled, and XASSERTM.

Member Data Documentation

◆ _color_elements

template<typename Trafo_ >
std::vector<Index> FEAT::Assembly::DomainAssembler< Trafo_ >::_color_elements
protected

a vector of element color offsets

Definition at line 969 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _compiled

◆ _elem_neighbors

template<typename Trafo_ >
Adjacency::Graph FEAT::Assembly::DomainAssembler< Trafo_ >::_elem_neighbors
protected

adjacency graph for element neighbors

Definition at line 963 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _element_indices

◆ _element_mask

template<typename Trafo_ >
std::vector<char> FEAT::Assembly::DomainAssembler< Trafo_ >::_element_mask
protected

an element mask vector

Definition at line 965 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _elems_at_vert

template<typename Trafo_ >
Adjacency::Graph FEAT::Assembly::DomainAssembler< Trafo_ >::_elems_at_vert
protected

adjacency graph for elements-at-vertex

Definition at line 961 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _layer_elements

template<typename Trafo_ >
std::vector<Index> FEAT::Assembly::DomainAssembler< Trafo_ >::_layer_elements
protected

a vector of element layer offsets

Definition at line 971 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _max_worker_threads

template<typename Trafo_ >
std::size_t FEAT::Assembly::DomainAssembler< Trafo_ >::_max_worker_threads
protected

specifies the maximum number of worker threads to use

Definition at line 985 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::get_max_worker_threads().

◆ _num_worker_threads

template<typename Trafo_ >
std::size_t FEAT::Assembly::DomainAssembler< Trafo_ >::_num_worker_threads
protected

◆ _strategy

template<typename Trafo_ >
ThreadingStrategy FEAT::Assembly::DomainAssembler< Trafo_ >::_strategy
protected

specifies the chosen threading strategy

Definition at line 983 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::dump(), and FEAT::Assembly::DomainAssembler< Trafo_ >::get_threading_strategy().

◆ _thread_fences

template<typename Trafo_ >
std::vector<ThreadFence> FEAT::Assembly::DomainAssembler< Trafo_ >::_thread_fences
protected

a vector of thread fences

Definition at line 975 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _thread_layers

template<typename Trafo_ >
std::vector<Index> FEAT::Assembly::DomainAssembler< Trafo_ >::_thread_layers
protected

a vector of thread layer blocks

Definition at line 973 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ _thread_mutex

template<typename Trafo_ >
std::mutex FEAT::Assembly::DomainAssembler< Trafo_ >::_thread_mutex
protected

a mutex for free use by the worker threads

Definition at line 981 of file domain_assembler.hpp.

◆ _thread_stats

template<typename Trafo_ >
std::vector<ThreadStats> FEAT::Assembly::DomainAssembler< Trafo_ >::_thread_stats
protected

◆ _threads

◆ _trafo

template<typename Trafo_ >
const TrafoType& FEAT::Assembly::DomainAssembler< Trafo_ >::_trafo
protected

a reference to the underlying trafo

Definition at line 957 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::get_trafo().

◆ _verts_at_elem

template<typename Trafo_ >
Adjacency::Graph FEAT::Assembly::DomainAssembler< Trafo_ >::_verts_at_elem
protected

adjacency graph for vertices-at-element

Definition at line 959 of file domain_assembler.hpp.

Referenced by FEAT::Assembly::DomainAssembler< Trafo_ >::clear().

◆ shape_dim

template<typename Trafo_ >
constexpr int FEAT::Assembly::DomainAssembler< Trafo_ >::shape_dim = MeshType::shape_dim
staticconstexpr

the shape dimension

Definition at line 401 of file domain_assembler.hpp.


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