libMesh::PointLocatorTree Class Reference

This is a point locator. More...

#include <point_locator_tree.h>

Inheritance diagram for libMesh::PointLocatorTree:

Public Member Functions
	PointLocatorTree (const MeshBase &mesh, const PointLocatorBase *master=nullptr)
	Constructor. More...
	PointLocatorTree (const MeshBase &mesh, const Trees::BuildType build_type, const PointLocatorBase *master=nullptr)
	Constructor. More...
	~PointLocatorTree ()
	Destructor. More...
virtual void	clear () override final
	Clears the locator. More...
void	init (Trees::BuildType build_type)
	Initializes the locator, so that the operator() methods can be used. More...
virtual void	init () override final
	Initializes the locator, so that the operator() methods can be used. More...
virtual const Elem *	operator() (const Point &p, const std::set< subdomain_id_type > *allowed_subdomains=nullptr) const override final
	Locates the element in which the point with global coordinates p is located, optionally restricted to a set of allowed subdomains. More...
virtual void	operator() (const Point &p, std::set< const Elem *> &candidate_elements, const std::set< subdomain_id_type > *allowed_subdomains=nullptr) const override final
	Locates a set of elements in proximity to the point with global coordinates p Pure virtual. More...
const Elem *	perform_linear_search (const Point &p, const std::set< subdomain_id_type > *allowed_subdomains, bool use_close_to_point, Real close_to_point_tolerance=TOLERANCE) const
	As a fallback option, it's helpful to be able to do a linear search over the entire mesh. More...
std::set< const Elem * >	perform_fuzzy_linear_search (const Point &p, const std::set< subdomain_id_type > *allowed_subdomains, Real close_to_point_tolerance=TOLERANCE) const
	A method to check if "fat" point p is in multiple elements. More...
virtual void	enable_out_of_mesh_mode () override final
	Enables out-of-mesh mode. More...
virtual void	disable_out_of_mesh_mode () override final
	Disables out-of-mesh mode (default). More...
void	set_target_bin_size (unsigned int target)
	Set the target bin size. More...
unsigned int	get_target_bin_size () const
	Get the target bin size. More...
virtual const Node *	locate_node (const Point &p, const std::set< subdomain_id_type > *allowed_subdomains=nullptr, Real tol=TOLERANCE) const
bool	initialized () const
Real	get_close_to_point_tol () const
	Get the close-to-point tolerance. More...
virtual void	set_close_to_point_tol (Real close_to_point_tol)
	Set a tolerance to use when determining if a point is contained within the mesh. More...
virtual void	unset_close_to_point_tol ()
	Specify that we do not want to use a user-specified tolerance to determine if a point is contained within the mesh. More...
virtual void	set_contains_point_tol (Real contains_point_tol)
	Set a tolerance to use when checking if a point is within an element in the mesh. More...
virtual void	unset_contains_point_tol ()
	Specify that we do not want to use a user-specified tolerance to determine if a point is inside an element in the mesh. More...
virtual Real	get_contains_point_tol () const
	Get the tolerance for determining element containment in the point locator. More...
bool	get_use_contains_point_tol () const
	The contains_point_tol may be nonzero (in fact it defaults to non-zero) but unless the user calls set_contains_point_tol(), it won't actually be used. More...
const MeshBase &	get_mesh () const
	Get a const reference to this PointLocator's mesh. More...
bool	get_verbose () const
	Get the verbosity setting (whether to print extra info to screen, default false) for this PointLocator. More...
void	set_verbose (bool verbosity)
	Set the verbosity setting for this PointLocator. More...
void	libmesh_assert_valid_point_locator ()
	Verifies that, for every node of every element, the point locator finds that element when searching at that node. More...

Static Public Member Functions
static std::unique_ptr< PointLocatorBase >	build (PointLocatorType t, const MeshBase &mesh, const PointLocatorBase *master=nullptr)
	Builds an PointLocator for the mesh mesh. More...
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
std::shared_ptr< TreeBase >	_tree
	Pointer to our tree. More...
const Elem *	_element
	Pointer to the last element that was found by the tree. More...
bool	_out_of_mesh_mode
	true if out-of-mesh mode is enabled. More...
unsigned int	_target_bin_size
	Target bin size, which gets passed to the constructor of _tree. More...
Trees::BuildType	_build_type
	How the underlying tree is built. More...
bool	_verbose
	Boolean flag to indicate whether to print out extra info. More...
const PointLocatorBase *	_master
	Const pointer to our master, initialized to nullptr if none given. More...
const MeshBase &	_mesh
	constant reference to the mesh in which the point is looked for. More...
