Line data    Source code

       1             : // The libMesh Finite Element Library.
       2             : // Copyright (C) 2002-2025 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
       3             : 
       4             : // This library is free software; you can redistribute it and/or
       5             : // modify it under the terms of the GNU Lesser General Public
       6             : // License as published by the Free Software Foundation; either
       7             : // version 2.1 of the License, or (at your option) any later version.
       8             : 
       9             : // This library is distributed in the hope that it will be useful,
      10             : // but WITHOUT ANY WARRANTY; without even the implied warranty of
      11             : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      12             : // Lesser General Public License for more details.
      13             : 
      14             : // You should have received a copy of the GNU Lesser General Public
      15             : // License along with this library; if not, write to the Free Software
      16             : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
      17             : 
      18             : 
      19             : 
      20             : #ifndef LIBMESH_POINT_LOCATOR_BASE_H
      21             : #define LIBMESH_POINT_LOCATOR_BASE_H
      22             : 
      23             : // Local Includes
      24             : #include "libmesh/reference_counted_object.h"
      25             : #include "libmesh/libmesh_common.h"
      26             : 
      27             : // C++ includes
      28             : #include <cstddef>
      29             : #include <memory>
      30             : #include <set>
      31             : #include <vector>
      32             : 
      33             : namespace libMesh
      34             : {
      35             : 
      36             : // Forward Declarations
      37             : class PointLocatorBase;
      38             : class MeshBase;
      39             : class Point;
      40             : class TreeBase;
      41             : class Elem;
      42             : class Node;
      43             : enum PointLocatorType : int;
      44             : 
      45             : 
      46             : /**
      47             :  * This is the base class for point locators.  They locate
      48             :  * points in space: given a mesh they return the element
      49             :  * and local coordinates for a given point in global coordinates.
      50             :  *
      51             :  * \author Daniel Dreyer
      52             :  * \date 2003
      53             :  */
      54      112598 : class PointLocatorBase : public ReferenceCountedObject<PointLocatorBase>
      55             : {
      56             : protected:
      57             :   /**
      58             :    * Constructor.  Protected so that this base class
      59             :    * cannot be explicitly instantiated.  Takes a master
      60             :    * PointLocator that helps in saving memory.
      61             :    */
      62             :   PointLocatorBase (const MeshBase & mesh,
      63             :                     const PointLocatorBase * master);
      64             : 
      65             : public:
      66             :   /**
      67             :    * Destructor.
      68             :    */
      69             :   virtual ~PointLocatorBase ();
      70             : 
      71             :   /**
      72             :    * Builds an PointLocator for the mesh \p mesh.
      73             :    * Optionally takes a master PointLocator to save memory.
      74             :    * An \p std::unique_ptr<PointLocatorBase> is returned to prevent memory leak.
      75             :    * This way the user need not remember to delete the object.
      76             :    */
      77             :   static std::unique_ptr<PointLocatorBase> build (PointLocatorType t,
      78             :                                                   const MeshBase & mesh,
      79             :                                                   const PointLocatorBase * master = nullptr);
      80             : 
      81             :   /**
      82             :    * Clears the \p PointLocator.
      83             :    */
      84             :   virtual void clear() = 0;
      85             : 
      86             :   /**
      87             :    * Initializes the point locator, so that the \p operator() methods can
      88             :    * be used.  Pure virtual.
      89             :    */
      90             :   virtual void init() = 0;
      91             : 
      92             :   /**
      93             :    * Locates the element in which the point with global coordinates
      94             :    * \p p is located.  Pure virtual. Optionally allows the user to restrict
      95             :    * the subdomains searched.
      96             :    */
      97             :   virtual const Elem * operator() (const Point & p,
      98             :                                    const std::set<subdomain_id_type> * allowed_subdomains = nullptr) const = 0;
      99             : 
     100             :   /**
     101             :    * Finds elements in proximity to the point with global coordinates
     102             :    * \p p and adds them to a set of candidate elements.  Pure virtual.
     103             :    * Optionally allows the user to restrict the subdomains searched.
     104             :    */
     105             :   virtual void operator() (const Point & p,
     106             :                            std::set<const Elem *> & candidate_elements,
     107             :                            const std::set<subdomain_id_type> * allowed_subdomains = nullptr) const = 0;
     108             : 
     109             :   /**
     110             :    * \returns A pointer to a Node with global coordinates \p p or \p
     111             :    * nullptr if no such Node can be found.
     112             :    *
     113             :    * Virtual subclasses can override for efficiency, but the base
     114             :    * class has a default implementation that works based on element
     115             :    * lookup.
     116             :    *
     117             :    * Optionally allows the user to restrict the subdomains searched;
     118             :    * with such a restriction, only a Node belonging to an element on
     119             :    * one or more of those subdomains will be returned.
     120             :    *
     121             :    * Will only return a Node whose distance from \p p is less than
     122             :    * \p tol multiplied by the size of a semilocal element which
     123             :    * contains \p p.
     124             :    */
     125             :   virtual const Node *
     126             :   locate_node (const Point & p,
     127             :                const std::set<subdomain_id_type> * allowed_subdomains = nullptr,
     128             :                Real tol = TOLERANCE) const;
     129             : 
     130             :   /**
     131             :    * \returns \p true when this object is properly initialized
     132             :    * and ready for use, \p false otherwise.
     133             :    */
     134             :   bool initialized () const;
     135             : 
     136             :   /**
     137             :    * Enables out-of-mesh mode.  In this mode, if asked to find a point
     138             :    * that is contained in no mesh at all, the point locator will
     139             :    * return a nullptr instead of crashing.  Per default, this
     140             :    * mode is off.
     141             :    */
     142             :   virtual void enable_out_of_mesh_mode () = 0;
     143             : 
     144             :   /**
     145             :    * Disables out-of-mesh mode (default).  If asked to find a point
     146             :    * that is contained in no mesh at all, the point locator will now
     147             :    * crash.
     148             :    */
     149             :   virtual void disable_out_of_mesh_mode () = 0;
     150             : 
     151             :   /**
     152             :    * Get the close-to-point tolerance.
     153             :    */
     154             :   Real get_close_to_point_tol() const;
     155             : 
     156             :   /**
     157             :    * Set a tolerance to use when determining
     158             :    * if a point is contained within the mesh.
     159             :    */
     160             :   virtual void set_close_to_point_tol(Real close_to_point_tol);
     161             : 
     162             :   /**
     163             :    * Specify that we do not want to use a user-specified tolerance to
     164             :    * determine if a point is contained within the mesh.
     165             :    */
     166             :   virtual void unset_close_to_point_tol();
     167             : 
     168             :   /**
     169             :    * Set a tolerance to use when checking
     170             :    * if a point is within an element in the mesh.
     171             :    */
     172             :   virtual void set_contains_point_tol(Real contains_point_tol);
     173             : 
     174             :   /**
     175             :    * Specify that we do not want to use a user-specified tolerance to
     176             :    * determine if a point is inside an element in the mesh.
     177             :    */
     178             :   virtual void unset_contains_point_tol();
     179             : 
     180             :   /**
     181             :    * Get the tolerance for determining element containment
     182             :    * in the point locator.
     183             :    */
     184             :   virtual Real get_contains_point_tol() const;
     185             : 
     186             :   /**
     187             :    * The contains_point_tol may be nonzero (in fact it defaults to
     188             :    * non-zero) but unless the user calls set_contains_point_tol(), it
     189             :    * won't actually be *used*. This const accessor can be used to
     190             :    * determine the current status of this flag.
     191             :    */
     192             :   bool get_use_contains_point_tol() const { return _use_contains_point_tol; }
     193             : 
     194             :   /**
     195             :    * Get a const reference to this PointLocator's mesh.
     196             :    */
     197             :   const MeshBase & get_mesh() const;
     198             : 
     199             :   /**
     200             :    * Boolean flag to indicate whether to print out extra info.
     201             :    */
     202             :   bool _verbose;
     203             : 
     204             : protected:
     205             :   /**
     206             :    * Const pointer to our master, initialized to \p nullptr if none
     207             :    * given.  When using multiple PointLocators, one can be assigned
     208             :    * master and be in charge of something that all can have access to.
     209             :    */
     210             :   const PointLocatorBase * _master;
     211             : 
     212             :   /**
     213             :    * constant reference to the mesh in which the point is looked for.
     214             :    */
     215             :   const MeshBase & _mesh;
     216             : 
     217             :   /**
     218             :    * \p true when properly initialized, \p false otherwise.
     219             :    */
     220             :   bool _initialized;
     221             : 
     222             :   /**
     223             :    * \p true if we will use a user-specified tolerance for locating
     224             :    * the element in an exhaustive search.
     225             :    */
     226             :   bool _use_close_to_point_tol;
     227             : 
     228             :   /**
     229             :    * The tolerance to use.
     230             :    */
     231             :   Real _close_to_point_tol;
     232             : 
     233             :   /**
     234             :    * \p true if we will use a user-specified tolerance for locating
     235             :    * the element.
     236             :    */
     237             :   bool _use_contains_point_tol;
     238             : 
     239             :   /**
     240             :    * The tolerance to use when locating an element in the tree.
     241             :    */
     242             :   Real _contains_point_tol;
     243             : };
     244             : 
     245             : } // namespace libMesh
     246             : 
     247             : #endif // LIBMESH_POINT_LOCATOR_BASE_H