libMesh
Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
libMesh::GhostingFunctor Class Referenceabstract

This abstract base class defines the interface by which library code and user code can report associations between elements. More...

#include <ghosting_functor.h>

Inheritance diagram for libMesh::GhostingFunctor:
[legend]

Public Types

typedef std::map< const Elem *, const CouplingMatrix *, CompareDofObjectsByPIDAndThenIDmap_type
 What elements do we care about and what variables do we care about on each element? More...
 

Public Member Functions

 GhostingFunctor ()
 Constructor. More...
 
 GhostingFunctor (const MeshBase &mesh)
 Constructor using mesh. More...
 
 GhostingFunctor (const GhostingFunctor &other)
 Copy Constructor. More...
 
virtual ~GhostingFunctor ()=default
 Virtual destructor; this is an abstract base class. More...
 
virtual std::unique_ptr< GhostingFunctorclone () const
 A clone() is needed because GhostingFunctor can not be shared between different meshes. More...
 
virtual void set_mesh (const MeshBase *mesh)
 It should be called after cloning a ghosting functor. More...
 
virtual void set_periodic_boundaries (const PeriodicBoundaries *)
 
const MeshBaseget_mesh () const
 Return the mesh associated with ghosting functor. More...
 
virtual void operator() (const MeshBase::const_element_iterator &range_begin, const MeshBase::const_element_iterator &range_end, processor_id_type p, map_type &coupled_elements)=0
 For the specified range of active elements, what other elements currently living (whether local or ghosted) on this processor need to be coupled/ghosted to accommodate them? Don't bother to return any results which already have processor_id p. More...
 
virtual void mesh_reinit ()
 GhostingFunctor subclasses which cache data will need to initialize that cache. More...
 
virtual void dofmap_reinit ()
 For algebraic ghosting or coupling functors we also call dofmap_reinit() later, after dofs have been distributed on the new mesh but before the functors have been queried for send_list or sparsity pattern calculations. More...
 
virtual void redistribute ()
 GhostingFunctor subclasses with relatively long-lasting caches may want to redistribute those caches whenever the relevant Mesh is redistributed; we will give them an opportunity when that happens. More...
 
virtual void delete_remote_elements ()
 GhostingFunctor subclasses with relatively long-lasting caches may want to delete the no-longer-relevant parts of those caches after a redistribution is complete. More...
 

Static Public Member Functions

static std::string get_info ()
 Gets a string containing the reference information. More...
 
static void print_info (std::ostream &out_stream=libMesh::out)
 Prints the reference information, by default to libMesh::out. More...
 
static unsigned int n_objects ()
 Prints the number of outstanding (created, but not yet destroyed) objects. More...
 
static void enable_print_counter_info ()
 Methods to enable/disable the reference counter output from print_info() More...
 
static void disable_print_counter_info ()
 

Protected Types

typedef std::map< std::string, std::pair< unsigned int, unsigned int > > Counts
 Data structure to log the information. More...
 

Protected Member Functions

void increment_constructor_count (const std::string &name) noexcept
 Increments the construction counter. More...
 
void increment_destructor_count (const std::string &name) noexcept
 Increments the destruction counter. More...
 

Protected Attributes

const MeshBase_mesh
 

Static Protected Attributes

static Counts _counts
 Actually holds the data. More...
 
static Threads::atomic< unsigned int_n_objects
 The number of objects. More...
 
static Threads::spin_mutex _mutex
 Mutual exclusion object to enable thread-safe reference counting. More...
 
static bool _enable_print_counter = true
 Flag to control whether reference count information is printed when print_info is called. More...
 

Detailed Description

This abstract base class defines the interface by which library code and user code can report associations between elements.

These associations between elements may be used to keep copies of non-local elements retained on a distributed mesh, may be used to keep element degrees of freedom properly communicated on a distributed vector, and/or may be used to insert coupling entries between elements' degrees of freedom to a sparsity matrix.