bool	_initialized
	true when properly initialized, false otherwise. More...
bool	_use_close_to_point_tol
	true if we will use a user-specified tolerance for locating the element in an exhaustive search. More...
Real	_close_to_point_tol
	The tolerance to use. More...
bool	_use_contains_point_tol
	true if we will use a user-specified tolerance for locating the element. More...
Real	_contains_point_tol
	The tolerance to use when locating an element in the tree. More...

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 is a point locator.

It locates points in space using a tree: given a mesh they return the element and local coordinates for a given point in global coordinates. Use PointLocatorBase::build() to create objects of this type at run time.

Author

Daniel Dreyer

Date

2003

Definition at line 49 of file point_locator_tree.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.

Constructor & Destructor Documentation

PointLocatorTree() [1/2]

libMesh::PointLocatorTree::PointLocatorTree	(	const MeshBase &	mesh,
		const PointLocatorBase *	master = nullptr
	)

Constructor.

Needs the mesh in which the points should be located. Optionally takes a master interpolator. This master helps in saving memory by reducing the number of trees in use. Only the master locator holds a tree, the others simply use the master's tree.

Definition at line 37 of file point_locator_tree.C.

References _build_type, and init().

                                                                     :
  PointLocatorBase (mesh,master),
  _tree            (nullptr),
  _element         (nullptr),
  _out_of_mesh_mode(false),
  _target_bin_size (200),
  _build_type(Trees::NODES)
{
  this->init(_build_type);
}

PointLocatorTree() [2/2]

libMesh::PointLocatorTree::PointLocatorTree	(	const MeshBase &	mesh,
		const Trees::BuildType	build_type,
		const PointLocatorBase *	master = nullptr
	)

Constructor.

Needs the mesh in which the points should be located. Allows the user to specify the method to use when building the tree. Optionally takes a master interpolator. This master helps in saving memory by reducing the number of trees in use. Only the master locator holds a tree, the others simply use the master's tree. Allows the user to specify the build type.

Definition at line 51 of file point_locator_tree.C.

References _build_type, and init().

                                                                     :
  PointLocatorBase (mesh,master),
  _tree            (nullptr),
  _element         (nullptr),
  _out_of_mesh_mode(false),
  _target_bin_size (200),
  _build_type(build_type)
{
  this->init(_build_type);
}

~PointLocatorTree()

libMesh::PointLocatorTree::~PointLocatorTree ( )

default

Destructor.

Member Function Documentation

build()

std::unique_ptr< PointLocatorBase > libMesh::PointLocatorBase::build ( PointLocatorType  t, const MeshBase &  mesh, const PointLocatorBase *  master = nullptr  )

staticinherited

Builds an PointLocator for the mesh mesh.

Optionally takes a master PointLocator to save memory. An std::unique_ptr<PointLocatorBase> is returned to prevent memory leak. This way the user need not remember to delete the object.

Definition at line 68 of file point_locator_base.C.

References libMesh::Trees::ELEMENTS, libMesh::Trees::LOCAL_ELEMENTS, mesh, libMesh::NANOFLANN, libMesh::TREE, libMesh::TREE_ELEMENTS, and libMesh::TREE_LOCAL_ELEMENTS.

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

{
  switch (t)
    {
    case TREE:
      return std::make_unique<PointLocatorTree>(mesh, /*Trees::NODES,*/ master);

    case TREE_ELEMENTS:
      return std::make_unique<PointLocatorTree>(mesh, Trees::ELEMENTS, master);

    case TREE_LOCAL_ELEMENTS:
      return std::make_unique<PointLocatorTree>(mesh, Trees::LOCAL_ELEMENTS, master);

#ifdef LIBMESH_HAVE_NANOFLANN
    case NANOFLANN:
      return std::make_unique<PointLocatorNanoflann>(mesh, master);
#endif

    default:
      libmesh_error_msg("ERROR: Bad PointLocatorType = " << t);
    }
}

clear()

void libMesh::PointLocatorTree::clear ( )

finaloverridevirtual

Clears the locator.

This function frees dynamic memory with "delete".

Implements libMesh::PointLocatorBase.

Definition at line 70 of file point_locator_tree.C.

References libMesh::PointLocatorBase::_initialized, and _tree.

{
  this->_initialized = false;

  // reset() actually frees the memory if we are master, otherwise it
  // just reduces the ref. count.
  _tree.reset();
}

disable_out_of_mesh_mode()

void libMesh::PointLocatorTree::disable_out_of_mesh_mode ( )

finaloverridevirtual

Disables out-of-mesh mode (default).

If asked to find a point that is contained in no mesh at all, the point locator will now crash.

