libMesh::PointLocatorNanoflann Class Reference

This is a PointLocator that uses Nanoflann for its implementation. More...

#include <point_locator_nanoflann.h>

Inheritance diagram for libMesh::PointLocatorNanoflann:

Public Types
typedef Real	coord_t
	Floating point type used for storing coordinates. More...

Public Member Functions
	PointLocatorNanoflann (const MeshBase &mesh, const PointLocatorBase *master=nullptr)
	Constructor. More...
virtual	~PointLocatorNanoflann ()
	Destructor. More...
virtual void	clear () override final
	Restore to PointLocator to a just-constructed state. 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. 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...
std::size_t	get_num_results () const
	Set/get the number of results returned by each Nanoflann findNeighbors() search. More...
void	set_num_results (std::size_t val)
std::size_t	kdtree_get_point_count () const
	Must return the number of data points. More...
coord_t	kdtree_distance (const coord_t *p1, const std::size_t idx_p2, std::size_t size) const
	Returns the squared distance between the vector (p1[0], p1[1], p1[2]) and the vertex average of Elem "idx_p2" stored in _mesh. More...
coord_t	kdtree_get_pt (const std::size_t idx, int dim) const
	Returns the dim'th component of the idx'th vertex average. More...
template<class BBOX >
bool	kdtree_get_bbox (BBOX &) const
	Optional bounding-box computation: return false to default to a standard bbox computation loop. 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...

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

Public Attributes
bool	_verbose
	Boolean flag to indicate whether to print out extra info. More...

Protected Types
typedef nanoflann::L2_Simple_Adaptor< Real, PointLocatorNanoflann >	adapter_t
typedef nanoflann::KDTreeSingleIndexAdaptor< adapter_t, PointLocatorNanoflann, LIBMESH_DIM >	kd_tree_t
typedef std::map< std::string, std::pair< unsigned int, unsigned int > >	Counts
	Data structure to log the information. More...

Protected Member Functions
nanoflann::KNNResultSet< Real >	kd_tree_find_neighbors (const Point &p, std::size_t num_results) const
	Helper function that wraps the call to the KDTree's findNeighbors() routine. More...
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
bool	_out_of_mesh_mode
	true if out-of-mesh mode is enabled. More...
std::size_t	_num_results
	The number of results returned by Nanoflann when operator() is called. More...
std::shared_ptr< std::vector< const Elem * > >	_elems
	Lists of Points and ids which make up the "point cloud" that is to be searched via Nanoflann. More...
std::shared_ptr< std::vector< Point > >	_point_cloud
std::shared_ptr< kd_tree_t >	_kd_tree
std::vector< std::size_t >	_ret_index
	The operator() functions on PointLocator-derived classes are const, so to avoid re-allocating these result data structures every time operator() is called, they have to be mutable. More...
std::vector< Real >	_out_dist_sqr
std::vector< std::size_t >	_b
	Vector of indices used by indirect sort. 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 PointLocator that uses Nanoflann for its implementation.

Nanoflann is distributed with libmesh (see: contrib/nanoflann) and libmesh must be built with nanoflann enabled for this class to work.

This PointLocator is still considered "experimental", so it is not enabled in libMesh by default. In particular, there may be false negatives (i.e. failures to find a containing Elem for a given Point even though there actually is one in the Mesh) on adaptively refined meshes, meshes with intersecting mixed-dimension manifolds, and meshes with large aspect ratio changes across neighboring elements. That said, the Nanoflann PointLocator did successfully pass all the MOOSE CI testing that we threw at it (and even uncovered some bugs in said tests) so it will likely work well for most applications outside of the categories mentioned above.

You must configure libmesh with –enable-nanoflann-pointlocator in order to use this class.

Author

John W. Peterson

Date

2021

Definition at line 71 of file point_locator_nanoflann.h.

Member Typedef Documentation

adapter_t