We can think of three levels of "element dependencies". An element K1 has a coupling dependency on K2 if the dofs on K1 might (modulo the coupling matrix) need sparsity pattern entries for dofs on K2. An element K1 has an algebraic dependency on K2 if a processor which owns K1 might need to examine the solution dof values on K2. An element K1 has a geometric dependency on K2 if a processor which owns K1 might need to examine the geometry of K2. For any element K, we could call the set of coupling-ghosted ("coupled") elements C(K), call the set of algebraic-ghosted ("evaluable") elements E(K), and call the set of geometry-ghosted ("ghosted") elements G(K).

It should be safe to assume that, for any element K, C(K) implies E(K) implies G(K). These will be one-way implications in some problems and equality relations in others.

We can think of these as operators on sets of elements in the obvious way, e.g.: G({K}) = {G(Ki) for all Ki in {K}}.

The user should omit from their implementations relations which we already have enough information to understand implicitly. For instance, K is obviously in C(K), so a GhostingFunctor should never bother telling us so. We pass a processor_id_type parameter to the GhostingFunctor::operator(), e.g. when determining what ghosted elements need to be sent to that processor while redistributing, and a GhostingFunctor should not return any elements which already have that processor_id. We determine what ancestor elements should be ghosted based on what active elements are being ghosted, and a GhostingFunctor should not return any elements which are not active.

We may have a PeriodicBoundary, a hanging node constraint equation, or a user-defined constraint equation which creates a dependency between two elements; if so then we don't need the user to also tell us about that relation. The DefaultCoupling functor will make both direct and periodic neighbor elements algebraically ghosted by default.

However, note that geometric ghosting information needs to all be inferrable (e.g. with PeriodicBoundary objects already all attached) before a mesh is prepared for use; otherwise ghost elements may be prematurely deleted and become unrecoverable.

For iterating over ghosted elements:

MeshBase::active_elements_begin() gives the first iterator to all geometrically ghosted elements. (this means all elements on any mesh which isn't distributed)

MeshBase::evaluable_elements_begin() gives the first iterator to all algebraically evaluable elements, which is a superset of all algebraically ghosted elements. (rarely a strict superset, but low order geometrically ghosted elements surrounded by enough algebraically ghosted elements may become evaluable "by accident")

Users may only care about a subset of variables in distant evaluable elements, so we could imagine defining E_v(K) for each variable number v, in which case E(K) under our previous definition is the union of E_v(K) forall v, and this is what would be included in G(K) when deciding what to ghost, but our send_list would only include the subset of variables we need, so communication and memory use would be much reduced. However, for efficiency and API simplicity, we instead define the isomorphic operator E'(K) which gives a set of ordered pairs of elements and variable-number-sets, from which a consistent E(K) would be derived by ignoring the variable-number-sets.

For C(K), there are similar issues: e.g. we may want some discontinuous variables to couple only within their own element but other discontinuous variables to couple in a DG/FVM way. This could extend to more than one variable index: i.e. a dof for variable v1 in element K1 would depend on a dof for variable v2 in element K2 iff K2 is in C_v1_v2(K1). This would induce a consistent E_v(K) = union of C_w_v(K) forall variable indices w. Again, the equivalent API alternative we use here is for C'(K) to return a set of ordered pairs of elements and variable-number-pair-sets.

We return variable-stuff-sets as pointers to CouplingMatrix. That way, in the common case where the user cares about all variables and couple to all variables, all the functor needs to return for variable-number-sets and variable-number-pair-sets is nullptr (which as in other libMesh APIs will be interpreted and documented to mean the full set). In the common case where the user wants coupling between elements to match coupling within elements, the functor can return the same pointer as DofMap::_coupling_matrix. Even in the less common cases, the user can store common variable-number-sets and variable-number-pair sets as CouplingMatrix members of a functor object of their subclass, and setting up a few of those matrices then setting lots of those pointers is cheap.

The definition of the CouplingMatrix for a variable-dependent E' should be consistent with the requirements that would have been imposed had that matrix been used for a C'. In other words, if the returned CouplingMatrix CM has CM(i,j)==true for any i, then variable j will be evaluable on the algebraically ghosted element.

After a GhostingFunctor has been created, a reference to it can be passed to MeshBase::add_ghosting_functor to expand geometric ghosting, or to DofMap::add_algebraic_ghosting_functor to expand both algebraic and geometric ghosting, or to DofMap::add_coupling_functor to expand coupling along with both types of ghosting.

Note that when an element is specified in algebraic ghosting or coupling queries, only degrees of freedom for the variables supported on that element are thereby ghosted and/or coupled. Any unsupported variable dofs associated with the element's nodes (e.g. subdomain-restricted variables on a neighboring subdomain) will be unaffected.

Typical usage of the GhostingFunctor would be to add a geometric ghosting functor before the mesh preparation is completed; progmatically, this would be before MeshBase::prepare_for_use() is called, but many different libMesh idioms internally call this function. The algebraic and coupling ghosting functors normally are added before EquationSystems::init() is called. However, in some circumstances, solution evaluation may be needed within the GhostingFunctor in order to determine the ghosting, in which case the appropriate functor would need to be added after EquationSystems::init(). In this case, the user will need to reinitialize certain parts of the DofMap for algebraic and coupling functors. For algebraic ghosting functors, the user will need to call DofMap::reinit_send_list() and then reinitialize any NumericVectors that are GHOSTED, e.g. the System::current_local_solution. For coupling ghosting, the user will also need to recompute the sparsity pattern via DofMap::clear_sparsity() and then DofMap::compute_sparsity() and then reinitialize any SparseMatrix objects attached to the System, e.g. the system.get_system_matrix().

Author
Roy H. Stogner
Date
2016

Definition at line 184 of file ghosting_functor.h.

Member Typedef Documentation

◆ Counts

typedef std::map<std::string, std::pair<unsigned int, unsigned int> > libMesh::ReferenceCounter::Counts
protectedinherited

Data structure to log the information.

The log is identified by the class name.

Definition at line 119 of file reference_counter.h.

◆ map_type

What elements do we care about and what variables do we care about on each element?

Definition at line 241 of file ghosting_functor.h.

Constructor & Destructor Documentation

◆ GhostingFunctor() [1/3]

libMesh::GhostingFunctor::GhostingFunctor ( )
inline

Constructor.

Empty in the base class.

Definition at line 191 of file ghosting_functor.h.

191 : _mesh(nullptr) {}

◆ GhostingFunctor() [2/3]

libMesh::GhostingFunctor::GhostingFunctor ( const MeshBase mesh)
inline

Constructor using mesh.

Definition at line 196 of file ghosting_functor.h.

196 : _mesh(&mesh) {}
MeshBase & mesh

◆ GhostingFunctor() [3/3]

libMesh::GhostingFunctor::GhostingFunctor ( const GhostingFunctor other)
inline

Copy Constructor.

Definition at line 201 of file ghosting_functor.h.

201  :
202  ReferenceCountedObject<GhostingFunctor>(other),
203  _mesh (other._mesh)
204  {}

◆ ~GhostingFunctor()

virtual libMesh::GhostingFunctor::~GhostingFunctor ( )
virtualdefault

Virtual destructor; this is an abstract base class.

Member Function Documentation

◆ clone()

virtual std::unique_ptr<GhostingFunctor> libMesh::GhostingFunctor::clone ( ) const
inlinevirtual

A clone() is needed because GhostingFunctor can not be shared between different meshes.

The operations in GhostingFunctor are mesh dependent.

Reimplemented in libMesh::DefaultCoupling, libMesh::PointNeighborCoupling, and libMesh::SiblingCoupling.

Definition at line 215 of file ghosting_functor.h.

Referenced by libMesh::MeshBase::MeshBase().

219  { return nullptr; }

◆ delete_remote_elements()

virtual void libMesh::GhostingFunctor::delete_remote_elements ( )
inlinevirtual

GhostingFunctor subclasses with relatively long-lasting caches may want to delete the no-longer-relevant parts of those caches after a redistribution is complete.

Reimplemented in libMesh::PointNeighborCoupling, libMesh::DefaultCoupling, and libMesh::GhostPointNeighbors.

Definition at line 291 of file ghosting_functor.h.

291 {};

◆ disable_print_counter_info()

void libMesh::ReferenceCounter::disable_print_counter_info ( )
staticinherited

Definition at line 100 of file reference_counter.C.

References libMesh::ReferenceCounter::_enable_print_counter.

101 {
102  _enable_print_counter = false;
103  return;
104 }
static bool _enable_print_counter
Flag to control whether reference count information is printed when print_info is called...

◆ dofmap_reinit()

virtual void libMesh::GhostingFunctor::dofmap_reinit ( )
inlinevirtual

For algebraic ghosting or coupling functors we also call dofmap_reinit() later, after dofs have been distributed on the new mesh but before the functors have been queried for send_list or sparsity pattern calculations.

Definition at line 272 of file ghosting_functor.h.

272 {};

◆ enable_print_counter_info()

void libMesh::ReferenceCounter::enable_print_counter_info ( )
staticinherited

Methods to enable/disable the reference counter output from print_info()

Definition at line 94 of file reference_counter.C.

References libMesh::ReferenceCounter::_enable_print_counter.

95 {
96  _enable_print_counter = true;
97  return;
98 }
static bool _enable_print_counter
Flag to control whether reference count information is printed when print_info is called...

◆ get_info()

std::string libMesh::ReferenceCounter::get_info ( )
staticinherited

Gets a string containing the reference information.

Definition at line 47 of file reference_counter.C.

References libMesh::ReferenceCounter::_counts, and libMesh::Quality::name().

Referenced by libMesh::ReferenceCounter::print_info().

48 {
49 #if defined(LIBMESH_ENABLE_REFERENCE_COUNTING) && defined(DEBUG)
50 
51  std::ostringstream oss;
52 
53  oss << '\n'
54  << " ---------------------------------------------------------------------------- \n"
55  << "| Reference count information |\n"
56  << " ---------------------------------------------------------------------------- \n";
57 
58  for (const auto & [name, cd] : _counts)
59  oss << "| " << name << " reference count information:\n"
60  << "| Creations: " << cd.first << '\n'
61  << "| Destructions: " << cd.second << '\n';
62 
63  oss << " ---------------------------------------------------------------------------- \n";
64 
65  return oss.str();
66 
67 #else
68 
69  return "";
70 
71 #endif
72 }
std::string name(const ElemQuality q)
This function returns a string containing some name for q.
Definition: elem_quality.C:42
static Counts _counts
Actually holds the data.

◆ get_mesh()

const MeshBase* libMesh::GhostingFunctor::get_mesh ( ) const
inline

Return the mesh associated with ghosting functor.

Definition at line 235 of file ghosting_functor.h.

References _mesh, and libMesh::libmesh_assert().

235 { libmesh_assert(_mesh); return _mesh; }
libmesh_assert(ctx)

◆ increment_constructor_count()

void libMesh::ReferenceCounter::increment_constructor_count ( const std::string &  name)
inlineprotectednoexceptinherited

Increments the construction counter.

Should be called in the constructor of any derived class that will be reference counted.

Definition at line 183 of file reference_counter.h.

References libMesh::err, libMesh::BasicOStreamProxy< charT, traits >::get(), libMesh::Quality::name(), and libMesh::Threads::spin_mtx.

Referenced by libMesh::ReferenceCountedObject< RBParametrized >::ReferenceCountedObject().

184 {
185  libmesh_try
186  {
187  Threads::spin_mutex::scoped_lock lock(Threads::spin_mtx);
188  std::pair<unsigned int, unsigned int> & p = _counts[name];
189  p.first++;
190  }
191  libmesh_catch (...)
192  {
193  auto stream = libMesh::err.get();
194  stream->exceptions(stream->goodbit); // stream must not throw
195  libMesh::err << "Encountered unrecoverable error while calling "
196  << "ReferenceCounter::increment_constructor_count() "
197  << "for a(n) " << name << " object." << std::endl;
198  std::terminate();
199  }
200 }
std::string name(const ElemQuality q)
This function returns a string containing some name for q.
Definition: elem_quality.C:42
OStreamProxy err
static Counts _counts
Actually holds the data.
streamT * get()
Rather than implement every ostream/ios/ios_base function, we&#39;ll be lazy and make esoteric uses go th...
spin_mutex spin_mtx
A convenient spin mutex object which can be used for obtaining locks.
Definition: threads.C:30

◆ increment_destructor_count()

void libMesh::ReferenceCounter::increment_destructor_count ( const std::string &  name)
inlineprotectednoexceptinherited

Increments the destruction counter.

Should be called in the destructor of any derived class that will be reference counted.

Definition at line 207 of file reference_counter.h.

References libMesh::err, libMesh::BasicOStreamProxy< charT, traits >::get(), libMesh::Quality::name(), and libMesh::Threads::spin_mtx.

Referenced by libMesh::ReferenceCountedObject< RBParametrized >::~ReferenceCountedObject().

208 {
209  libmesh_try
210  {
211  Threads::spin_mutex::scoped_lock lock(Threads::spin_mtx);
212  std::pair<unsigned int, unsigned int> & p = _counts[name];
213  p.second++;
214  }
215  libmesh_catch (...)
216  {
217  auto stream = libMesh::err.get();
218  stream->exceptions(stream->goodbit); // stream must not throw
219  libMesh::err << "Encountered unrecoverable error while calling "
220  << "ReferenceCounter::increment_destructor_count() "
221  << "for a(n) " << name << " object." << std::endl;
222  std::terminate();
223  }
224 }
std::string name(const ElemQuality q)
This function returns a string containing some name for q.
Definition: elem_quality.C:42
OStreamProxy err
static Counts _counts
Actually holds the data.
streamT * get()
Rather than implement every ostream/ios/ios_base function, we&#39;ll be lazy and make esoteric uses go th...
spin_mutex spin_mtx
A convenient spin mutex object which can be used for obtaining locks.
Definition: threads.C:30

◆ mesh_reinit()

virtual void libMesh::GhostingFunctor::mesh_reinit ( )
inlinevirtual

GhostingFunctor subclasses which cache data will need to initialize that cache.

We call mesh_reinit() whenever the relevant Mesh has changed, but before remote elements on a distributed mesh are deleted.

Reimplemented in AugmentSparsityOnNodes, libMesh::PointNeighborCoupling, libMesh::DefaultCoupling, and AugmentSparsityOnInterface.

Definition at line 264 of file ghosting_functor.h.

Referenced by libMesh::GhostPointNeighbors::delete_remote_elements().

264 {};

◆ n_objects()

static unsigned int libMesh::ReferenceCounter::n_objects ( )
inlinestaticinherited

Prints the number of outstanding (created, but not yet destroyed) objects.

Definition at line 85 of file reference_counter.h.

References libMesh::ReferenceCounter::_n_objects.

Referenced by libMesh::LibMeshInit::~LibMeshInit().

86  { return _n_objects; }
static Threads::atomic< unsigned int > _n_objects
The number of objects.

◆ operator()()

virtual void libMesh::GhostingFunctor::operator() ( const MeshBase::const_element_iterator range_begin,
const MeshBase::const_element_iterator range_end,
processor_id_type  p,
map_type coupled_elements 
)
pure virtual

For the specified range of active elements, what other elements currently living (whether local or ghosted) on this processor need to be coupled/ghosted to accommodate them? Don't bother to return any results which already have processor_id p.

This API is new, and we should replace "ignoring those on processor p" with "ignoring those which match a predicate functor" eventually.

Implemented in libMesh::DefaultCoupling, libMesh::PointNeighborCoupling, libMesh::GhostPointNeighbors, AugmentSparsityOnNodes, libMesh::SiblingCoupling, and OverlappingCouplingFunctor.

◆ print_info()

void libMesh::ReferenceCounter::print_info ( std::ostream &  out_stream = libMesh::out)
staticinherited

Prints the reference information, by default to libMesh::out.

Definition at line 81 of file reference_counter.C.

References libMesh::ReferenceCounter::_enable_print_counter, and libMesh::ReferenceCounter::get_info().

Referenced by libMesh::LibMeshInit::~LibMeshInit().

82 {
84  out_stream << ReferenceCounter::get_info();
85 }
static std::string get_info()
Gets a string containing the reference information.
static bool _enable_print_counter
Flag to control whether reference count information is printed when print_info is called...

◆ redistribute()

virtual void libMesh::GhostingFunctor::redistribute ( )
inlinevirtual

GhostingFunctor subclasses with relatively long-lasting caches may want to redistribute those caches whenever the relevant Mesh is redistributed; we will give them an opportunity when that happens.

At the point in the code where this is called, element processor ids have been set to their new destinations, and those elements have been copied to their new destinations, but the elements have not yet been deleted by the processors which previously held them..

Reimplemented in AugmentSparsityOnNodes, libMesh::PointNeighborCoupling, libMesh::DefaultCoupling, and AugmentSparsityOnInterface.

Definition at line 284 of file ghosting_functor.h.

284 {};

◆ set_mesh()

virtual void libMesh::GhostingFunctor::set_mesh ( const MeshBase mesh)
inlinevirtual

It should be called after cloning a ghosting functor.

Ghosting functor is mesh dependent

Definition at line 225 of file ghosting_functor.h.

References _mesh, and mesh.

Referenced by libMesh::DofMap::add_algebraic_ghosting_functor(), and libMesh::DofMap::add_coupling_functor().

225 { _mesh = mesh; }
MeshBase & mesh

◆ set_periodic_boundaries()

virtual void libMesh::GhostingFunctor::set_periodic_boundaries ( const PeriodicBoundaries )
inlinevirtual

Reimplemented in libMesh::PointNeighborCoupling, and libMesh::DefaultCoupling.

Definition at line 229 of file ghosting_functor.h.

229 {}

Member Data Documentation

◆ _counts

ReferenceCounter::Counts libMesh::ReferenceCounter::_counts
staticprotectedinherited

Actually holds the data.

Definition at line 124 of file reference_counter.h.

Referenced by libMesh::ReferenceCounter::get_info().

◆ _enable_print_counter

bool libMesh::ReferenceCounter::_enable_print_counter = true
staticprotectedinherited

Flag to control whether reference count information is printed when print_info is called.

Definition at line 143 of file reference_counter.h.

Referenced by libMesh::ReferenceCounter::disable_print_counter_info(), libMesh::ReferenceCounter::enable_print_counter_info(), and libMesh::ReferenceCounter::print_info().

◆ _mesh

const MeshBase* libMesh::GhostingFunctor::_mesh
protected

◆ _mutex

Threads::spin_mutex libMesh::ReferenceCounter::_mutex
staticprotectedinherited

Mutual exclusion object to enable thread-safe reference counting.

Definition at line 137 of file reference_counter.h.

◆ _n_objects

Threads::atomic< unsigned int > libMesh::ReferenceCounter::_n_objects
staticprotectedinherited

The number of objects.

Print the reference count information when the number returns to 0.

Definition at line 132 of file reference_counter.h.

Referenced by libMesh::ReferenceCounter::n_objects(), libMesh::ReferenceCounter::ReferenceCounter(), and libMesh::ReferenceCounter::~ReferenceCounter().


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