Implements libMesh::PointLocatorBase.

Definition at line 347 of file point_locator_tree.C.

References _out_of_mesh_mode.

{
  _out_of_mesh_mode = false;
}

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.

{
  _enable_print_counter = false;
  return;
}

enable_out_of_mesh_mode()

void libMesh::PointLocatorTree::enable_out_of_mesh_mode ( )

finaloverridevirtual

Enables out-of-mesh mode.

In this mode, if asked to find a point that is contained in no mesh at all, the point locator will return nullptr instead of crashing. Per default, this mode is off.

Implements libMesh::PointLocatorBase.

Definition at line 339 of file point_locator_tree.C.

References _out_of_mesh_mode.

Referenced by InfFERadialTest::testRefinement().

{
  // Out-of-mesh mode should now work properly even on meshes with
  // non-affine elements.
  _out_of_mesh_mode = true;
}

enable_print_counter_info()

void libMesh::ReferenceCounter::enable_print_counter_info ( )

staticinherited

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

Enabled by default.

Definition at line 94 of file reference_counter.C.

References libMesh::ReferenceCounter::_enable_print_counter.

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

{
  _enable_print_counter = true;
  return;
}

get_close_to_point_tol()

Real libMesh::PointLocatorBase::get_close_to_point_tol ( ) const

inherited

Get the close-to-point tolerance.

Definition at line 93 of file point_locator_base.C.

References libMesh::PointLocatorBase::_close_to_point_tol.

Referenced by libMesh::MeshFunction::MeshFunction().

{
  return _close_to_point_tol;
}

get_contains_point_tol()

Real libMesh::PointLocatorBase::get_contains_point_tol ( ) const

virtualinherited

Get the tolerance for determining element containment in the point locator.

Definition at line 123 of file point_locator_base.C.

References libMesh::PointLocatorBase::_contains_point_tol.

{
  return _contains_point_tol;
}

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().

{
#if defined(LIBMESH_ENABLE_REFERENCE_COUNTING) && defined(DEBUG)

  std::ostringstream oss;

  oss << '\n'
      << " ---------------------------------------------------------------------------- \n"
      << "| Reference count information                                                |\n"
      << " ---------------------------------------------------------------------------- \n";

  for (const auto & [name, cd] : _counts)
    oss << "| " << name << " reference count information:\n"
        << "|  Creations:    " << cd.first    << '\n'
        << "|  Destructions: " << cd.second << '\n';

  oss << " ---------------------------------------------------------------------------- \n";

  return oss.str();

#else

  return "";

#endif
}

get_mesh()

const MeshBase & libMesh::PointLocatorBase::get_mesh ( ) const

inherited

Get a const reference to this PointLocator's mesh.

Definition at line 128 of file point_locator_base.C.

References libMesh::PointLocatorBase::_mesh.

Referenced by libMesh::PeriodicBoundaries::neighbor().

{
  return _mesh;
}

get_target_bin_size()

unsigned int libMesh::PointLocatorTree::get_target_bin_size

(

)

const

Get the target bin size.

Definition at line 359 of file point_locator_tree.C.

References _target_bin_size.

Referenced by init().

{
  return _target_bin_size;
}

get_use_contains_point_tol()

bool libMesh::PointLocatorBase::get_use_contains_point_tol ( ) const

inlineinherited

The contains_point_tol may be nonzero (in fact it defaults to non-zero) but unless the user calls set_contains_point_tol(), it won't actually be used.

This const accessor can be used to determine the current status of this flag.

Definition at line 192 of file point_locator_base.h.

References libMesh::PointLocatorBase::_use_contains_point_tol.

{ return _use_contains_point_tol; }

get_verbose()

bool libMesh::PointLocatorBase::get_verbose ( ) const

inlineinherited

Get the verbosity setting (whether to print extra info to screen, default false) for this PointLocator.

Definition at line 203 of file point_locator_base.h.

References libMesh::PointLocatorBase::_verbose.

{ return _verbose; }

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().

{
  libmesh_try
  {
    Threads::spin_mutex::scoped_lock lock(Threads::spin_mtx);
    std::pair<unsigned int, unsigned int> & p = _counts[name];
    p.first++;
  }
  libmesh_catch (...)
  {
    auto stream = libMesh::err.get();
    stream->exceptions(stream->goodbit); // stream must not throw
    libMesh::err << "Encountered unrecoverable error while calling "
                 << "ReferenceCounter::increment_constructor_count() "
                 << "for a(n) " << name << " object." << std::endl;
    std::terminate();
  }
}

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().