typedef nanoflann::L2_Simple_Adaptor<Real, PointLocatorNanoflann> libMesh::PointLocatorNanoflann::adapter_t

protected

Definition at line 228 of file point_locator_nanoflann.h.

coord_t

typedef Real libMesh::PointLocatorNanoflann::coord_t

Floating point type used for storing coordinates.

Definition at line 167 of file point_locator_nanoflann.h.

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.

kd_tree_t

typedef nanoflann::KDTreeSingleIndexAdaptor<adapter_t, PointLocatorNanoflann, LIBMESH_DIM> libMesh::PointLocatorNanoflann::kd_tree_t

protected

Definition at line 229 of file point_locator_nanoflann.h.

Constructor & Destructor Documentation

PointLocatorNanoflann()

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

Constructor.

Needs the mesh in which the points should be located. Optionally takes a pointer to a "master" PointLocator object. If non-nullptr, this object simply forwards its calls onto the master, so we can have multiple pointers that use the same Nanoflann KD-Tree data structure.

Definition at line 40 of file point_locator_nanoflann.C.

References init().

                                                                               :
  PointLocatorBase (mesh, master),
  _out_of_mesh_mode(false),
  _num_results(8)
{
  this->init();
}

~PointLocatorNanoflann()

libMesh::PointLocatorNanoflann::~PointLocatorNanoflann ( )

virtualdefault

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 67 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::PointLocatorNanoflann::clear ( )

finaloverridevirtual

Restore to PointLocator to a just-constructed state.

Implements libMesh::PointLocatorBase.

Definition at line 56 of file point_locator_nanoflann.C.

References _elems, libMesh::PointLocatorBase::_initialized, _kd_tree, _out_of_mesh_mode, and _point_cloud.

{
  this->_initialized = false;
  this->_out_of_mesh_mode = false;

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

disable_out_of_mesh_mode()

void libMesh::PointLocatorNanoflann::disable_out_of_mesh_mode ( )

finaloverridevirtual

Disables out-of-mesh mode (default).

See above.

Implements libMesh::PointLocatorBase.

Definition at line 377 of file point_locator_nanoflann.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::PointLocatorNanoflann::enable_out_of_mesh_mode ( )

finaloverridevirtual

Enables out-of-mesh mode.

In this mode, if a searched-for Point is not contained in any element of the Mesh, return nullptr instead of throwing an error. By default, this mode is off.

Implements libMesh::PointLocatorBase.

Definition at line 368 of file point_locator_nanoflann.C.

References _out_of_mesh_mode.

{
  // 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()

Definition at line 94 of file reference_counter.C.

References libMesh::ReferenceCounter::_enable_print_counter.

{
  _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 92 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 122 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 127 of file point_locator_base.C.

References libMesh::PointLocatorBase::_mesh.

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

{
  return _mesh;
}

get_num_results()

std::size_t libMesh::PointLocatorNanoflann::get_num_results

(

)

const

Set/get the number of results returned by each Nanoflann findNeighbors() search.

If a containing Elem (to within _contains_point_tol) is not found after linear searching the first _num_results Elems returned by Nanoflann, then we give up and return nullptr (or throw an error if not in out-of-mesh-mode).

Remarks: 1.) Although we do a linear search through the Nanoflann results, the Nanoflann results are always sorted by distance to the searched-for Point, so it's likely that the containing Elem will be found at the beginning of the linear search rather than the end. For nicely shaped elements, the containing Elem is often the first or second one found in the Nanoflann results.

2.) I'm not sure about the relative cost of requesting more results from the Nanoflann search than one actually needs, but presumably reducing _num_results will result in better performance for your particular application up to a point. If, on the other hand, _num_results is too small, then you risk having a false negative result, so take this into account when choosing the parameter for a particular application.

Definition at line 385 of file point_locator_nanoflann.C.

References _num_results.

{
  return _num_results;
}

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; }

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

