mesh_refinement.h

Go to the documentation of this file.

// The libMesh Finite Element Library.
// Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
 
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
 
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
 
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
 
 
#ifndef LIBMESH_MESH_REFINEMENT_H
#define LIBMESH_MESH_REFINEMENT_H
 
 
 
#include "libmesh/libmesh_config.h"
 
#ifdef LIBMESH_ENABLE_AMR
 
// Local Includes
#include "libmesh/libmesh_common.h"
#include "libmesh/libmesh.h" // libMesh::invalid_uint
#include "libmesh/topology_map.h"
#include "libmesh/parallel_object.h"
 
// C++ Includes
#include <vector>
 
namespace libMesh
{
 
// Forward Declarations
class MeshBase;
class Point;
class Node;
class ErrorVector;
class PeriodicBoundaries;
class Elem;
class PointLocatorBase;
 
class MeshRefinement : public ParallelObject
{
public:
 
  explicit
  MeshRefinement (MeshBase & mesh);
 
private:
  // Both the copy ctor and the assignment operator are
  // declared private but not implemented.  This is the
  // standard practice to prevent them from being used.
  MeshRefinement (const MeshRefinement &);
  MeshRefinement & operator=(const MeshRefinement &);
 
public:
 
  class ElementFlagging
  {
  public:
    virtual ~ElementFlagging () = default;
 
    virtual void flag_elements () = 0;
  };
 
  void set_periodic_boundaries_ptr(PeriodicBoundaries * pb_ptr);
 
  ~MeshRefinement ();
 
  void clear ();
 
  void flag_elements_by_error_fraction (const ErrorVector & error_per_cell,
                                        const Real refine_fraction  = 0.3,
                                        const Real coarsen_fraction = 0.0,
                                        const unsigned int max_level = libMesh::invalid_uint);
 
  void flag_elements_by_error_tolerance (const ErrorVector & error_per_cell);
 
  bool flag_elements_by_nelem_target (const ErrorVector & error_per_cell);
 
  void flag_elements_by_elem_fraction (const ErrorVector & error_per_cell,
                                       const Real refine_fraction  = 0.3,
                                       const Real coarsen_fraction = 0.0,
                                       const unsigned int max_level = libMesh::invalid_uint);
 
  void flag_elements_by_mean_stddev (const ErrorVector & error_per_cell,
                                     const Real refine_fraction  = 1.0,
                                     const Real coarsen_fraction = 0.0,
                                     const unsigned int max_level = libMesh::invalid_uint);
 
  void flag_elements_by (ElementFlagging & element_flagging);
 
  void switch_h_to_p_refinement();
 
  void add_p_to_h_refinement();
 
  bool refine_and_coarsen_elements ();
 
  bool coarsen_elements ();
 
  bool refine_elements ();
 
  void uniformly_refine (unsigned int n=1);
 
  void uniformly_coarsen (unsigned int n=1);
 
  void uniformly_p_refine (unsigned int n=1);
 
  void uniformly_p_coarsen (unsigned int n=1);
 
  void clean_refinement_flags ();
 
  bool test_level_one (bool libmesh_assert_yes = false) const;
 
  bool test_unflagged (bool libmesh_assert_yes = false) const;
 
  Node * add_node (Elem & parent,
                   unsigned int child,
                   unsigned int node,
                   processor_id_type proc_id);
 
  Elem * add_elem (Elem * elem);
 
  Elem * add_elem (std::unique_ptr<Elem> elem);
 
  const MeshBase & get_mesh () const { return _mesh; }
 
  MeshBase & get_mesh () { return _mesh; }
 
  bool & coarsen_by_parents();
 
  Real & refine_fraction();
 
  Real & coarsen_fraction();
 
  unsigned int & max_h_level();
 
  Real & coarsen_threshold();
 
  dof_id_type & nelem_target();
 
  Real & absolute_global_tolerance();
 
  unsigned char & face_level_mismatch_limit();
 
  unsigned char & edge_level_mismatch_limit();
 
  unsigned char & node_level_mismatch_limit();
 
  signed char & overrefined_boundary_limit();
 
  signed char & underrefined_boundary_limit();
 
  bool & allow_unrefined_patches();
 
  bool make_flags_parallel_consistent ();
 
  bool & enforce_mismatch_limit_prior_to_refinement();
  bool enforce_mismatch_limit_prior_to_refinement() const;
  void enforce_mismatch_limit_prior_to_refinement(bool enforce);
 
private:
 
  bool _coarsen_elements ();
 
  bool _refine_elements ();
 
  void _smooth_flags (bool refining, bool coarsening);
 
  //------------------------------------------------------
  // "Smoothing" algorithms for refined meshes
 
  bool limit_level_mismatch_at_node (const unsigned int max_mismatch);
 
  /*
   * This algorithm restricts the maximum level mismatch
   * at any edge in the mesh.  See the ASCII art in the comment of
   * limit_level_mismatch_at_node, and pretend they're hexes.
   */
  bool limit_level_mismatch_at_edge (const unsigned int max_mismatch);
 