{
  libmesh_try
  {
    Threads::spin_mutex::scoped_lock lock(Threads::spin_mtx);
    std::pair<unsigned int, unsigned int> & p = _counts[name];
    p.second++;
  }
  libmesh_catch (...)
  {
    auto stream = libMesh::err.get();
    stream->exceptions(stream->goodbit); // stream must not throw
    libMesh::err << "Encountered unrecoverable error while calling "
                 << "ReferenceCounter::increment_destructor_count() "
                 << "for a(n) " << name << " object." << std::endl;
    std::terminate();
  }
}

init() [1/2]

void libMesh::PointLocatorTree::init

(

Trees::BuildType

build_type

)

Initializes the locator, so that the operator() methods can be used.

This function allocates dynamic memory with "new".

Definition at line 88 of file point_locator_tree.C.

References _build_type, _element, libMesh::PointLocatorBase::_initialized, libMesh::PointLocatorBase::_master, libMesh::PointLocatorBase::_mesh, _tree, libMesh::MeshTools::create_bounding_box(), libMesh::err, get_target_bin_size(), libMesh::PointLocatorBase::initialized(), libMesh::libmesh_assert(), and libMesh::Real.

{
  libmesh_assert (!this->_tree);

  if (this->_initialized)
    {
      // Warn that we are already initialized
      libMesh::err << "Warning: PointLocatorTree already initialized!  Will ignore this call..." << std::endl;

      // Further warn if we try to init() again with a different build_type
      if (_build_type != build_type)
        {
          libMesh::err << "Warning: PointLocatorTree is using build_type = " << _build_type << ".\n"
                       << "Your requested build_type, " << build_type << " will not be used!" << std::endl;
        }
    }

  else
    {
      // Let the requested build_type override the _build_type we were
      // constructed with.  This is no big deal since we have not been
      // initialized before.
      _build_type = build_type;

      if (this->_master == nullptr)
        {
          LOG_SCOPE("init(no master)", "PointLocatorTree");

          if (LIBMESH_DIM == 1)
            _tree = std::make_shared<Trees::BinaryTree>(this->_mesh, get_target_bin_size(), _build_type);
          else if (LIBMESH_DIM == 2)
            _tree = std::make_shared<Trees::QuadTree>(this->_mesh, get_target_bin_size(), _build_type);
          else if (this->_mesh.mesh_dimension() == 3) // && LIBMESH_DIM==3
            _tree = std::make_shared<Trees::OctTree>(this->_mesh, get_target_bin_size(), _build_type);
          else
            {
              // LIBMESH_DIM==3 but we have a mesh with only 1D/2D
              // elements, which needs special consideration.  If the
              // mesh is planar XY, we want to build a QuadTree to
              // search efficiently.  If the mesh is truly a manifold,
              // then we need an octree
              bool is_planar_xy = false;

              // Build the bounding box for the mesh.  If the delta-z bound is
              // negligibly small then we can use a quadtree.
              BoundingBox bbox = MeshTools::create_bounding_box(this->_mesh);

              const Real
                Dx = bbox.second(0) - bbox.first(0),
                Dz = bbox.second(2) - bbox.first(2);

              // In order to satisfy is_planar_xy the mesh should be planar and should
              // also be in the z=0 plane, since otherwise it is incorrect to use a
              // QuadTree since QuadTrees assume z=0.
              if ( (std::abs(Dz/(Dx + 1.e-20)) < 1e-10) && (std::abs(bbox.second(2)) < 1.e-10) )
                is_planar_xy = true;

              if (is_planar_xy)
                _tree = std::make_shared<Trees::QuadTree>(this->_mesh, get_target_bin_size(), _build_type);
              else
                _tree = std::make_shared<Trees::OctTree>(this->_mesh, get_target_bin_size(), _build_type);
            }
        }

      else
        {
          // We are _not_ the master.  Let our Tree point to
          // the master's tree.  But for this we first transform
          // the master in a state for which we are friends.
          // And make sure the master has a tree!
          const PointLocatorTree * my_master =
            cast_ptr<const PointLocatorTree *>(this->_master);

          if (my_master->initialized())
            this->_tree = my_master->_tree;
          else
            libmesh_error_msg("ERROR: Initialize master first, then servants!");
        }

      // Not all PointLocators may own a tree, but all of them
      // use their own element pointer.  Let the element pointer
      // be unique for every interpolator.
      // Suppose the interpolators are used concurrently
      // at different locations in the mesh, then it makes quite
      // sense to have unique start elements.
      this->_element = nullptr;
    }

  // ready for take-off
  this->_initialized = true;

  // This may be too expensive to use even in debug mode, but it's
  // helpful to uncomment for debugging.
  // this->libmesh_assert_valid_point_locator();
}