void libMesh::PointLocatorNanoflann::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 71 of file point_locator_nanoflann.C.

References _elems, libMesh::PointLocatorBase::_initialized, _kd_tree, libMesh::PointLocatorBase::_master, libMesh::PointLocatorBase::_mesh, and _point_cloud.

Referenced by PointLocatorNanoflann().

{
  LOG_SCOPE("init()", "PointLocatorNanoflann");

  if (!_initialized)
    {
      // If _master == nullptr, then we _are_ the master, and thus
      // responsible for initializing.
      bool we_are_master = (_master == nullptr);

      // If we are the master PointLocator, fill in the _point_cloud
      // data structure with active, local element vertex averages.
      if (we_are_master)
        {
          _elems = std::make_shared<std::vector<const Elem *>>();
          _point_cloud = std::make_shared<std::vector<Point>>();

          // Make the KD-Tree out of active element vertex averages.
          //
          // Note: we use active elements rather than active+local
          // elements since we sometimes need to be able to locate
          // points in ghosted elements (for example in Periodic BCs).
          // Active elements are also natural to use in the
          // DistributedMesh case. The size of the KD-Tree on each
          // processor therefore scales with the number of elements on
          // each processor in either case.
          //
          // Note 2: the approximate amount of space we should reserve
          // here is going to be different for ReplicatedMesh
          // (n_active_elem()) vs. DistributedMesh (n_active_local_elem())
          // so we just let the containers resize themselves
          // automatically.
          for (const auto & elem : _mesh.active_element_ptr_range())
            {
              _elems->push_back(elem);
              _point_cloud->push_back(elem->vertex_average());
            }

          // Construct the KD-Tree
          _kd_tree = std::make_shared<kd_tree_t>
            (LIBMESH_DIM, *this, nanoflann::KDTreeSingleIndexAdaptorParams(/*max leaf=*/10));

          _kd_tree->buildIndex();
        }
      else // we are not master
        {
          // Cast the _master to the appropriate type, and point to
          // its data arrays.
          const auto my_master =
            cast_ptr<const PointLocatorNanoflann *>(this->_master);

          // Point our data structures at the master's
          _elems = my_master->_elems;
          _point_cloud = my_master->_point_cloud;
          _kd_tree = my_master->_kd_tree;
        }

      // We are initialized now
      this->_initialized = true;
    }
}

initialized()

bool libMesh::PointLocatorBase::initialized ( ) const

inherited

Returns

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

Definition at line 60 of file point_locator_base.C.

References libMesh::PointLocatorBase::_initialized.

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

{
  return this->_initialized;
}

kd_tree_find_neighbors()

nanoflann::KNNResultSet< Real > libMesh::PointLocatorNanoflann::kd_tree_find_neighbors ( const Point &  p, std::size_t  num_results  ) const

protected

Helper function that wraps the call to the KDTree's findNeighbors() routine.

Must be passed the Point to search for and the number of results to return. Stores the results of the search in the _ret_index and _out_dist_sqr class members and returns a KNNResultSet, which has pointers to the index and distance data.

Definition at line 134 of file point_locator_nanoflann.C.

References _kd_tree, _out_dist_sqr, and _ret_index.

Referenced by operator()().

{
  // We are searching for the Point(s) closest to Point p.
  //
  // TODO: The kd_tree's findNeighbors() routine needs a pointer to
  // Real of length LIBMESH_DIM. It might be convenient if libMesh
  // Points had a data() member that provided this, for now we just
  // copy the coordinates into a std::array of the appropriate size.
  std::array<Real, LIBMESH_DIM> query_pt;
  for (int i=0; i<LIBMESH_DIM; ++i)
    query_pt[i] = p(i);

  // Allocate storage for the indices and distances
  _ret_index.resize(num_results);
  _out_dist_sqr.resize(num_results);

  // nanoflann::KNNResultSet cannot be resized/reused easily, I think
  // it is just meant to be re-created for each search.
  nanoflann::KNNResultSet<Real> result_set(num_results);

  // Initialize the result_set
  result_set.init(_ret_index.data(), _out_dist_sqr.data());

  // Do the search
  // We leave all the SearchParams() ctor args on their default values
  // (note that the first arg is ignored anyway).
  _kd_tree->findNeighbors(result_set, query_pt.data(), nanoflann::SearchParameters());

  return result_set;
}