  /*
   * This algorithm flags interior elements for refinement as needed
   * to prevent corresponding boundary element refinement mismatch
   * from exceeding the given limit.
   */
  bool limit_overrefined_boundary (const signed char max_mismatch);
 
  /*
   * This algorithm flags boundary elements for refinement as needed
   * to prevent corresponding interior element refinement mismatch
   * from exceeding the given limit.
   */
  bool limit_underrefined_boundary (const signed char max_mismatch);
 
  bool eliminate_unrefined_patches ();
 
 
  //---------------------------------------------
  // Utility algorithms
 
  void create_parent_error_vector (const ErrorVector & error_per_cell,
                                   ErrorVector & error_per_parent,
                                   Real & parent_error_min,
                                   Real & parent_error_max);
 
  void update_nodes_map ();
 
  bool make_coarsening_compatible ();
 
  bool make_refinement_compatible ();
 
  Elem * topological_neighbor (Elem * elem,
                               const PointLocatorBase * point_locator,
                               const unsigned int side) const;
 
  bool has_topological_neighbor (const Elem * elem,
                                 const PointLocatorBase * point_locator,
                                 const Elem * neighbor) const;
 
  TopologyMap _new_nodes_map;
 
  MeshBase & _mesh;
 
  bool _use_member_parameters;
 
  bool _coarsen_by_parents;
 
  Real _refine_fraction;
 
  Real _coarsen_fraction;
 
  unsigned int _max_h_level;
 
  Real _coarsen_threshold;
 
  dof_id_type _nelem_target;
 
  Real _absolute_global_tolerance;
 
  unsigned char _face_level_mismatch_limit;
  unsigned char _edge_level_mismatch_limit;
  unsigned char _node_level_mismatch_limit;
 
  signed char _overrefined_boundary_limit;
  signed char _underrefined_boundary_limit;
 
  bool _allow_unrefined_patches;
 
  bool _enforce_mismatch_limit_prior_to_refinement;
 
  enum NeighborType {POINT, EDGE};
  bool enforce_mismatch_limit_prior_to_refinement(Elem * elem,
                                                  NeighborType nt,
                                                  unsigned max_mismatch);
 
#ifdef LIBMESH_ENABLE_PERIODIC
  PeriodicBoundaries * _periodic_boundaries;
#endif
};
 
 
 
// ------------------------------------------------------------
// MeshRefinement class inline members
 
inline bool & MeshRefinement::coarsen_by_parents()
{
  _use_member_parameters = true;
  return _coarsen_by_parents;
}
 
inline Real & MeshRefinement::refine_fraction()
{
  _use_member_parameters = true;
  return _refine_fraction;
}
 
inline Real & MeshRefinement::coarsen_fraction()
{
  _use_member_parameters = true;
  return _coarsen_fraction;
}
 
inline unsigned int & MeshRefinement::max_h_level()
{
  _use_member_parameters = true;
  return _max_h_level;
}
 
inline Real & MeshRefinement::coarsen_threshold()
{
  _use_member_parameters = true;
  return _coarsen_threshold;
}
 
inline dof_id_type & MeshRefinement::nelem_target()
{
  _use_member_parameters = true;
  return _nelem_target;
}
 
inline Real & MeshRefinement::absolute_global_tolerance()
{
  _use_member_parameters = true;
  return _absolute_global_tolerance;
}
 
inline unsigned char & MeshRefinement::face_level_mismatch_limit()
{
  return _face_level_mismatch_limit;
}
 
inline unsigned char & MeshRefinement::edge_level_mismatch_limit()
{
  return _edge_level_mismatch_limit;
}
 
inline unsigned char & MeshRefinement::node_level_mismatch_limit()
{
  return _node_level_mismatch_limit;
}
 
inline signed char & MeshRefinement::overrefined_boundary_limit()
{
  return _overrefined_boundary_limit;
}
 
inline signed char & MeshRefinement::underrefined_boundary_limit()
{
  return _underrefined_boundary_limit;
}
 
inline bool & MeshRefinement::allow_unrefined_patches()
{
  return _allow_unrefined_patches;
}
 
inline bool & MeshRefinement::enforce_mismatch_limit_prior_to_refinement()
{
  return _enforce_mismatch_limit_prior_to_refinement;
}
 
inline bool
MeshRefinement::enforce_mismatch_limit_prior_to_refinement() const
{
  return _enforce_mismatch_limit_prior_to_refinement;
}
 
inline void
MeshRefinement::enforce_mismatch_limit_prior_to_refinement(bool enforce)
{
  _enforce_mismatch_limit_prior_to_refinement = enforce;
}
 
 
 
} // namespace libMesh
 
#endif // end #ifdef LIBMESH_ENABLE_AMR
#endif // LIBMESH_MESH_REFINEMENT_H