init() [2/2]

void libMesh::PointLocatorTree::init ( )

finaloverridevirtual

Initializes the locator, so that the operator() methods can be used.

This function allocates dynamic memory with "new".

Implements libMesh::PointLocatorBase.

Definition at line 81 of file point_locator_tree.C.

References _build_type.

Referenced by PointLocatorTree().

{
  this->init(_build_type);
}

initialized()

bool libMesh::PointLocatorBase::initialized ( ) const

inherited

Returns

true when this object is properly initialized and ready for use, false otherwise.

Definition at line 61 of file point_locator_base.C.

References libMesh::PointLocatorBase::_initialized.

Referenced by init(), and libMesh::MeshFunction::MeshFunction().

{
  return this->_initialized;
}

libmesh_assert_valid_point_locator()

void libMesh::PointLocatorBase::libmesh_assert_valid_point_locator ( )

inherited

Verifies that, for every node of every element, the point locator finds that element when searching at that node.

This is an O(N log N) operation, and so only available in builds with NDEBUG undefined, for asserting internal consistency (the PointLocator works) and external consistency (user code didn't change the mesh without updating the PointLocator afterward) that we hope should never be broken in opt.

Definition at line 159 of file point_locator_base.C.

References libMesh::PointLocatorBase::_mesh, libMesh::LAGRANGE_MAP, libMesh::libmesh_assert(), libMesh::make_range(), and libMesh::PointLocatorBase::operator()().

{
  // We might only have been built with TREE_LOCAL_ELEMENTS as an
  // option; let's just check local elements to be safe.
  for (const Elem * elem : this->_mesh.active_local_element_ptr_range())
    {
      // For non-Lagrange mappings, we might have nodes that are
      // really control points, not contained in the element they
      // define; we can only safely check containment of vertices.
      auto range = make_range(0u, (elem->mapping_type() == LAGRANGE_MAP) ?
                                 elem->n_nodes() : elem->n_vertices());

        for (auto n : range)
          {
            const Node & node = elem->node_ref(n);
            std::set<const Elem *> candidate_elements;
            this->operator()(node, candidate_elements);
            libmesh_assert(candidate_elements.count(elem));
          }
    }
}

locate_node()

const Node * libMesh::PointLocatorBase::locate_node ( const Point &  p, const std::set< subdomain_id_type > *  allowed_subdomains = nullptr, Real  tol = TOLERANCE  ) const

virtualinherited

Returns

A pointer to a Node with global coordinates p or nullptr if no such Node can be found.

Virtual subclasses can override for efficiency, but the base class has a default implementation that works based on element lookup.

Optionally allows the user to restrict the subdomains searched; with such a restriction, only a Node belonging to an element on one or more of those subdomains will be returned.

Will only return a Node whose distance from p is less than tol multiplied by the size of a semilocal element which contains p.

Definition at line 136 of file point_locator_base.C.

References libMesh::TensorTools::norm_sq(), libMesh::PointLocatorBase::operator()(), and libMesh::Real.

{
  std::set<const Elem *> candidate_elements;
  this->operator()(p, candidate_elements, allowed_subdomains);

  for (const auto & elem : candidate_elements)
    {
      const int elem_n_nodes = elem->n_nodes();
      const Real hmax = elem->hmax();
      const Real dist_tol_sq = (tol * hmax) * (tol * hmax);

      for (int n=0; n != elem_n_nodes; ++n)
        if ((elem->point(n) - p).norm_sq() < dist_tol_sq)
          return elem->node_ptr(n);
    }

  return nullptr;
}

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().

  { return _n_objects; }

operator()() [1/2]

const Elem * libMesh::PointLocatorTree::operator() ( const Point &  p, const std::set< subdomain_id_type > *  allowed_subdomains = nullptr  ) const

finaloverridevirtual

Locates the element in which the point with global coordinates p is located, optionally restricted to a set of allowed subdomains.

The mutable _element member is used to cache the result and allow it to be used during the next call to operator().

Implements libMesh::PointLocatorBase.

Definition at line 184 of file point_locator_tree.C.

References libMesh::PointLocatorBase::_close_to_point_tol, libMesh::PointLocatorBase::_contains_point_tol, _element, libMesh::PointLocatorBase::_initialized, _out_of_mesh_mode, _tree, libMesh::PointLocatorBase::_use_close_to_point_tol, libMesh::PointLocatorBase::_use_contains_point_tol, libMesh::PointLocatorBase::_verbose, libMesh::Elem::active(), libMesh::Elem::close_to_point(), libMesh::Elem::contains_point(), libMesh::libmesh_assert(), libMesh::out, and perform_linear_search().

{
  libmesh_assert (this->_initialized);

  LOG_SCOPE("operator()", "PointLocatorTree");

  // If we're provided with an allowed_subdomains list and have a cached element, make sure it complies
  if (allowed_subdomains && this->_element && !allowed_subdomains->count(this->_element->subdomain_id()))
    this->_element = nullptr;

  if (this->_element != nullptr)
    {
      // If the user specified a custom tolerance, we actually call
      // Elem::close_to_point() instead, since Elem::contains_point()
      // warns about using non-default BoundingBox tolerances.
      if (_use_contains_point_tol && !(this->_element->close_to_point(p, _contains_point_tol)))
        this->_element = nullptr;

      // Otherwise, just call contains_point(p) with default tolerances.
      else if (!(this->_element->contains_point(p)))
        this->_element = nullptr;
    }

  // First check the element from last time before asking the tree
  if (this->_element==nullptr)
    {
      // ask the tree
      if (_use_contains_point_tol)
        this->_element = this->_tree->find_element(p, allowed_subdomains, _contains_point_tol);
      else
        this->_element = this->_tree->find_element(p, allowed_subdomains);

      if (this->_element == nullptr)
        {
          // If we haven't found the element, we may want to do a linear
          // search using a tolerance.
          if (_use_close_to_point_tol)
            {
              if (_verbose)
                {
                  libMesh::out << "Performing linear search using close-to-point tolerance "
                               << _close_to_point_tol
                               << std::endl;
                }

              this->_element =
                this->perform_linear_search(p,
                                            allowed_subdomains,
                                            /*use_close_to_point*/ true,
                                            _close_to_point_tol);

              return this->_element;
            }

          // No element seems to contain this point.  In theory, our
          // tree now correctly handles curved elements.  In
          // out-of-mesh mode this is sometimes expected, and we can
          // just return nullptr without searching further.  Out of
          // out-of-mesh mode, something must have gone wrong.
          libmesh_assert_equal_to (_out_of_mesh_mode, true);

          return this->_element;
        }
    }

  // If we found an element, it should be active
  libmesh_assert (!this->_element || this->_element->active());

  // If we found an element and have a restriction list, they better match
  libmesh_assert (!this->_element || !allowed_subdomains || allowed_subdomains->count(this->_element->subdomain_id()));

  // return the element
  return this->_element;
}

operator()() [2/2]

void libMesh::PointLocatorTree::operator() ( const Point &  p, std::set< const Elem *> &  candidate_elements, const std::set< subdomain_id_type > *  allowed_subdomains = nullptr  ) const

finaloverridevirtual

Locates a set of elements in proximity to the point with global coordinates p Pure virtual.

Optionally allows the user to restrict the subdomains searched.

Implements libMesh::PointLocatorBase.

Definition at line 261 of file point_locator_tree.C.

References libMesh::PointLocatorBase::_close_to_point_tol, libMesh::PointLocatorBase::_initialized, _tree, and libMesh::libmesh_assert().

{
  libmesh_assert (this->_initialized);

  LOG_SCOPE("operator() - Version 2", "PointLocatorTree");

  // ask the tree
  this->_tree->find_elements (p, candidate_elements, allowed_subdomains, _close_to_point_tol);
}

perform_fuzzy_linear_search()

std::set< const Elem * > libMesh::PointLocatorTree::perform_fuzzy_linear_search	(	const Point &	p,
		const std::set< subdomain_id_type > *	allowed_subdomains,
		Real	close_to_point_tolerance = TOLERANCE
	)		const

A method to check if "fat" point p is in multiple elements.

This would happen if p is close to a face or node. This is important for evaluating MeshFunction on faces when discontinuous shape functions are used.

Definition at line 313 of file point_locator_tree.C.

References _build_type, libMesh::PointLocatorBase::_mesh, and libMesh::Trees::LOCAL_ELEMENTS.

{
  LOG_SCOPE("perform_fuzzy_linear_search", "PointLocatorTree");

  std::set<const Elem *> candidate_elements;

  // The type of iterator depends on the Trees::BuildType
  // used for this PointLocator.  If it's
  // TREE_LOCAL_ELEMENTS, we only want to double check
  // local elements during this linear search.
  SimpleRange<MeshBase::const_element_iterator> r =
    this->_build_type == Trees::LOCAL_ELEMENTS ?
    this->_mesh.active_local_element_ptr_range() :
    this->_mesh.active_element_ptr_range();

  for (const auto & elem : r)
    if ((!allowed_subdomains || allowed_subdomains->count(elem->subdomain_id())) && elem->close_to_point(p, close_to_point_tolerance))
      candidate_elements.insert(elem);

  return candidate_elements;
}

perform_linear_search()

const Elem * libMesh::PointLocatorTree::perform_linear_search	(	const Point &	p,
		const std::set< subdomain_id_type > *	allowed_subdomains,
		bool	use_close_to_point,
		Real	close_to_point_tolerance = TOLERANCE
	)		const

As a fallback option, it's helpful to be able to do a linear search over the entire mesh.

This can be used if operator() fails to find an element that contains p, for example. Optionally specify a "close to point" tolerance to use in the linear search. Return nullptr if no element is found.

Definition at line 275 of file point_locator_tree.C.

References _build_type, libMesh::PointLocatorBase::_contains_point_tol, libMesh::PointLocatorBase::_mesh, and libMesh::Trees::LOCAL_ELEMENTS.

Referenced by operator()().

{
  LOG_SCOPE("perform_linear_search", "PointLocatorTree");

  // The type of iterator depends on the Trees::BuildType
  // used for this PointLocator.  If it's
  // TREE_LOCAL_ELEMENTS, we only want to double check
  // local elements during this linear search.
  SimpleRange<MeshBase::const_element_iterator> r =
    this->_build_type == Trees::LOCAL_ELEMENTS ?
    this->_mesh.active_local_element_ptr_range() :
    this->_mesh.active_element_ptr_range();

  for (const auto & elem : r)
    {
      if (!allowed_subdomains ||
          allowed_subdomains->count(elem->subdomain_id()))
        {
          if (!use_close_to_point)
            {
              if (elem->contains_point(p, _contains_point_tol))
                return elem;
            }
          else
            {
              if (elem->close_to_point(p, close_to_point_tolerance))
                return elem;
            }
        }
    }

  return nullptr;
}

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().

{
  if (_enable_print_counter)
    out_stream << ReferenceCounter::get_info();
}

set_close_to_point_tol()

void libMesh::PointLocatorBase::set_close_to_point_tol ( Real  close_to_point_tol )

virtualinherited

Set a tolerance to use when determining if a point is contained within the mesh.

Definition at line 99 of file point_locator_base.C.

References libMesh::PointLocatorBase::_close_to_point_tol, and libMesh::PointLocatorBase::_use_close_to_point_tol.

{
  _use_close_to_point_tol = true;
  _close_to_point_tol = close_to_point_tol;
}

set_contains_point_tol()

void libMesh::PointLocatorBase::set_contains_point_tol ( Real  contains_point_tol )

virtualinherited

Set a tolerance to use when checking if a point is within an element in the mesh.

Definition at line 111 of file point_locator_base.C.

References libMesh::PointLocatorBase::_contains_point_tol, and libMesh::PointLocatorBase::_use_contains_point_tol.

{
  _use_contains_point_tol = true;
  _contains_point_tol = contains_point_tol;
}

set_target_bin_size()

void libMesh::PointLocatorTree::set_target_bin_size

(

unsigned int

target

)

Set the target bin size.

Definition at line 353 of file point_locator_tree.C.

References _target_bin_size.

{
  _target_bin_size = target_bin_size;
}

set_verbose()

void libMesh::PointLocatorBase::set_verbose ( bool  verbosity )

inlineinherited

Set the verbosity setting for this PointLocator.

Definition at line 208 of file point_locator_base.h.

References libMesh::PointLocatorBase::_verbose.

{ _verbose = verbosity; }

unset_close_to_point_tol()

void libMesh::PointLocatorBase::unset_close_to_point_tol ( )

virtualinherited

Specify that we do not want to use a user-specified tolerance to determine if a point is contained within the mesh.

Definition at line 105 of file point_locator_base.C.

References libMesh::PointLocatorBase::_close_to_point_tol, libMesh::PointLocatorBase::_use_close_to_point_tol, and libMesh::TOLERANCE.

{
  _use_close_to_point_tol = false;
  _close_to_point_tol = TOLERANCE;
}

unset_contains_point_tol()

void libMesh::PointLocatorBase::unset_contains_point_tol ( )

virtualinherited

Specify that we do not want to use a user-specified tolerance to determine if a point is inside an element in the mesh.

Definition at line 117 of file point_locator_base.C.

References libMesh::PointLocatorBase::_contains_point_tol, libMesh::PointLocatorBase::_use_contains_point_tol, and libMesh::TOLERANCE.

{
  _use_contains_point_tol = false;
  _contains_point_tol = TOLERANCE;
}

Member Data Documentation

_build_type

Trees::BuildType libMesh::PointLocatorTree::_build_type

protected

How the underlying tree is built.

Definition at line 195 of file point_locator_tree.h.

Referenced by init(), perform_fuzzy_linear_search(), perform_linear_search(), and PointLocatorTree().

_close_to_point_tol

Real libMesh::PointLocatorBase::_close_to_point_tol

protectedinherited

The tolerance to use.

Definition at line 260 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_close_to_point_tol(), operator()(), libMesh::PointLocatorBase::PointLocatorBase(), libMesh::PointLocatorBase::set_close_to_point_tol(), and libMesh::PointLocatorBase::unset_close_to_point_tol().

_contains_point_tol

Real libMesh::PointLocatorBase::_contains_point_tol

protectedinherited

The tolerance to use when locating an element in the tree.

Definition at line 271 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_contains_point_tol(), libMesh::PointLocatorNanoflann::operator()(), operator()(), perform_linear_search(), libMesh::PointLocatorBase::set_contains_point_tol(), and libMesh::PointLocatorBase::unset_contains_point_tol().

_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().

_element

const Elem* libMesh::PointLocatorTree::_element

mutableprotected

Pointer to the last element that was found by the tree.

Chances are that this may be close to the next call to operator()...

Definition at line 179 of file point_locator_tree.h.

Referenced by init(), and operator()().

_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().

_initialized

bool libMesh::PointLocatorBase::_initialized

protectedinherited

true when properly initialized, false otherwise.

Definition at line 249 of file point_locator_base.h.

Referenced by clear(), libMesh::PointLocatorNanoflann::clear(), init(), libMesh::PointLocatorNanoflann::init(), libMesh::PointLocatorBase::initialized(), libMesh::PointLocatorNanoflann::operator()(), and operator()().

_master

const PointLocatorBase* libMesh::PointLocatorBase::_master

protectedinherited

Const pointer to our master, initialized to nullptr if none given.

When using multiple PointLocators, one can be assigned master and be in charge of something that all can have access to.

Definition at line 239 of file point_locator_base.h.

Referenced by init(), libMesh::PointLocatorNanoflann::init(), and libMesh::PointLocatorBase::PointLocatorBase().

_mesh

const MeshBase& libMesh::PointLocatorBase::_mesh

protectedinherited

constant reference to the mesh in which the point is looked for.

Definition at line 244 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_mesh(), init(), libMesh::PointLocatorNanoflann::init(), libMesh::PointLocatorBase::libmesh_assert_valid_point_locator(), perform_fuzzy_linear_search(), and perform_linear_search().

_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().

_out_of_mesh_mode

bool libMesh::PointLocatorTree::_out_of_mesh_mode

protected

true if out-of-mesh mode is enabled.

See enable_out_of_mesh_mode() for details.

Definition at line 185 of file point_locator_tree.h.

Referenced by disable_out_of_mesh_mode(), enable_out_of_mesh_mode(), and operator()().

_target_bin_size

unsigned int libMesh::PointLocatorTree::_target_bin_size

protected

Target bin size, which gets passed to the constructor of _tree.

Definition at line 190 of file point_locator_tree.h.

Referenced by get_target_bin_size(), and set_target_bin_size().

_tree

std::shared_ptr<TreeBase> libMesh::PointLocatorTree::_tree

protected

Pointer to our tree.

The tree is built at run-time through init(). For non-master PointLocators, this simply points to the tree of the master.

Definition at line 172 of file point_locator_tree.h.

Referenced by clear(), init(), and operator()().

_use_close_to_point_tol

bool libMesh::PointLocatorBase::_use_close_to_point_tol

protectedinherited

true if we will use a user-specified tolerance for locating the element in an exhaustive search.

Definition at line 255 of file point_locator_base.h.

Referenced by operator()(), libMesh::PointLocatorBase::PointLocatorBase(), libMesh::PointLocatorBase::set_close_to_point_tol(), and libMesh::PointLocatorBase::unset_close_to_point_tol().

_use_contains_point_tol

bool libMesh::PointLocatorBase::_use_contains_point_tol

protectedinherited

true if we will use a user-specified tolerance for locating the element.

Definition at line 266 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_use_contains_point_tol(), libMesh::PointLocatorNanoflann::operator()(), operator()(), libMesh::PointLocatorBase::set_contains_point_tol(), and libMesh::PointLocatorBase::unset_contains_point_tol().

_verbose

bool libMesh::PointLocatorBase::_verbose

protectedinherited

Boolean flag to indicate whether to print out extra info.

Definition at line 231 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_verbose(), operator()(), and libMesh::PointLocatorBase::set_verbose().

---

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

• include/utils/point_locator_tree.h
• src/utils/point_locator_tree.C