kdtree_distance()

PointLocatorNanoflann::coord_t libMesh::PointLocatorNanoflann::kdtree_distance	(	const coord_t *	p1,
		const std::size_t	idx_p2,
		std::size_t	size
	)		const

Returns the squared distance between the vector (p1[0], p1[1], p1[2]) and the vertex average of Elem "idx_p2" stored in _mesh.

Definition at line 411 of file point_locator_nanoflann.C.

References _point_cloud, and libMesh::TypeVector< T >::norm_sq().

{
  // We only consider LIBMESH_DIM dimensional KD-Trees, so just make
  // sure we were called consistently.
  libmesh_assert_equal_to(size, LIBMESH_DIM);

  // Construct a libmesh Point object from the LIBMESH_DIM-dimensional
  // input object, p1.
  Point point1;
  for (int i=0; i<LIBMESH_DIM; ++i)
    point1(i) = p1[i];

  // Compute Euclidean distance, squared
  return (point1 - (*_point_cloud)[idx_p2]).norm_sq();
}

kdtree_get_bbox()

template<class BBOX >

bool libMesh::PointLocatorNanoflann::kdtree_get_bbox ( BBOX &  ) const

inline

Optional bounding-box computation: return false to default to a standard bbox computation loop.

Return true if the BBOX can be computed more efficiently (and returned in "bb") than the standard bounding box computation. The BBOX template parameter must at least support bb.size() to find out the expected dimensionality of the box (e.g. 2 or 3 for point clouds).

Definition at line 196 of file point_locator_nanoflann.h.

{ return false; }

kdtree_get_point_count()

std::size_t libMesh::PointLocatorNanoflann::kdtree_get_point_count

(

)

const

Must return the number of data points.

Definition at line 403 of file point_locator_nanoflann.C.

References _point_cloud.

{
  return _point_cloud->size();
}

kdtree_get_pt()

PointLocatorNanoflann::coord_t libMesh::PointLocatorNanoflann::kdtree_get_pt	(	const std::size_t	idx,
		int	dim
	)		const

Returns the dim'th component of the idx'th vertex average.

Definition at line 432 of file point_locator_nanoflann.C.

References _point_cloud, dim, and libMesh::MeshTools::Generation::Private::idx().

{
  libmesh_assert_less (idx, _point_cloud->size());
  libmesh_assert_less (dim, LIBMESH_DIM);

  return (*_point_cloud)[idx](dim);
}

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 135 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::PointLocatorNanoflann::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.

Implements libMesh::PointLocatorBase.

Definition at line 169 of file point_locator_nanoflann.C.

References _b, libMesh::PointLocatorBase::_contains_point_tol, libMesh::PointLocatorBase::_initialized, _num_results, _out_dist_sqr, _out_of_mesh_mode, _ret_index, libMesh::PointLocatorBase::_use_contains_point_tol, libMesh::Elem::close_to_point(), libMesh::Elem::contains_point(), libMesh::Utility::iota(), kd_tree_find_neighbors(), libMesh::libmesh_assert(), libMesh::make_range(), and libMesh::Elem::subdomain_id().

{
  libmesh_assert (this->_initialized);

  LOG_SCOPE("operator()", "PointLocatorNanoflann");

  // Keep track of the number of elements checked in detail. This can
  // be useful for determining an optimal _num_results for
  // specific applications, by looking at the average and best/worse
  // case of each linear search.
  unsigned int n_elems_checked = 0;

  // If a containing Elem is found locally, we will set this pointer.
  const Elem * found_elem = nullptr;

  auto result_set = this->kd_tree_find_neighbors(p, _num_results);

  // The results from Nanoflann are already sorted by (squared)
  // distance, but within that list of results, there may be some
  // vertex averages which are equidistant from the searched-for
  // Point. Therefore, we will now indirect_sort the results based on
  // elem id, so that the lowest-id Elem from the class of Elems which
  // are the same distance away from the search Point is always
  // selected.

  // operator< comparison lambda used in the indirect sort.  The
  // inputs to this vector are indices of the result_set array.
  auto comp = [this](std::size_t lhs, std::size_t rhs) -> bool
    {
      // First we sort by squared distance
      if (_out_dist_sqr[lhs] < _out_dist_sqr[rhs])
        return true;
      if (_out_dist_sqr[rhs] < _out_dist_sqr[lhs])
        return false;

      // If we made it here without returning, then the Points were
      // equidistant, so we sort based on Elem id instead.
      auto nanoflann_index_lhs = _ret_index[lhs];
      auto elem_id_lhs = (*_elems)[nanoflann_index_lhs]->id();

      auto nanoflann_index_rhs = _ret_index[rhs];
      auto elem_id_rhs = (*_elems)[nanoflann_index_rhs]->id();

      if (elem_id_lhs < elem_id_rhs)
        return true;

      return false;
    };

  // Set up the indices and do the indirect sort. The results are
  // stored in _b so that _b[0] is the first result to check, _b[1]
  // is second, etc.
  _b.resize(result_set.size());
  std::iota(_b.begin(), _b.end(), 0);
  std::sort(_b.begin(), _b.end(), comp);

  // Note: we use result_set.size() here rather than
  // _num_results, in case the result returns fewer than
  // _num_results results!
  for (auto r : make_range(result_set.size()))
    {
      // Translate the Nanoflann index, which is from [0..n_points),
      // into the corresponding Elem id from the mesh. Note that we
      // use index _b[r] instead of r, since we want to process the
      // Elems in order based on Elem id.
      auto nanoflann_index = _ret_index[_b[r]];
      const Elem * candidate_elem = (*_elems)[nanoflann_index];

      // Debugging: print the results
      // libMesh::err << "Vertex average/Elem id = " << candidate_elem->id()
      //              << ", dist^2 = " << _out_dist_sqr[r]
      //              << std::endl;

      // Before we even check whether the candidate Elem actually
      // contains the Point, we may need to check whether the
      // candidate Elem is from an allowed subdomain.  If the
      // candidate Elem is not from an allowed subdomain, we continue
      // to the next one.
      if (allowed_subdomains && !allowed_subdomains->count(candidate_elem->subdomain_id()))
        {
          // Debugging
          // libMesh::err << "Elem " << candidate_elem->id() << " was not from an allowed subdomain, continuing search." << std::endl;
          continue;
        }

      // If we made it here, then the candidate Elem is from an
      // allowed subdomain, so let's next check whether it contains
      // the point. If the user set a custom tolerance, then we
      // actually check close_to_point() rather than contains_point(),
      // since this latter function warns about using non-default
      // tolerances, but otherwise does the same test.
      bool inside = _use_contains_point_tol ?
        candidate_elem->close_to_point(p, _contains_point_tol) :
        candidate_elem->contains_point(p);

      // Increment the number of elements checked
      n_elems_checked++;

      // If the point is inside an Elem from an allowed subdomain, we are done.
      if (inside)
        {
          // Debugging: report the number of Elems checked
          // libMesh::err << "Checked " << n_elems_checked << " nearby Elems before finding a containing Elem." << std::endl;

          found_elem = candidate_elem;
          break;
        }
    } // end for(r)

  // If we made it here, then at least one of the following happened:
  // .) All the candidate elements were from non-allowed subdomains.
  // .) The Point was not inside _any_ of the _num_results candidate Elems.
  // Thus, if we are not in _out_of_mesh_mode, throw an error,
  // otherwise return nullptr to indicate that no suitable element was
  // found.
  if (!_out_of_mesh_mode && !found_elem)
    {
      // Debugging: we are about to throw an error, but before we do,
      // print information about the closest elements (by vertex average
      // distance) that the Point was not found in.
      // for (auto r : make_range(result_set.size()))
      //   {
      //     auto nanoflann_index = _ret_index[_b[r]];
      //     const Elem * candidate_elem = (*_elems)[nanoflann_index];
      //
      //     libMesh::err << "Vertex average/Elem id = " << candidate_elem->id()
      //                  << ", dist = " << std::sqrt(_out_dist_sqr[_b[r]])
      //                  << std::endl;
      //   } // end for(r)


      libmesh_error_msg("Point " << p << " was not contained within the closest " << n_elems_checked <<
                        " elems (by vertex average distance), and _out_of_mesh_mode was not enabled.");
    }

  return found_elem;
}

operator()() [2/2]

void libMesh::PointLocatorNanoflann::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.

Optionally allows the user to restrict the subdomains searched. The idea here is that if a Point lies on the boundary between two elements, so that it is "in" both elements (to within some tolerance) then the candidate_elements set will contain both of these elements instead of just picking one or the other.

Implements libMesh::PointLocatorBase.

Definition at line 310 of file point_locator_nanoflann.C.

References libMesh::PointLocatorBase::_contains_point_tol, libMesh::PointLocatorBase::_initialized, _num_results, _ret_index, libMesh::PointLocatorBase::_use_contains_point_tol, libMesh::Elem::close_to_point(), libMesh::Elem::contains_point(), kd_tree_find_neighbors(), libMesh::libmesh_assert(), libMesh::make_range(), and libMesh::Elem::subdomain_id().

{
  libmesh_assert (this->_initialized);

  LOG_SCOPE("operator() returning set", "PointLocatorNanoflann");

  // Make sure the output set is initially empty
  candidate_elements.clear();

  // Keep track of the number of elements checked in detail
  // unsigned int n_elems_checked = 0;

  // Do the KD-Tree search
  auto result_set = this->kd_tree_find_neighbors(p, _num_results);

  for (auto r : make_range(result_set.size()))
    {
      // Translate the Nanoflann index, which is from [0..n_points),
      // into the corresponding Elem id from the mesh.
      auto nanoflann_index = _ret_index[r];
      const Elem * candidate_elem = (*_elems)[nanoflann_index];

      // Before we even check whether the candidate Elem actually
      // contains the Point, we may need to check whether the
      // candidate Elem is from an allowed subdomain.  If the
      // candidate Elem is not from an allowed subdomain, we continue
      // to the next one.
      if (allowed_subdomains && !allowed_subdomains->count(candidate_elem->subdomain_id()))
        continue;

      // If we made it here, then the candidate Elem is from an
      // allowed subdomain, so let's next check whether it contains
      // the point. If the user set a custom tolerance, then we
      // actually check close_to_point() rather than contains_point(),
      // since this latter function warns about using non-default
      // tolerances, but otherwise does the same test.
      bool inside = _use_contains_point_tol ?
        candidate_elem->close_to_point(p, _contains_point_tol) :
        candidate_elem->contains_point(p);

      // Increment the number of elements checked
      // n_elems_checked++;

      // If the point is contained in/close to an Elem from an
      // allowed subdomain, add it to the list.
      if (inside)
        candidate_elements.insert(candidate_elem);
    } // end for(r)

  // Debugging: for performance reasons, it may be useful to print the
  // number of Elems actually checked during the search.
  // libMesh::err << "Checked " << n_elems_checked << " nearby Elems before finding a containing Elem." << std::endl;
}

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 98 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 110 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_num_results()

void libMesh::PointLocatorNanoflann::set_num_results

(

std::size_t

val

)

Definition at line 393 of file point_locator_nanoflann.C.

References _num_results.

{
  // Must request at least 1 result
  _num_results = std::max(static_cast<std::size_t>(1), val);
}

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 104 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 116 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

_b

std::vector<std::size_t> libMesh::PointLocatorNanoflann::_b

mutableprotected

Vector of indices used by indirect sort.

Stored as a class member so we don't have to allocate it from scratch for every search.

Definition at line 244 of file point_locator_nanoflann.h.

Referenced by operator()().

_close_to_point_tol

Real libMesh::PointLocatorBase::_close_to_point_tol

protectedinherited

The tolerance to use.

Definition at line 231 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_close_to_point_tol(), libMesh::PointLocatorTree::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 242 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_contains_point_tol(), operator()(), libMesh::PointLocatorTree::operator()(), libMesh::PointLocatorTree::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().

_elems

std::shared_ptr<std::vector<const Elem *> > libMesh::PointLocatorNanoflann::_elems

protected

Lists of Points and ids which make up the "point cloud" that is to be searched via Nanoflann.

The point cloud can be comprised of Elem vertex averages or mesh Nodes, depending on the type of tree created. We keep two separate vectors since the Points in the cloud may not be numbered contiguously in general.

These are shared_ptrs to vectors since, if we are not the "master" PointLocator, they need to point at the master's vectors instead.

Definition at line 222 of file point_locator_nanoflann.h.

Referenced by clear(), and init().

_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 220 of file point_locator_base.h.

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

_kd_tree

std::shared_ptr<kd_tree_t> libMesh::PointLocatorNanoflann::_kd_tree

protected

Definition at line 230 of file point_locator_nanoflann.h.

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

_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 210 of file point_locator_base.h.

Referenced by libMesh::PointLocatorTree::init(), 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 215 of file point_locator_base.h.

Referenced by libMesh::PointLocatorBase::get_mesh(), libMesh::PointLocatorTree::init(), init(), libMesh::PointLocatorTree::perform_fuzzy_linear_search(), and libMesh::PointLocatorTree::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().

_num_results

std::size_t libMesh::PointLocatorNanoflann::_num_results

protected

The number of results returned by Nanoflann when operator() is called.

Definition at line 210 of file point_locator_nanoflann.h.

Referenced by get_num_results(), operator()(), and set_num_results().

_out_dist_sqr

std::vector<Real> libMesh::PointLocatorNanoflann::_out_dist_sqr

mutableprotected

Definition at line 238 of file point_locator_nanoflann.h.

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

_out_of_mesh_mode

bool libMesh::PointLocatorNanoflann::_out_of_mesh_mode

protected

true if out-of-mesh mode is enabled.

See enable_out_of_mesh_mode() for details.

Definition at line 204 of file point_locator_nanoflann.h.

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

_point_cloud

std::shared_ptr<std::vector<Point> > libMesh::PointLocatorNanoflann::_point_cloud

protected

Definition at line 223 of file point_locator_nanoflann.h.

Referenced by clear(), init(), kdtree_distance(), kdtree_get_point_count(), and kdtree_get_pt().

_ret_index

std::vector<std::size_t> libMesh::PointLocatorNanoflann::_ret_index

mutableprotected

The operator() functions on PointLocator-derived classes are const, so to avoid re-allocating these result data structures every time operator() is called, they have to be mutable.

Definition at line 237 of file point_locator_nanoflann.h.

Referenced by kd_tree_find_neighbors(), 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 226 of file point_locator_base.h.

Referenced by libMesh::PointLocatorTree::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 237 of file point_locator_base.h.

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

_verbose

bool libMesh::PointLocatorBase::_verbose

inherited

Boolean flag to indicate whether to print out extra info.

Definition at line 202 of file point_locator_base.h.

Referenced by libMesh::PointLocatorTree::operator()().

---

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

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